286

From question How to replace a character for a newline in Vim?. You have to use \r when replacing text for a newline, like this

:%s/%/\r/g

But when replacing end of lines and newlines for a character, you can do it like:

:%s/\n/%/g 

What section of the manual documents these behaviors, and what's the reasoning behind them?

3
  • 1
    What is the % for when searching and replacing?
    – qed
    Oct 21, 2013 at 20:12
  • 9
    @qed: by default :s will only apply the substitution to the current line. :%s makes it address the whole file. More.
    – c24w
    Jan 6, 2014 at 14:09
  • 5
    +c24w I think he is referring to the '%' between the slashes, the first example the '%' being in the search location, and in the replace location in the second example, but @qed to answer your question, those '%'s are matched literally.
    – RastaJedi
    Aug 24, 2016 at 2:57

5 Answers 5

239

From http://vim.wikia.com/wiki/Search_and_replace :

When Searching

...

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

When Replacing

...

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

5
  • 8
    This answer helped me the most. Also, for more information, :h :s%, especially the last paragraph. (via :h :s)
    – dipnlik
    Oct 20, 2014 at 12:56
  • i wrote about that in even more depth - stackoverflow.com/a/18961239/805284
    – sjas
    Jul 31, 2020 at 14:18
  • Yes, you wrote more, but I don't think you added anything material. Aug 1, 2020 at 15:13
  • 2
    but WHY........
    – IceFire
    Jul 21, 2023 at 15:06
  • @IceFire Excellent question. I have no idea (even 13 years later). It's just one more "grey-beard" thing we have to memorize to make ourselves into the GNU/Linux sages we revere. :sigh: Jul 24, 2023 at 3:46
157

From vim docs on patterns:

\r matches <CR>

\n matches an end-of-line - When matching in a string instead of buffer text a literal newline character is matched.

3
  • 48
    For me the point of confusion is that \r and \n mean different things when used is the search pattern and the replacement pattern.
    – dlamblin
    Dec 4, 2012 at 17:09
  • 3
    @dlamblin Yup! See my answer :) Jun 28, 2014 at 1:54
  • 1
    The question in the title is "why" and this is not answered
    – IceFire
    Jul 21, 2023 at 15:07
143

Another aspect to this is that \0, which is traditionally NULL, is taken in s//\0/ to mean "the whole matched pattern". (Which, by the way, is redundant with, and longer than, &).

  • So you can't use \0 to mean NULL, so you use \n
  • So you can't use \n to mean \n, so you use \r.
  • So you can't use \r to mean \r, but I don't know who would want to add that char on purpose.

—☈

4
  • 1
    Good point! So this is a hack around \0 - backreference to 0-th nested group - whole regexp. This is a very good answer, but it makes me dissapointed, that I can't use \r in replacement... (meaning: insert #(13), for example in a "normal" file (== unix EOLs). Nov 6, 2013 at 9:54
  • 3
    OK, the answer is in the Vim docs. Just escape \^M or \<CR>, with a normal backslash. Nice. ----- <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> Nov 6, 2013 at 10:03
  • 27
    "Another aspect"? You're too modest! Explaining precisely_why_ this happens makes for a superior answer to all the ones just saying how to work around it. +1 Oct 20, 2015 at 13:23
  • 1
    This is honestly really great insight into why \n has different meanings in search and replace patterns. Fantastic answer.
    – ZeroKnight
    Apr 30, 2019 at 10:51
51

:help NL-used-for-Nul

Technical detail:

<Nul> characters in the file are stored as <NL> in memory. In the display they are shown as "^@". The translation is done when reading and writing files. To match a <Nul> with a search pattern you can just enter CTRL-@ or "CTRL-V 000". This is probably just what you expect. Internally the character is replaced with a <NL> in the search pattern. What is unusual is that typing CTRL-V CTRL-J also inserts a <NL>, thus also searches for a <Nul> in the file. {Vi cannot handle <Nul> characters in the file at all}


0
12

First of all, open :h :s to see the section "4.2 Substitute" of documentation on "Change". Here's what the command accepts:

:[range]s[ubstitute]/{pattern}/{string}/[flags] [count]

Notice the description about pattern and string

For the {pattern} see |pattern|.
{string} can be a literal string, or something
special; see |sub-replace-special|.

So now you know that the search pattern and replacement patterns follow different rules. If you follow the link to |pattern|, it takes you to the section that explains the whole regexp patterns used in Vim.

Meanwhile, |sub-replace-special| takes you to the subsection of "4.2 Substitute", which contains the patterns for substitution, among which is \r for line break/split.

(The shortcut to this part of manual is :h :s%)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.