Change
Change
This file describes commands that delete or change text. In this context,
changing text means deleting the text and replacing it with other text using
one command. You can undo all of these commands. You can repeat the non-Ex
commands with the "." command.
==============================================================================
1. Deleting text *deleting* *E470*
*X* *dh*
["x]X Delete [count] characters before the cursor [into
register x] (not |linewise|). Does the same as "dh".
Also see |'whichwrap'|.
*d*
["x]d{motion} Delete text that {motion} moves over [into register
x]. See below for exceptions.
*dd*
["x]dd Delete [count] lines [into register x] |linewise|.
*D*
["x]D Delete the characters under the cursor until the end
of the line and [count]-1 more lines [into register
x]; synonym for "d$".
(not |linewise|)
When the '#' flag is in 'cpoptions' the count is
ignored.
These commands delete text. You can repeat them with the `.` command
(except `:d`) and undo them. Use Visual mode to delete blocks of text. See
|registers| for an explanation of registers.
An exception for the d{motion} command: If the motion is not linewise, the
start and end of the motion are not in the same line, and there are only
blanks before the start and there are no non-blanks after the end of the
motion, the delete becomes linewise. This means that the delete also removes
the line of blanks that you might expect to remain. Use the |o_v| operator to
force the motion to be characterwise.
Trying to delete an empty region of text (e.g., "d0" in the first column)
is an error when 'cpoptions' includes the 'E' flag.
*J*
J Join [count] lines, with a minimum of two lines.
Remove the indent and insert up to two spaces (see
below). Fails when on the last line of the buffer.
If [count] is too big it is reduced to the number of
lines available.
*v_J*
{Visual}J Join the highlighted lines, with a minimum of two
lines. Remove the indent and insert up to two spaces
(see below).
*gJ*
gJ Join [count] lines, with a minimum of two lines.
Don't insert or remove any spaces.
*v_gJ*
{Visual}gJ Join the highlighted lines, with a minimum of two
lines. Don't insert or remove any spaces.
*:j* *:join*
:[range]j[oin][!] [flags]
Join [range] lines. Same as "J", except with [!]
the join does not insert or delete any spaces.
If a [range] has equal start and end values, this
command does nothing. The default behavior is to
join the current line with the line below it.
See |ex-flags| for [flags].
These commands delete the <EOL> between lines. This has the effect of joining
multiple lines into one line. You can repeat these commands (except `:j`) and
undo them.
These commands, except "gJ", insert one space in place of the <EOL> unless
there is trailing white space or the next line starts with a ')'. These
commands, except "gJ", delete any leading white space on the next line. If
the 'joinspaces' option is on, these commands insert two spaces after a '.',
'!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces
only after a '.').
The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting
spaces before and after a multibyte character |fo-table|.
The '[ mark is set at the end of the first line that was joined, '] at the end
of the resulting line.
==============================================================================
2. Delete and insert *delete-insert* *replacing*
*R*
R Enter Replace mode: Each character you type replaces
an existing character, starting with the character
under the cursor. Repeat the entered text [count]-1
times. See |Replace-mode| for more details.
*gR*
gR Enter Virtual Replace mode: Each character you type
replaces existing characters in screen space. So a
<Tab> may replace several characters at once.
Repeat the entered text [count]-1 times. See
|Virtual-Replace-mode| for more details.
*c*
["x]c{motion} Delete {motion} text [into register x] and start
insert. When 'cpoptions' includes the 'E' flag and
there is no text to delete (e.g., with "cTx" when the
cursor is just after an 'x'), an error occurs and
insert mode does not start (this is Vi compatible).
When 'cpoptions' does not include the 'E' flag, the
"c" command always starts insert mode, even if there
is no text to delete.
*cc*
["x]cc Delete [count] lines [into register x] and start
insert |linewise|. If 'autoindent' is on, preserve
the indent of the first line.
*C*
["x]C Delete from the cursor position to the end of the
line and [count]-1 more lines [into register x], and
start insert. Synonym for c$ (not |linewise|).
*s*
["x]s Delete [count] characters [into register x] and start
insert (s stands for Substitute). Synonym for "cl"
(not |linewise|).
*S*
["x]S Delete [count] lines [into register x] and start
insert. Synonym for "cc" |linewise|.
*v_r*
{Visual}r{char} Replace all selected characters by {char}.
CTRL-C will be inserted literally.
*v_C*
{Visual}["x]C Delete the highlighted lines [into register x] and
start insert. In Visual block mode it works
differently |v_b_C|.
*v_S*
{Visual}["x]S Delete the highlighted lines [into register x] and
start insert (for {Visual} see |Visual-mode|).
*v_R*
{Visual}["x]R Currently just like {Visual}["x]S. In a next version
it might work differently.
Notes:
- You can end Insert and Replace mode with <Esc>.
- See the section "Insert and Replace mode" |mode-ins-repl| for the other
special characters in these modes.
- The effect of [count] takes place after Vim exits Insert or Replace mode.
- When the 'cpoptions' option contains '$' and the change is within one line,
Vim continues to show the text to be deleted and puts a '$' at the last
deleted character.
*cw* *cW*
Special case: When the cursor is in a word, "cw" and "cW" do not include the
white space after a word, they only change up to the end of the word. This is
because Vim interprets "cw" as change-word, and a word does not include the
following white space.
{Vi: "cw" when on a blank followed by other blanks changes only the first
blank; this is probably a bug, because "dw" deletes all the blanks; use the
'w' flag in 'cpoptions' to make it work like Vi anyway}
If you prefer "cw" to include the space after a word, use this mapping: >
:map cw dwi
Or use "caw" (see |aw|).
==============================================================================
3. Simple changes *simple-change*
*r*
r{char} Replace the character under the cursor with {char}.
If {char} is a <CR> or <NL>, a line break replaces the
character. To replace with a real <CR>, use CTRL-V
<CR>. CTRL-V <NL> replaces with a <Nul>.
*gr*
gr{char} Replace the virtual characters under the cursor with
{char}. This replaces in screen space, not file
space. See |gR| and |Virtual-Replace-mode| for more
details. As with |r| a count may be given.
{char} can be entered like with |r|, but characters
that have a special meaning in Insert mode, such as
most CTRL-keys, cannot be used.
*digraph-arg*
The argument for Normal mode commands like |r| and |t| is a single character.
When 'cpo' doesn't contain the 'D' flag, this character can also be entered
like |digraphs|. First type CTRL-K and then the two digraph characters.
{not available when compiled without the |+digraphs| feature}
*case*
The following commands change the case of letters. The currently active
|locale| is used. See |:language|. The LC_CTYPE value matters here.
*~*
~ 'notildeop' option: Switch case of the character
under the cursor and move the cursor to the right.
If a [count] is given, do that many characters.
*g~*
g~{motion} Switch case of {motion} text.
*v_~*
{Visual}~ Switch case of highlighted text (for {Visual} see
|Visual-mode|).
*v_U*
{Visual}U Make highlighted text uppercase (for {Visual} see
|Visual-mode|).
*gU* *uppercase*
gU{motion} Make {motion} text uppercase.
Example: >
:map! <C-F> <Esc>gUiw`]a
< This works in Insert mode: press CTRL-F to make the
word before the cursor uppercase. Handy to type
words in lowercase and then make them uppercase.
*v_u*
{Visual}u Make highlighted text lowercase (for {Visual} see
|Visual-mode|).
*gu* *lowercase*
gu{motion} Make {motion} text lowercase.
*g?* *rot13*
g?{motion} Rot13 encode {motion} text.
*v_g?*
{Visual}g? Rot13 encode the highlighted text (for {Visual} see
|Visual-mode|).
To turn one line into title caps, make every first letter of a word
uppercase: >
:s/\v<(.)(\w*)/\u\1\L\2/g
*v_CTRL-A*
{Visual}CTRL-A Add [count] to the number or alphabetic character in
the highlighted text.
*v_g_CTRL-A*
{Visual}g CTRL-A Add [count] to the number or alphabetic character in
the highlighted text. If several lines are
highlighted, each one will be incremented by an
additional [count] (so effectively creating a
[count] incrementing sequence).
For Example, if you have this list of numbers:
1. ~
1. ~
1. ~
1. ~
Move to the second "1." and Visually select three
lines, pressing g CTRL-A results in:
1. ~
2. ~
3. ~
4. ~
*CTRL-X*
CTRL-X Subtract [count] from the number or alphabetic
character at or after the cursor.
*v_CTRL-X*
{Visual}CTRL-X Subtract [count] from the number or alphabetic
character in the highlighted text.
For numbers with leading zeros (including all octal and hexadecimal numbers),
Vim preserves the number of characters in the number when possible. CTRL-A on
"0077" results in "0100", CTRL-X on "0x100" results in "0x0ff".
There is one exception: When a number that starts with a zero is found not to
be octal (it contains a '8' or '9'), but 'nrformats' does include "octal",
leading zeros are removed to avoid that the result may be recognized as an
octal number.
Note that when 'nrformats' includes "octal", decimal numbers with leading
zeros cause mistakes, because they can be confused with octal numbers.
Note similarly, when 'nrformats' includes both "bin" and "hex", binary numbers
with a leading '0x' or '0X' can be interpreted as hexadecimal rather than
binary since '0b' are valid hexadecimal digits. CTRL-A on "0x0b11" results in
"0x0b12", not "0x0b100".
When 'nrformats' includes "bin" and doesn't include "hex", CTRL-A on "0b11" in
"0x0b11" results in "0x0b100".
When the number under the cursor is too big to fit into 32 or 64 bit
(depending on how Vim was build), it will be rounded off to the nearest number
that can be represented, and the addition/subtraction is skipped. E.g. with
64 bit support using CTRL-X on 18446744073709551616 results in
18446744073709551615. Same for larger numbers, such as 18446744073709551618.
The CTRL-A command is very useful in a macro. Example: Use the following
steps to make a numbered list.
1. Create the first list entry, make sure it starts with a number.
2. qa - start recording into register 'a'
3. Y - yank the entry
4. p - put a copy of the entry below the first one
5. CTRL-A - increment the number
6. q - stop recording
7. <count>@a - repeat the yank, put and increment <count> times
*<*
<{motion} Shift {motion} lines one 'shiftwidth' leftwards.
*v_<*
{Visual}[count]< Shift the highlighted lines [count] 'shiftwidth'
leftwards (for {Visual} see |Visual-mode|).
*>*
>{motion} Shift {motion} lines one 'shiftwidth' rightwards.
*v_>*
{Visual}[count]> Shift the highlighted lines [count] 'shiftwidth'
rightwards (for {Visual} see |Visual-mode|).
*:<*
:[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<'
for shifting multiple 'shiftwidth's.
:[range]le[ft] [indent] left align lines in [range]. Sets the indent in the
lines to [indent] (default 0).
*:>*
:[range]> [flags] Shift [range] lines one 'shiftwidth' right.
Repeat '>' for shifting multiple 'shiftwidth's.
See |ex-flags| for [flags].
When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as
much as possible to make the indent. You can use ">><<" to replace an indent
made out of spaces with the same indent made out of <Tab>s (and a few spaces
if necessary). If the 'expandtab' option is on, Vim uses only spaces. Then
you can use ">><<" to replace <Tab>s in the indent by spaces (or use
`:retab!`).
To move a line several 'shiftwidth's, use Visual mode or the `:` commands.
For example: >
Vjj4> move three lines 4 indents to the right
:<<< move current line 3 indents to the left
:>> 5 move 5 lines 2 indents to the right
:5>> move line 5 2 indents to the right
==============================================================================
4. Complex changes *complex-change*
*!*
!{motion}{filter} Filter {motion} text lines through the external
program {filter}.
*!!*
!!{filter} Filter [count] lines through the external program
{filter}.
*v_!*
{Visual}!{filter} Filter the highlighted lines through the external
program {filter} (for {Visual} see |Visual-mode|).
*=*
={motion} Filter {motion} lines through the external program
given with the 'equalprg' option. When the 'equalprg'
option is empty (this is the default), use the
internal formatting function |C-indenting| and
|'lisp'|. But when 'indentexpr' is not empty, it will
be used instead |indent-expression|. When Vim was
compiled without internal formatting then the "indent"
program is used as a last resort.
*==*
== Filter [count] lines like with ={motion}.
*v_=*
{Visual}= Filter the highlighted lines like with ={motion}.
*tempfile* *setuid*
Vim uses temporary files for filtering, generating diffs and also for
tempname(). For Unix, the file will be in a private directory (only
accessible by the current user) to avoid security problems (e.g., a symlink
attack or other people reading your file). When Vim exits the directory and
all files in it are deleted. When Vim has the setuid bit set this may cause
problems, the temp file is owned by the setuid user but the filter command
probably runs as the original user.
Directory for temporary files is created in the first of these directories
that works:
Unix: $TMPDIR, /tmp, current-dir, $HOME.
Windows: $TMP, $TEMP, c:\TMP, c:\TEMP
For MS-Windows the GetTempFileName() system function is used.
For other systems the tmpnam() library function is used.
*&*
& Synonym for `:s` (repeat last substitute). Note
that the flags are not remembered, thus it might
actually work differently. You can use `:&&` to keep
the flags.
*g&*
g& Synonym for `:%s//~/&` (repeat last substitute with
last search pattern on all lines with the same flags).
For example, when you first do a substitution with
`:s/pattern/repl/flags` and then `/search` for
something else, `g&` will do `:%s/search/repl/flags`.
Mnemonic: global substitute.
*:snomagic* *:sno*
:[range]sno[magic] ... Same as `:substitute`, but always use 'nomagic'.
*:smagic* *:sm*
:[range]sm[agic] ... Same as `:substitute`, but always use 'magic'.
*:s_flags*
The flags that you can use for the substitute commands:
*:&&*
[&] Must be the first one: Keep the flags from the previous substitute
command. Examples: >
:&&
:s/this/that/&
< Note that `:s` and `:&` don't keep the flags.
[c] Confirm each substitution. Vim highlights the matching string (with
|hl-IncSearch|). You can type: *:s_c*
'y' to substitute this match
'l' to substitute this match and then quit ("last")
'n' to skip this match
<Esc> to quit substituting
'a' to substitute this and all remaining matches
'q' to quit substituting
CTRL-E to scroll the screen up
CTRL-Y to scroll the screen down
If the 'edcompatible' option is on, Vim remembers the [c] flag and
toggles it each time you use it, but resets it when you give a new
search pattern.
*:s_e*
[e] When the search pattern fails, do not issue an error message and, in
particular, continue in maps as if no error occurred. This is most
useful to prevent the "No match" error from breaking a mapping. Vim
does not suppress the following error messages, however:
Regular expressions can't be delimited by letters
\ should be followed by /, ? or &
No previous substitute regular expression
Trailing characters
Interrupted
*:s_g*
[g] Replace all occurrences in the line. Without this argument,
replacement occurs only for the first occurrence in each line. If
the 'edcompatible' option is on, Vim remembers this flag and toggles
it each time you use it, but resets it when you give a new search
pattern. If the 'gdefault' option is on, this flag is on by default
and the [g] argument switches it off.
*:s_i*
[i] Ignore case for the pattern. The 'ignorecase' and 'smartcase' options
are not used.
*:s_I*
[I] Don't ignore case for the pattern. The 'ignorecase' and 'smartcase'
options are not used.
*:s_n*
[n] Report the number of matches, do not actually substitute. The [c]
flag is ignored. The matches are reported as if 'report' is zero.
Useful to |count-items|.
If \= |sub-replace-expression| is used, the expression will be
evaluated in the |sandbox| at every match.
[l] Like [p] but print the text like |:list|. *:s_l*
*:s_r*
[r] Only useful in combination with `:&` or `:s` without arguments. `:&r`
works the same way as `:~`: When the search pattern is empty, use the
previously used search pattern instead of the search pattern from the
last substitute or `:global`. If the last command that did a search
was a substitute or `:global`, there is no effect. If the last
command was a search command such as "/", use the pattern from that
command.
For `:s` with an argument this already happens: >
:s/blue/red/
/green
:s//red/ or :~ or :&r
< The last commands will replace "green" with "red". >
:s/blue/red/
/green
:&
< The last command will replace "blue" with "red".
If the {pattern} for the substitute command is empty, the command uses the
pattern from the last substitute or `:global` command. If there is none, but
there is a previous search pattern, that one is used. With the [r] flag, the
command uses the pattern from the last substitute, `:global`, or search
command.
If the {string} is omitted the substitute is done as if it's empty. Thus the
matched pattern is deleted. The separator after {pattern} can also be left
out then. Example: >
:%s/TESTING
This deletes "TESTING" from all lines, but only one per line.
*E1270*
For compatibility with Vi these two exceptions are allowed in legacy script:
"\/{string}/" and "\?{string}?" do the same as "//{string}/r".
"\&{string}&" does the same as "//{string}/".
*pattern-delimiter* *E146* *E1241* *E1242*
Instead of the '/' which surrounds the pattern and replacement string, you can
use another single-byte character. This is useful if you want to include a
'/' in the search pattern or replacement string. Example: >
:s+/+//+
You can use most characters, but not an alphanumeric character, '\', '"' or
'|'. In Vim9 script you should not use '#' because it may be recognized as
the start of a comment.
For the definition of a pattern, see |pattern|. 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 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.
These commands repeat the previous `:substitute` command with the given flags.
The first letter is always "s", followed by one or two of the possible flag
characters. For example `:sce` works like `:s///ce`. The table lists the
possible combinations, not all flags are possible, because the command is
short for another command.
Exceptions:
:scr is `:scriptnames`
:se is `:set`
:sig is `:sign`
:sil is `:silent`
:sn is `:snext`
:sp is `:split`
:sl is `:sleep`
:sre is `:srewind`
When the result is a |List| then the items are joined with separating line
breaks. Thus each item becomes a line, except that they can contain line
breaks themselves.
The |submatch()| function can be used to obtain matched text. The whole
matched text can be accessed with "submatch(0)". The text matched with the
first pair of () with "submatch(1)". Likewise for further sub-matches in ().
Examples: >
:s@\n@\="\r" .. expand("$HOME") .. "\r"@
This replaces an end-of-line with a new line containing the value of $HOME. >
s/E/\="\<Char-0x20ac>"/g
This replaces each 'E' character with a euro sign. Read more in |<Char->|.
*:pro* *:promptfind*
:promptf[ind] [string]
Put up a Search dialog. When [string] is given, it is
used as the initial search string.
{only for Win32, Motif and GTK GUI}
*:promptr* *:promptrepl*
:promptr[epl] [string]
Put up a Search/Replace dialog. When [string] is
given, it is used as the initial search string.
{only for Win32, Motif and GTK GUI}
*retab-example*
Example for using autocommands and ":retab" to edit a file which is stored
with tabstops at 8 but edited with tabstops set at 4. Warning: white space
inside of strings can change! Also see 'softtabstop' option. >
==============================================================================
5. Copying and moving text *copy-move*
*quote*
"{register} Use {register} for next delete, yank or put. Use
an uppercase character to append with delete and yank.
Registers ".", "%", "#" and ":" only work with put.
*:reg* *:registers*
:reg[isters] Display the type and contents of all numbered and
named registers. If a register is written to for
|:redir| it will not be listed.
Type can be one of:
"c" for |characterwise| text
"l" for |linewise| text
"b" for |blockwise-visual| text
*y* *yank*
["x]y{motion} Yank {motion} text [into register x]. When no
characters are to be yanked (e.g., "y0" in column 1),
this is an error when 'cpoptions' includes the 'E'
flag.
*yy*
["x]yy Yank [count] lines [into register x] |linewise|.
*Y*
["x]Y yank [count] lines [into register x] (synonym for
yy, |linewise|). If you like "Y" to work from the
cursor to the end of line (which is more logical,
but not Vi-compatible) use ":map Y y$".
*zy*
["x]zy{motion} Yank {motion} text [into register x]. Only differs
from `y` when selecting a block of text, see |v_zy|.
*v_y*
{Visual}["x]y Yank the highlighted text [into register x] (for
{Visual} see |Visual-mode|).
*v_Y*
{Visual}["x]Y Yank the highlighted lines [into register x] (for
{Visual} see |Visual-mode|).
*v_zy*
{Visual}["x]zy Yank the highlighted text [into register x]. Trailing
whitespace at the end of each line of a selected block
won't be yanked. Especially useful in combination
with `zp`. (for {Visual} see |Visual-mode|)
*P*
["x]P Put the text [from register x] before the cursor
[count] times.
*<MiddleMouse>*
["x]<MiddleMouse> Put the text from a register before the cursor [count]
times. Uses the "* register, unless another is
specified.
Leaves the cursor at the end of the new text.
Using the mouse only works when 'mouse' contains 'n'
or 'a'.
If you have a scrollwheel and often accidentally paste
text, you can use these mappings to disable the
pasting with the middle mouse button: >
:map <MiddleMouse> <Nop>
:imap <MiddleMouse> <Nop>
< You might want to disable the multi-click versions
too, see |double-click|.
*gp*
["x]gp Just like "p", but leave the cursor just after the new
text.
*gP*
["x]gP Just like "P", but leave the cursor just after the new
text.
*:pu* *:put*
:[line]pu[t] [x] Put the text [from register x] after [line] (default
current line). This always works |linewise|, thus
this command can be used to put a yanked block as new
lines.
If no register is specified, it depends on the 'cb'
option: If 'cb' contains "unnamedplus", paste from the
+ register |quoteplus|. Otherwise, if 'cb' contains
"unnamed", paste from the * register |quotestar|.
Otherwise, paste from the unnamed register
|quote_quote|.
The register can also be '=' followed by an optional
expression. The expression continues until the end of
the command. You need to escape the '|' and '"'
characters to prevent them from terminating the
command. Example: >
:put ='path' .. \",/test\"
< If there is no expression after '=', Vim uses the
previous expression. You can see it with ":dis =".
:[line]pu[t]! [x] Put the text [from register x] before [line] (default
current line).
["x][P or *[P*
["x]]P or *]P*
["x][p or *[p* *[<MiddleMouse>*
["x][<MiddleMouse> Like "P", but adjust the indent to the current line.
Using the mouse only works when 'mouse' contains 'n'
or 'a'.
You can use these commands to copy text from one place to another. Do this
by first getting the text into a register with a yank, delete or change
command, then inserting the register contents with a put command. You can
also use these commands to move text from one file to another, because Vim
preserves all registers when changing buffers (the CTRL-^ command is a quick
way to toggle between two files).
*linewise-register* *characterwise-register*
You can repeat the put commands with "." (except for :put) and undo them. If
the command that was used to get the text into the register was |linewise|,
Vim inserts the text below ("p") or above ("P") the line where the cursor is.
Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With
the ":put" command, Vim always inserts the text in the next line. You can
exchange two characters with the command sequence "xp". You can exchange two
lines with the command sequence "ddp". You can exchange two words with the
command sequence "deep" (start with the cursor in the blank space before the
first word). You can use the "']" or "`]" command after the put command to
move the cursor to the end of the inserted text, or use "'[" or "`[" to move
the cursor to the start.
*blockwise-register*
If you use a blockwise Visual mode command to get the text into the register,
the block of text will be inserted before ("P") or after ("p") the cursor
column in the current and next lines. Vim makes the whole block of text start
in the same column. Thus the inserted text looks the same as when it was
yanked or deleted. Vim may replace some <Tab> characters with spaces to make
this happen. However, if the width of the block is not a multiple of a <Tab>
width and the text after the inserted block contains <Tab>s, that text may be
misaligned.
Note that after a characterwise yank command, Vim leaves the cursor on the
first yanked character that is closest to the start of the buffer. This means
that "yl" doesn't move the cursor, but "yh" moves the cursor one character
left.
Rationale: In Vi the "y" command followed by a backwards motion would
sometimes not move the cursor to the first yanked character,
because redisplaying was skipped. In Vim it always moves to
the first character, as specified by Posix.
With a linewise yank command the cursor is put in the first line, but the
column is unmodified, thus it may not be on the first yanked character.
When typing the '=' after " or CTRL-R the cursor moves to the command-line,
where you can enter any expression (see |expression|). All normal
command-line editing commands are available, including a special history for
expressions. When you end the command-line by typing <CR>, Vim computes the
result of the expression. If you end it with <Esc>, Vim abandons the
expression. If you do not enter an expression, Vim uses the previous
expression (like with the "/" command).
If the "= register is used for the "p" command, the String is split up at <NL>
characters. If the String ends in a <NL>, it is regarded as a linewise
register.
Note that there is only a distinction between "* and "+ for X11 systems. For
an explanation of the difference, see |x11-selection|. Under MS-Windows, use
of "* and "+ is actually synonymous and refers to the |gui-clipboard|.
Note: The "~ register is only used when dropping plain text onto Vim.
Drag'n'drop of URI lists is handled internally.
*@/*
You can write to a register with a `:let` command |:let-@|. Example: >
:let @/ = "the"
If you use a put command without specifying a register, Vim uses the register
that was last filled (this is also the contents of the unnamed register). If
you are confused, use the `:dis` command to find out what Vim will put (this
command displays all named and numbered registers; the unnamed register is
labelled '"').
*:t*
:t Synonym for copy.
This command is not supported in |Vim9| script,
because it is too easily confused with a variable
name.
==============================================================================
6. Formatting text *formatting*
*:le* *:left*
:[range]le[ft] [indent]
Left-align lines in [range]. Sets the indent in the
lines to [indent] (default 0).
*gq*
gq{motion} Format the lines that {motion} moves over.
Formatting is done with one of three methods:
1. If 'formatexpr' is not empty the expression is
evaluated. This can differ for each buffer.
2. If 'formatprg' is not empty an external program
is used.
3. Otherwise formatting is done internally.
*v_gq*
{Visual}gq Format the highlighted text. (for {Visual} see
|Visual-mode|).
*gw*
gw{motion} Format the lines that {motion} moves over. Similar to
|gq| but puts the cursor back at the same position in
the text. However, 'formatprg' and 'formatexpr' are
not used.
*v_gw*
{Visual}gw Format the highlighted text as with "gw". (for
{Visual} see |Visual-mode|).
Example: To format the current paragraph use: *gqap* >
gqap
The "gq" command leaves the cursor in the line where the motion command takes
the cursor. This allows you to repeat formatting repeated with ".". This
works well with "gqj" (format current and next line) and "gq}" (format until
end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on
the first formatted line (as with using a filter command).
If you want to format the current paragraph and continue where you were, use: >
gwap
If you always want to keep paragraphs formatted you may want to add the 'a'
flag to 'formatoptions'. See |auto-format|.
If the 'autoindent' option is on, Vim uses the indent of the first line for
the following lines.
Formatting does not change empty lines (but it does change lines with only
white space!).
You can set the 'formatexpr' option to an expression or the 'formatprg' option
to the name of an external program for Vim to use for text formatting. The
'textwidth' and other options have no effect on formatting by an external
program.
*format-formatexpr*
The 'formatexpr' option can be set to a Vim script function that performs
reformatting of the buffer. This should usually happen in an |ftplugin|,
since formatting is highly dependent on the type of file. It makes
sense to use an |autoload| script, so the corresponding script is only loaded
when actually needed and the script should be called <filetype>format.vim.
For example, the XML filetype plugin distributed with Vim in the $VIMRUNTIME
directory, sets the 'formatexpr' option to: >
setlocal formatexpr=xmlformat#Format()
That means, you will find the corresponding script, defining the
xmlformat#Format() function, in the directory:
`$VIMRUNTIME/autoload/xmlformat.vim`
Here is an example script that removes trailing whitespace from the selected
text. Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim: >
func! format#Format()
" only reformat on explicit gq command
if mode() != 'n'
" fall back to Vim's internal reformatting
return 1
endif
let lines = getline(v:lnum, v:lnum + v:count - 1)
call map(lines, {key, val -> substitute(val, '\s\+$', '', 'g')})
call setline('.', lines)
Note: this function explicitly returns non-zero when called from insert mode
(which basically means, text is inserted beyond the 'textwidth' limit). This
causes Vim to fall back to reformat the text by using the internal formatter.
However, if the |gq| command is used to reformat the text, the function
will receive the selected lines, trim trailing whitespace from those lines and
put them back in place. If you are going to split single lines into multiple
lines, be careful not to overwrite anything.
If you want to allow reformatting of text from insert or replace mode, one has
to be very careful, because the function might be called recursively. For
debugging it helps to set the 'debug' option.
*right-justify*
There is no command in Vim to right justify text. You can do it with
an external command, like "par" (e.g.: "!}par" to format until the end of the
paragraph) or set 'formatprg' to "par".
*format-comments*
An overview of comment formatting is in section |30.6| of the user manual.
Vim can automatically insert and format comments in a special way. Vim
recognizes a comment by a specific string at the start of the line (ignoring
white space). Three types of comments can be used:
- A comment string that repeats at the start of each line. An example is the
type of comment used in shell scripts, starting with "#".
- A comment string that occurs only in the first line, not in the following
lines. An example is this list with dashes.
- Three-piece comments that have a start string, an end string, and optional
lines in between. The strings for the start, middle and end are different.
An example is the C style comment:
/*
* this is a C comment
*/
{flags}:
n Nested comment. Nesting with mixed parts is allowed. If 'comments'
is "n:),n:>" a line starting with "> ) >" is a comment.
f Only the first line has the comment string. Do not repeat comment on
the next line, but preserve indentation (e.g., a bullet-list).
l Left align. Used together with 's' or 'e', the leftmost character of
start or end will line up with the leftmost character from the middle.
This is the default and can be omitted. See below for more details.
{digits}
When together with 's' or 'e': add {digit} amount of offset to an
automatically inserted middle or end comment leader. The offset begins
from a left alignment. See below for more details.
-{digits}
Like {digits} but reduce the indent. This only works when there is
some indent for the start or end part that can be removed.
When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the
comment string repeats at the start of each line. The flags field may be
empty.
Any blank space in the text before and after the {string} is part of the
{string}, so do not include leading or trailing blanks unless the blanks are a
required part of the comment string.
When one comment leader is part of another, specify the part after the whole.
For example, to include both "-" and "->", use >
:set comments=f:->,f:-
Notice the use of the "x" flag in the above three-piece comment definition.
When you hit Return in a C-comment, Vim will insert the middle comment leader
for the new line: " * ". To close this comment you just have to type "/"
before typing anything else on the new line. This will replace the
middle-comment leader with the end-comment leader and apply any specified
alignment, leaving just " */". There is no need to hit Backspace first.
When there is a match with a middle part, but there also is a matching end
part which is longer, the end part is used. This makes a C style comment work
without requiring the middle part to end with a space.
Here are some finer points of three part comments. There are three times when
alignment and offset flags are taken into consideration: opening a new line
after a start-comment, opening a new line before an end-comment, and
automatically ending a three-piece comment. The end alignment flag has a
backwards perspective; the result is that the same alignment flag used with
"s" and "e" will result in the same indent for the starting and ending pieces.
Only one alignment per comment part is meant to be used, but an offset number
will override the "r" and "l" flag.
By default, "b:#" is included. This means that a line that starts with
"#include" is not recognized as a comment line. But a line that starts with
"# define" is recognized. This is a compromise.
*fo-table*
You can use the 'formatoptions' option to influence how Vim formats text.
'formatoptions' is a string that can contain any of the letters below. The
default setting is "tcq". You can separate the option letters with commas for
readability.
With 't' and 'c' you can specify when Vim performs auto-wrapping:
value action ~
"" no automatic formatting (you can use "gq" for manual formatting)
"t" automatic formatting of text, but not comments
"c" automatic formatting for comments, but not text (good for C code)
"tc" automatic formatting for text and comments
Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but
does insert comment leaders according to the 'comments' option). An exception
is when the 'a' flag is present. |auto-format|
Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping;
'textwidth' is still useful for formatting with "gq".
If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some
built in stuff to treat these types of comments a bit more cleverly.
Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in
'formatoptions') gives the correct start of the line automatically. The same
happens with formatting and auto-wrapping. Opening a line after a line
starting with "/*" or "*" and containing "*/", will cause no comment leader to
be inserted, and the indent of the new line is taken from the line containing
the start of the comment.
E.g.:
/* ~
* Your typical comment. ~
*/ ~
The indent on this line is the same as the start of the above
comment.
All of this should be really cool, especially in conjunction with the new
:autocmd command to prepare different settings for different types of file.
Some examples:
for C code (only format comments): >
:set fo=croq
< for Mail/news (format all, don't start comment with "o" command): >
:set fo=tcrq
<
- You need to properly define paragraphs. The simplest is paragraphs that are
separated by a blank line. When there is no separating blank line, consider
using the 'w' flag and adding a space at the end of each line in the
paragraphs except the last one.
- You can set the 'formatoptions' based on the type of file |filetype| or
specifically for one file with a |modeline|.
- Add the 'c' flag to only auto-format comments. Useful in source code.
:set fo-=a
- When using the 'w' flag (trailing space means paragraph continues) and
deleting the last line of a paragraph with |dd|, the paragraph will be
joined with the next one.
- Changed text is saved for undo. Formatting is also a change. Thus each
format action saves text for undo. This may consume quite a lot of memory.
==============================================================================
7. Sorting text *sorting*
Vim has a sorting function and a sorting command. The sorting function can be
found here: |sort()|, |uniq()|.
*:sor* *:sort*
:[range]sor[t][!] [b][f][i][l][n][o][r][u][x] [/{pattern}/]
Sort lines in [range]. When no range is given all
lines are sorted.
Note that using `:sort` with `:global` doesn't sort the matching lines, it's
quite useless.
`:sort` does not use the current locale unless the l flag is used.
Vim does do a "stable" sort.
The sorting can be interrupted, but if you interrupt it too late in the
process you may end up with duplicated lines. This also depends on the system
library function used.
vim:tw=78:ts=8:noet:ft=help:norl: