From Vim Tips Wiki

Tip 31 Previous Tip • Next Tip

Created: March 7, 2001 Complexity: basic Author: Anon Minimum version: 5.7 Karma: 1178/444 Imported from: Tip#31

---

Use the :substitute command to search for a text pattern, and replace it with a text string.

There are many options, but these are what you most probably want:

:%s/foo/bar/g

Find each occurrence of 'foo', and replace it with 'bar'.

:%s/foo/bar/gc

Change each 'foo' to 'bar', but ask for confirmation first.

:%s/\<foo\>/bar/gc

Change only whole words exactly matching 'foo' to 'bar'; ask for confirmation.

:%s/foo/bar/gci

Change each 'foo' (case insensitive) to 'bar'; ask for confirmation.

:%s/foo/bar/gcI

Change each 'foo' (case sensitive) to 'bar'; ask for confirmation.

The g flag means global — each occurrence in the line is changed, rather than just the first.

Search range:

The % in :%s applies the substitute to every line in the buffer, rather than just the current line.

:5,12s/foo/bar/g will change each 'foo' to 'bar' for all lines between line 5 and line 12.

:'a,'bs/foo/bar/g will change each 'foo' to 'bar' for all lines between marks a and b.

:.,$s/foo/bar/g will change each 'foo' to 'bar' for all lines between the current line (.) and the last line ($).

:.,+2s/foo/bar/g will change each 'foo' to 'bar' for the current line (.) and the two next lines (+2).

(Note that :%s is equivalent to :1,$s.)

When searching:

\/ is / (use backslash + forward slash to search for forward slash)

\t is tab, \s is whitespace

\n is newline, \r is CR (carriage return = Ctrl-M = ^M)

When replacing:

\r is newline, \n is a null byte (0x00).

\& is ampersand (& is the search pattern).

You can use other delimiters with substitute:

:s#http://www.example.com/index.html#http://example.com/#

This can be a very helpful technique, because you can avoid escaping a / character if you use something other than / for a delimiter, and some delimiters such as ; may be faster/easier to type.

Save typing by using \zs and \ze to set the start and end of a pattern. For example, instead of:

:s/Copyright 2007 All Rights Reserved/Copyright 2008 All Rights Reserved/

You could try:

:s/Copyright \zs2007\ze All Rights Reserved/2008/

[edit] Using registers

:%s/foo/<c-r>a/g

Substitute each 'foo' by the content of register 'a'.

<c-r>a means: Press Ctrl-R then A. The content of register 'a' will be immediately inserted.

:%s/foo/\=@a/g

Substitute each 'foo' by the content of register 'a'.

\=@a is a reference to register 'a'. The content of register 'a' will not be shown. This is useful if register 'a' contains many lines of text.

:%s/<c-r>//bar/g

Substitute the last search pattern (<c-r>/) by 'bar'.

Hint: If the substitute pattern is omitted, the last search pattern is used. See 'r' flag.

:%s/<c-r>*/bar/g

Substitute the visual selection (saved in the '*' register) by 'bar'.

See Paste registers in search or colon commands instead of using the clipboard.

[edit] Special cases

For substituting patterns with a corresponding case-sensitive text, Michael Geddes's keepcase plugin can be used, e.g.:

:%SubstituteCase/\cHello/goodBye/g

Substitute 'Hello hello helLo HELLO' by 'Goodbye goodbye goodBye GOODBYE'

[edit] See also – using substitute

• 63 Applying substitutes to a visual block
• 81 Substitute characters and lines easily
• 159 Keystroke Saving Substituting and Searching
• 406 Alternate delimiters for the replace command
• 438 Search and replace in a visual selection
• 464 Search and replace the word under the cursor
• 479 Replace with no typing
• 573 Repeating a substitute from current cursor position
• 605 Replace a word with the yanked text
• 654 Special characters in the substitute command
• 755 Using an expression in substitute command
• 808 Replace a visual-block of text with another such block
• 877 Replace all commas with new lines
• 915 Using g instead of substitute
• 971 Substitute with incrementing numbers
• 1114 Step increment and replace
• 1196 Replace text to register content with visual selection help
• 1501 Substitute last search

[edit] See also – substitute in buffers/files

• 324 Search and replace in files named NAME
• 373 Run find/replace/search on multiple files and subdirectories
• 382 Search and replace in all open buffers
• 1512 Search and replace in all buffers

[edit] References

• :help :substitute
• :help cmdline-ranges
• :help pattern
• :help 'gdefault'
• :help registers

[edit] Comments

 TO DO 
The large "see also" section may be useful to readers. We need to merge some of the related tips (but don't make the result too complex). I included the tip numbers to help editors keep track.

[edit] Open questions

• Is it possible to use a register as a search pattern? E.g. replace the content of register 'a' by the content of register 'b':

:%s/\=@a/\=@b/g (doesn't work)

AFAIK, we can't use expressions as the {pattern} parameter of :substitute. Actually, using registers is just a special case of the general use of expression. \= is about using a dynamic expression as the replacement {string}. See :help sub-replace-special

--Luc Hermitte 11:59, 7 September 2007 (UTC)

• If the content of register 'a' is inserted by <c-r>a, the above task can be accomplished. However, if register 'a' contains line breaks, they are inserted as ^M and not found. If they are manually replaced by '\n', they are found correctly.

Then use <c-r>=substitute(@a, "\n", '\\n', "g") instead of <c-r>a

--Luc Hermitte 11:59, 7 September 2007 (UTC)

---

• Is it possible to search for a partial word and then replace by typing? e.g. search for "foo" and then replace by typing "bar" in one match and replace by typing "zoo" in another match.