Home • Explore • Blog • CI
☰



neovim
11th chunk of `runtime/doc/change.txt`
7197a0fc9e85b8113cc71f122eea8e723715ed3bb6d8cebe0000000100000fa2
 In Visual block mode, use
|/\%V| in the pattern to have the substitute work in the block only.
Otherwise it works on whole lines anyway.

					*sub-replace-special* *:s\=*
When the {string} starts with "\=" it is evaluated as an expression, see
|sub-replace-expression|.  You can use that for complex replacement or special
characters.

The substitution is limited in recursion to 4 levels. *E1290*

Otherwise these characters in {string} have a special meaning:

magic	nomagic	  action    ~
  &	  \&	  replaced with the whole matched pattern	     *s/\&*
 \&	   &	  replaced with &
      \0	  replaced with the whole matched pattern	   *\0* *s/\0*
      \1	  replaced with the matched pattern in the first
		  pair of ()					     *s/\1*
      \2	  replaced with the matched pattern in the second
		  pair of ()					     *s/\2*
      ..	  ..						     *s/\3*
      \9	  replaced with the matched pattern in the ninth
		  pair of ()					     *s/\9*
  ~	  \~	  replaced with the {string} of the previous
		  substitute					     *s~*
 \~	   ~	  replaced with ~				     *s/\~*
      \u	  next character made uppercase			     *s/\u*
      \U	  following characters made uppercase, until \E      *s/\U*
      \l	  next character made lowercase			     *s/\l*
      \L	  following characters made lowercase, until \E      *s/\L*
      \e	  end of \u, \U, \l and \L (NOTE: not <Esc>!)	     *s/\e*
      \E	  end of \u, \U, \l and \L			     *s/\E*
      <CR>	  split line in two at this point
		  (Type the <CR> as CTRL-V <Enter>)		     *s<CR>*
      \r	  idem						     *s/\r*
      \<CR>	  insert a carriage-return (CTRL-M)
		  (Type the <CR> as CTRL-V <Enter>)		     *s/\<CR>*
      \n	  insert a <NL> (<NUL> in the file)
		  (does NOT break the line)			     *s/\n*
      \b	  insert a <BS>					     *s/\b*
      \t	  insert a <Tab>				     *s/\t*
      \\	  insert a single backslash			     *s/\\*
      \x	  where x is any character not mentioned above:
		  Reserved for future expansion

The special meaning is also used inside the third argument {sub} of
the |substitute()| function with the following exceptions:
  - A % inserts a percent literally without regard to 'cpoptions'.
  - magic is always set without regard to 'magic'.
  - A ~ inserts a tilde literally.
  - <CR> and \r inserts a carriage-return (CTRL-M).
  - \<CR> does not have a special meaning. It's just one of \x.

Examples: >
  :s/a\|b/xxx\0xxx/g		 modifies "a b"	     to "xxxaxxx xxxbxxx"
  :s/\([abc]\)\([efg]\)/\2\1/g	 modifies "af fa bg" to "fa fa gb"
  :s/abcde/abc^Mde/		 modifies "abcde"    to "abc", "de" (two lines)
  :s/$/\^M/			 modifies "abcde"    to "abcde^M"
  :s/\w\+/\u\0/g		 modifies "bla bla"  to "Bla Bla"
  :s/\w\+/\L\u\0/g		 modifies "BLA bla"  to "Bla Bla"

Note: "\L\u" can be used to capitalize the first letter of a word.  This is
not compatible with Vi and older versions of Vim, where the "\u" would cancel
out the "\L". Same for "\U\l".

Note: In previous versions CTRL-V was handled in a special way.  Since this is
not Vi compatible, this was removed.  Use a backslash instead.

command		text	result ~
:s/aa/a^Ma/	aa	a<line-break>a
:s/aa/a\^Ma/	aa	a^Ma
:s/aa/a\\^Ma/	aa	a\<line-break>a

(you need to type CTRL-V <CR> to get a ^M here)

The numbering of "\1", "\2" etc. is done based on which "\(" comes first in
the pattern (going left to right).  When a parentheses group matches several
times, the last one will be used for "\1", "\2", etc.  Example: >
  :s/\(\(a[a-d] \)*\)/\2/      modifies "aa ab x" to "ab x"
The "\2" is for "\(a[a-d] \)".  At first it matches "aa ", secondly "ab ".

When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\),
either the first or second pattern in parentheses did not match, so either
\1 or \2 is empty.  Example: >
  :s/\([ab]\)\|\([cd]\)/\1x/g   modifies "a b c d"  to "ax bx x x"
<

		*:sc* *:sce* *:scg* *:sci* *:scI* *:scl* *:scp* *:sg* *:sgc*
		*:sge* *:sgi* *:sgI* *:sgl* *:sgn* *:sgp* *:sgr* *:sI* *:si*
		*:sic* *:sIc* *:sie* *:sIe* *:sIg*
Title: Vim Substitute Command: Special Characters and Examples
Summary
This section describes special characters in the substitute string, including '&' (whole matched pattern), '\0' (whole matched pattern), '\1' - '\9' (captured groups), '~' (previous substitute string), '\u'/\U' (uppercase), '\l'/\L' (lowercase), '\e'/\E' (end case modification), '<CR>'/'\r' (split line), '\n' (newline), '\b' (backspace), '\t' (tab), and '\\' (backslash). It includes how these characters work in the `substitute()` function and provides examples of using these characters in substitute commands. It covers Visual mode substitutions, expression evaluation with `\=`, and limitations on recursion.