p
and P
always work the same way:
p
puts text after the cursor,
P
puts text before the cursor.
But what you put with p
and P
can be "character-wise", "line-wise", or "block-wise". This means that the end result varies not because of p
and P
but because of the nature of what you put.
Character-wise text
The text you put is "character-wise" if it was yanked with a character-wise motion or from character-wise visual mode.
Examples: yiw
, y}
, vf)y
, etc.
If you put character-wise text with p
, the text is put inline, after the cursor:
foo bar baz source line
^^^^ you yanked " bar"
lorem ipsum dolor destination line
^ the cursor is on the "m" of "lorem"
lorem bar ipsum dolor result
With P
, the text is put inline, before the cursor:
lore barm ipsum dolor result
Line-wise text
The text you put is "line-wise" if it was yanked with a line-wise motion or from line-wise visual mode.
Examples: yip
, y3j
, V25jy
, etc.
If you put line-wise text with p
, the text is put below the current line:
foo bar baz source line
^^^^^^^^^^^ you yanked the whole line, including the newline character
lorem ipsum dolor destination line
^ the cursor is on the "m" of "lorem"
lorem ipsum dolor result
foo bar baz
With P
, the text is put above the current line:
foo bar baz result
lorem ipsum dolor
Block-wise text
The text you put is "block-wise" if it was yanked from block-wise visual mode.
Example: <C-v>iw6jy
, etc.
If you put block-wise text with p
, the text is put inline, after the cursor, and overwrites any character in his way:
foo 000 baz source text
foo 000 bar the yanked text is the column of zeroes
baz 000 bar
lorem ipsum dolor destination text
lorem ipsum dolor the cursor is on the "m" of the first "lorem"
lorem ipsum dolor
lorem000 ipsum dolor result
lorem000 ipsum dolor
lorem000 ipsum dolor
With P
, the text is put inline, before the cursor, and overwrites any character in his way:
lore000m ipsum dolor result
lore000m ipsum dolor
lore000m ipsum dolor
help p
's "Put the text [from register x] after the cursor" is not exactly what is happening when the register contains one or more full lines yanked. I'm unaware of a better documentation than the actual help files, though.yy
etc.)p
(and other operations) tries to behave in a "intuitive" manner in each case. When you yank a line,p
tries to paste/put "after" the current line, when you yank some chars,p
will paste "after" current char etc.