| blob | bf2b104580ab9233bf68d0daf43e06b4d620d5f9 |
1 *change.txt* For Vim version 7.1. Last change: 2008 Jan 16
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 This file describes commands that delete or change text. In this context,
8 changing text means deleting the text and replacing it with other text using
9 one command. You can undo all of these commands. You can repeat the non-Ex
10 commands with the "." command.
12 1. Deleting text |deleting|
13 2. Delete and insert |delete-insert|
14 3. Simple changes |simple-change| *changing*
15 4. Complex changes |complex-change|
16 4.1 Filter commands |filter|
17 4.2 Substitute |:substitute|
18 4.3 Search and replace |search-replace|
19 4.4 Changing tabs |change-tabs|
20 5. Copying and moving text |copy-move|
21 6. Formatting text |formatting|
22 7. Sorting text |sorting|
24 For inserting text see |insert.txt|.
26 ==============================================================================
27 1. Deleting text *deleting* *E470*
29 ["x]<Del> or *<Del>* *x* *dl*
30 ["x]x Delete [count] characters under and after the cursor
31 [into register x] (not |linewise|). Does the same as
32 "dl".
33 The <Del> key does not take a [count]. Instead, it
34 deletes the last character of the count.
35 See |:fixdel| if the <Del> key does not do what you
36 want. See |'whichwrap'| for deleting a line break
37 (join lines). {Vi does not support <Del>}
39 *X* *dh*
40 ["x]X Delete [count] characters before the cursor [into
41 register x] (not |linewise|). Does the same as "dh".
42 Also see |'whichwrap'|.
44 *d*
45 ["x]d{motion} Delete text that {motion} moves over [into register
46 x]. See below for exceptions.
48 *dd*
49 ["x]dd Delete [count] lines [into register x] |linewise|.
51 *D*
52 ["x]D Delete the characters under the cursor until the end
53 of the line and [count]-1 more lines [into register
54 x]; synonym for "d$".
55 (not |linewise|)
56 When the '#' flag is in 'cpoptions' the count is
57 ignored.
59 {Visual}["x]x or *v_x* *v_d* *v_<Del>*
60 {Visual}["x]d or
61 {Visual}["x]<Del> Delete the highlighted text [into register x] (for
62 {Visual} see |Visual-mode|). {not in Vi}
64 {Visual}["x]CTRL-H or *v_CTRL-H* *v_<BS>*
65 {Visual}["x]<BS> When in Select mode: Delete the highlighted text [into
66 register x].
68 {Visual}["x]X or *v_X* *v_D* *v_b_D*
69 {Visual}["x]D Delete the highlighted lines [into register x] (for
70 {Visual} see |Visual-mode|). In Visual block mode,
71 "D" deletes the highlighted text plus all text until
72 the end of the line. {not in Vi}
74 *:d* *:de* *:del* *:delete*
75 :[range]d[elete] [x] Delete [range] lines (default: current line) [into
76 register x].
78 :[range]d[elete] [x] {count}
79 Delete {count} lines, starting with [range]
80 (default: current line |cmdline-ranges|) [into
81 register x].
83 These commands delete text. You can repeat them with the "." command
84 (except ":d") and undo them. Use Visual mode to delete blocks of text. See
85 |registers| for an explanation of registers.
87 An exception for the d{motion} command: If the motion is not linewise, the
88 start and end of the motion are not in the same line, and there are only
89 blanks before the start and after the end of the motion, the delete becomes
90 linewise. This means that the delete also removes the line of blanks that you
91 might expect to remain.
93 Trying to delete an empty region of text (e.g., "d0" in the first column)
94 is an error when 'cpoptions' includes the 'E' flag.
96 *J*
97 J Join [count] lines, with a minimum of two lines.
98 Remove the indent and insert up to two spaces (see
99 below).
101 *v_J*
102 {Visual}J Join the highlighted lines, with a minimum of two
103 lines. Remove the indent and insert up to two spaces
104 (see below). {not in Vi}
106 *gJ*
107 gJ Join [count] lines, with a minimum of two lines.
108 Don't insert or remove any spaces. {not in Vi}
110 *v_gJ*
111 {Visual}gJ Join the highlighted lines, with a minimum of two
112 lines. Don't insert or remove any spaces. {not in
113 Vi}
115 *:j* *:join*
116 :[range]j[oin][!] [flags]
117 Join [range] lines. Same as "J", except with [!]
118 the join does not insert or delete any spaces.
119 If a [range] has equal start and end values, this
120 command does nothing. The default behavior is to
121 join the current line with the line below it.
122 {not in Vi: !}
123 See |ex-flags| for [flags].
125 :[range]j[oin][!] {count} [flags]
126 Join {count} lines, starting with [range] (default:
127 current line |cmdline-ranges|). Same as "J", except
128 with [!] the join does not insert or delete any
129 spaces.
130 {not in Vi: !}
131 See |ex-flags| for [flags].
133 These commands delete the <EOL> between lines. This has the effect of joining
134 multiple lines into one line. You can repeat these commands (except ":j") and
135 undo them.
137 These commands, except "gJ", insert one space in place of the <EOL> unless
138 there is trailing white space or the next line starts with a ')'. These
139 commands, except "gJ", delete any leading white space on the next line. If
140 the 'joinspaces' option is on, these commands insert two spaces after a '.',
141 '!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces
142 only after a '.').
143 The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting
144 spaces before and after a multi-byte character |fo-table|.
147 ==============================================================================
148 2. Delete and insert *delete-insert* *replacing*
150 *R*
151 R Enter Replace mode: Each character you type replaces
152 an existing character, starting with the character
153 under the cursor. Repeat the entered text [count]-1
154 times. See |Replace-mode| for more details.
156 *gR*
157 gR Enter Virtual Replace mode: Each character you type
158 replaces existing characters in screen space. So a
159 <Tab> may replace several characters at once.
160 Repeat the entered text [count]-1 times. See
161 |Virtual-Replace-mode| for more details.
162 {not available when compiled without the +vreplace
163 feature}
165 *c*
166 ["x]c{motion} Delete {motion} text [into register x] and start
167 insert. When 'cpoptions' includes the 'E' flag and
168 there is no text to delete (e.g., with "cTx" when the
169 cursor is just after an 'x'), an error occurs and
170 insert mode does not start (this is Vi compatible).
171 When 'cpoptions' does not include the 'E' flag, the
172 "c" command always starts insert mode, even if there
173 is no text to delete.
175 *cc*
176 ["x]cc Delete [count] lines [into register x] and start
177 insert |linewise|. If 'autoindent' is on, preserve
178 the indent of the first line.
180 *C*
181 ["x]C Delete from the cursor position to the end of the
182 line and [count]-1 more lines [into register x], and
183 start insert. Synonym for c$ (not |linewise|).
185 *s*
186 ["x]s Delete [count] characters [into register x] and start
187 insert (s stands for Substitute). Synonym for "cl"
188 (not |linewise|).
190 *S*
191 ["x]S Delete [count] lines [into register x] and start
192 insert. Synonym for "cc" |linewise|.
194 {Visual}["x]c or *v_c* *v_s*
195 {Visual}["x]s Delete the highlighted text [into register x] and
196 start insert (for {Visual} see |Visual-mode|). {not
197 in Vi}
199 *v_r*
200 {Visual}["x]r{char} Replace all selected characters by {char}.
202 *v_C*
203 {Visual}["x]C Delete the highlighted lines [into register x] and
204 start insert. In Visual block mode it works
205 differently |v_b_C|. {not in Vi}
206 *v_S*
207 {Visual}["x]S Delete the highlighted lines [into register x] and
208 start insert (for {Visual} see |Visual-mode|). {not
209 in Vi}
210 *v_R*
211 {Visual}["x]R Currently just like {Visual}["x]S. In a next version
212 it might work differently. {not in Vi}
214 Notes:
215 - You can end Insert and Replace mode with <Esc>.
216 - See the section "Insert and Replace mode" |mode-ins-repl| for the other
217 special characters in these modes.
218 - The effect of [count] takes place after Vim exits Insert or Replace mode.
219 - When the 'cpoptions' option contains '$' and the change is within one line,
220 Vim continues to show the text to be deleted and puts a '$' at the last
221 deleted character.
223 See |registers| for an explanation of registers.
225 Replace mode is just like Insert mode, except that every character you enter
226 deletes one character. If you reach the end of a line, Vim appends any
227 further characters (just like Insert mode). In Replace mode, the backspace
228 key restores the original text (if there was any). (See section "Insert and
229 Replace mode" |mode-ins-repl|).
231 *cw* *cW*
232 Special case: "cw" and "cW" work the same as "ce" and "cE" if the cursor is
233 on a non-blank. This is because Vim interprets "cw" as change-word, and a
234 word does not include the following white space. {Vi: "cw" when on a blank
235 followed by other blanks changes only the first blank; this is probably a
236 bug, because "dw" deletes all the blanks; use the 'w' flag in 'cpoptions' to
237 make it work like Vi anyway}
239 If you prefer "cw" to include the space after a word, use this mapping: >
240 :map cw dwi
241 <
242 *:c* *:ch* *:change*
243 :{range}c[hange][!] Replace lines of text with some different text.
244 Type a line containing only "." to stop replacing.
245 Without {range}, this command changes only the current
246 line.
247 Adding [!] toggles 'autoindent' for the time this
248 command is executed.
250 ==============================================================================
251 3. Simple changes *simple-change*
253 *r*
254 r{char} Replace the character under the cursor with {char}.
255 If {char} is a <CR> or <NL>, a line break replaces the
256 character. To replace with a real <CR>, use CTRL-V
257 <CR>. CTRL-V <NL> replaces with a <Nul>.
258 {Vi: CTRL-V <CR> still replaces with a line break,
259 cannot replace something with a <CR>}
260 If you give a [count], Vim replaces [count] characters
261 with [count] {char}s. When {char} is a <CR> or <NL>,
262 however, Vim inserts only one <CR>: "5r<CR>" replaces
263 five characters with a single line break.
264 When {char} is a <CR> or <NL>, Vim performs
265 autoindenting. This works just like deleting the
266 characters that are replaced and then doing
267 "i<CR><Esc>".
268 {char} can be entered as a digraph |digraph-arg|.
269 |:lmap| mappings apply to {char}. The CTRL-^ command
270 in Insert mode can be used to switch this on/off
271 |i_CTRL-^|. See |utf-8-char-arg| about using
272 composing characters when 'encoding' is Unicode.
274 *gr*
275 gr{char} Replace the virtual characters under the cursor with
276 {char}. This replaces in screen space, not file
277 space. See |gR| and |Virtual-Replace-mode| for more
278 details. As with |r| a count may be given.
279 {char} can be entered like with |r|.
280 {not available when compiled without the +vreplace
281 feature}
283 *digraph-arg*
284 The argument for Normal mode commands like |r| and |t| is a single character.
285 When 'cpo' doesn't contain the 'D' flag, this character can also be entered
286 like |digraphs|. First type CTRL-K and then the two digraph characters.
287 {not available when compiled without the |+digraphs| feature}
289 *case*
290 The following commands change the case of letters. The currently active
291 |locale| is used. See |:language|. The LC_CTYPE value matters here.
293 *~*
294 ~ 'notildeop' option: Switch case of the character
295 under the cursor and move the cursor to the right.
296 If a [count] is given, do that many characters. {Vi:
297 no count}
299 ~{motion} 'tildeop' option: switch case of {motion} text. {Vi:
300 tilde cannot be used as an operator}
302 *g~*
303 g~{motion} Switch case of {motion} text. {not in Vi}
305 g~g~ *g~g~* *g~~*
306 g~~ Switch case of current line. {not in Vi}.
308 *v_~*
309 {Visual}~ Switch case of highlighted text (for {Visual} see
310 |Visual-mode|). {not in Vi}
312 *v_U*
313 {Visual}U Make highlighted text uppercase (for {Visual} see
314 |Visual-mode|). {not in Vi}
316 *gU* *uppercase*
317 gU{motion} Make {motion} text uppercase. {not in Vi}
318 Example: >
319 :map! <C-F> <Esc>gUiw`]a
320 < This works in Insert mode: press CTRL-F to make the
321 word before the cursor uppercase. Handy to type
322 words in lowercase and then make them uppercase.
325 gUgU *gUgU* *gUU*
326 gUU Make current line uppercase. {not in Vi}.
328 *v_u*
329 {Visual}u Make highlighted text lowercase (for {Visual} see
330 |Visual-mode|). {not in Vi}
332 *gu* *lowercase*
333 gu{motion} Make {motion} text lowercase. {not in Vi}
335 gugu *gugu* *guu*
336 guu Make current line lowercase. {not in Vi}.
338 *g?* *rot13*
339 g?{motion} Rot13 encode {motion} text. {not in Vi}
341 *v_g?*
342 {Visual}g? Rot13 encode the highlighted text (for {Visual} see
343 |Visual-mode|). {not in Vi}
345 g?g? *g?g?* *g??*
346 g?? Rot13 encode current line. {not in Vi}.
348 To turn one line into title caps, make every first letter of a word
349 uppercase: >
350 :s/\v<(.)(\w*)/\u\1\L\2/g
353 Adding and subtracting ~
354 *CTRL-A*
355 CTRL-A Add [count] to the number or alphabetic character at
356 or after the cursor. {not in Vi}
358 *CTRL-X*
359 CTRL-X Subtract [count] from the number or alphabetic
360 character at or after the cursor. {not in Vi}
362 The CTRL-A and CTRL-X commands work for (signed) decimal numbers, unsigned
363 octal and hexadecimal numbers and alphabetic characters. This depends on the
364 'nrformats' option.
365 - When 'nrformats' includes "octal", Vim considers numbers starting with a '0'
366 to be octal, unless the number includes a '8' or '9'. Other numbers are
367 decimal and may have a preceding minus sign.
368 If the cursor is on a number, the commands apply to that number; otherwise
369 Vim uses the number to the right of the cursor.
370 - When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or
371 '0X' are hexadecimal. The case of the rightmost letter in the number
372 determines the case of the resulting hexadecimal number. If there is no
373 letter in the current number, Vim uses the previously detected case.
374 - When 'nrformats' includes "alpha", Vim will change the alphabetic character
375 under or after the cursor. This is useful to make lists with an alphabetic
376 index.
378 For numbers with leading zeros (including all octal and hexadecimal numbers),
379 Vim preserves the number of characters in the number when possible. CTRL-A on
380 "0077" results in "0100", CTRL-X on "0x100" results in "0x0ff".
381 There is one exception: When a number that starts with a zero is found not to
382 be octal (it contains a '8' or '9'), but 'nrformats' does include "octal",
383 leading zeros are removed to avoid that the result may be recognized as an
384 octal number.
386 Note that when 'nrformats' includes "octal", decimal numbers with leading
387 zeros cause mistakes, because they can be confused with octal numbers.
389 The CTRL-A command is very useful in a macro. Example: Use the following
390 steps to make a numbered list.
392 1. Create the first list entry, make sure it starts with a number.
393 2. qa - start recording into register 'a'
394 3. Y - yank the entry
395 4. p - put a copy of the entry below the first one
396 5. CTRL-A - increment the number
397 6. q - stop recording
398 7. <count>@a - repeat the yank, put and increment <count> times
401 SHIFTING LINES LEFT OR RIGHT *shift-left-right*
403 *<*
404 <{motion} Shift {motion} lines one 'shiftwidth' leftwards.
406 *<<*
407 << Shift [count] lines one 'shiftwidth' leftwards.
409 *v_<*
410 {Visual}[count]< Shift the highlighted lines [count] 'shiftwidth'
411 leftwards (for {Visual} see |Visual-mode|). {not in
412 Vi}
414 *>*
415 >{motion} Shift {motion} lines one 'shiftwidth' rightwards.
417 *>>*
418 >> Shift [count] lines one 'shiftwidth' rightwards.
420 *v_>*
421 {Visual}[count]> Shift the highlighted lines [count] 'shiftwidth'
422 rightwards (for {Visual} see |Visual-mode|). {not in
423 Vi}
425 *:<*
426 :[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<'
427 for shifting multiple 'shiftwidth's.
429 :[range]< {count} Shift {count} lines one 'shiftwidth' left, starting
430 with [range] (default current line |cmdline-ranges|).
431 Repeat '<' for shifting multiple 'shiftwidth's.
433 :[range]le[ft] [indent] left align lines in [range]. Sets the indent in the
434 lines to [indent] (default 0). {not in Vi}
436 *:>*
437 :[range]> [flags] Shift {count} [range] lines one 'shiftwidth' right.
438 Repeat '>' for shifting multiple 'shiftwidth's.
439 See |ex-flags| for [flags].
441 :[range]> {count} [flags]
442 Shift {count} lines one 'shiftwidth' right, starting
443 with [range] (default current line |cmdline-ranges|).
444 Repeat '>' for shifting multiple 'shiftwidth's.
445 See |ex-flags| for [flags].
447 The ">" and "<" commands are handy for changing the indentation within
448 programs. Use the 'shiftwidth' option to set the size of the white space
449 which these commands insert or delete. Normally the 'shiftwidth' option is 8,
450 but you can set it to, say, 3 to make smaller indents. The shift leftwards
451 stops when there is no indent. The shift right does not affect empty lines.
453 If the 'shiftround' option is on, the indent is rounded to a multiple of
454 'shiftwidth'.
456 If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains
457 '#', shift right does not affect lines starting with '#' (these are supposed
458 to be C preprocessor lines that must stay in column 1).
460 When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as
461 much as possible to make the indent. You can use ">><<" to replace an indent
462 made out of spaces with the same indent made out of <Tab>s (and a few spaces
463 if necessary). If the 'expandtab' option is on, Vim uses only spaces. Then
464 you can use ">><<" to replace <Tab>s in the indent by spaces (or use
465 ":retab!").
467 To move a line several 'shiftwidth's, use Visual mode or the ":" commands.
468 For example: >
469 Vjj4> move three lines 4 indents to the right
470 :<<< move current line 3 indents to the left
471 :>> 5 move 5 lines 2 indents to the right
472 :5>> move line 5 2 indents to the right
474 ==============================================================================
475 4. Complex changes *complex-change*
477 4.1 Filter commands *filter*
479 A filter is a program that accepts text at standard input, changes it in some
480 way, and sends it to standard output. You can use the commands below to send
481 some text through a filter, so that it is replaced by the filter output.
482 Examples of filters are "sort", which sorts lines alphabetically, and
483 "indent", which formats C program files (you need a version of indent that
484 works like a filter; not all versions do). The 'shell' option specifies the
485 shell Vim uses to execute the filter command (See also the 'shelltype'
486 option). You can repeat filter commands with ".". Vim does not recognize a
487 comment (starting with '"') after the ":!" command.
489 *!*
490 !{motion}{filter} Filter {motion} text lines through the external
491 program {filter}.
493 *!!*
494 !!{filter} Filter [count] lines through the external program
495 {filter}.
497 *v_!*
498 {Visual}!{filter} Filter the highlighted lines through the external
499 program {filter} (for {Visual} see |Visual-mode|).
500 {not in Vi}
502 :{range}![!]{filter} [!][arg] *:range!*
503 Filter {range} lines through the external program
504 {filter}. Vim replaces the optional bangs with the
505 latest given command and appends the optional [arg].
506 Vim saves the output of the filter command in a
507 temporary file and then reads the file into the
508 buffer. Vim uses the 'shellredir' option to redirect
509 the filter output to the temporary file.
510 However, if the 'shelltemp' option is off then pipes
511 are used when possible (on Unix).
512 When the 'R' flag is included in 'cpoptions' marks in
513 the filtered lines are deleted, unless the
514 |:keepmarks| command is used. Example: >
515 :keepmarks '<,'>!sort
516 < When the number of lines after filtering is less than
517 before, marks in the missing lines are deleted anyway.
519 *=*
520 ={motion} Filter {motion} lines through the external program
521 given with the 'equalprg' option. When the 'equalprg'
522 option is empty (this is the default), use the
523 internal formatting function |C-indenting|. But when
524 'indentexpr' is not empty, it will be used instead
525 |indent-expression|.
527 *==*
528 == Filter [count] lines like with ={motion}.
530 *v_=*
531 {Visual}= Filter the highlighted lines like with ={motion}.
532 {not in Vi}
535 4.2 Substitute *:substitute*
536 *:s* *:su*
537 :[range]s[ubstitute]/{pattern}/{string}/[flags] [count]
538 For each line in [range] replace a match of {pattern}
539 with {string}.
540 For the {pattern} see |pattern|.
541 {string} can be a literal string, or something
542 special; see |sub-replace-special|.
543 When [range] and [count] are omitted, replace in the
544 current line only.
545 When [count] is given, replace in [count] lines,
546 starting with the last line in [range]. When [range]
547 is omitted start in the current line.
548 Also see |cmdline-ranges|.
549 See |:s_flags| for [flags].
551 :[range]s[ubstitute] [flags] [count]
552 :[range]&[&][flags] [count] *:&*
553 Repeat last :substitute with same search pattern and
554 substitute string, but without the same flags. You
555 may add [flags], see |:s_flags|.
556 Note that after ":substitute" the '&' flag can't be
557 used, it's recognized as a pattern separator.
558 The space between ":substitute" and the 'c', 'g' and
559 'r' flags isn't required, but in scripts it's a good
560 idea to keep it to avoid confusion.
562 :[range]~[&][flags] [count] *:~*
563 Repeat last substitute with same substitute string
564 but with last used search pattern. This is like
565 ":&r". See |:s_flags| for [flags].
567 *&*
568 & Synonym for ":s//~/" (repeat last substitute). Note
569 that the flags are not remembered, thus it might
570 actually work differently. You can use ":&&" to keep
571 the flags.
573 *g&*
574 g& Synonym for ":%s//~/&" (repeat last substitute on all
575 lines with the same flags).
576 Mnemonic: global substitute. {not in Vi}
578 *:snomagic* *:sno*
579 :[range]sno[magic] ... Same as ":substitute", but always use 'nomagic'.
580 {not in Vi}
582 *:smagic* *:sm*
583 :[range]sm[agic] ... Same as ":substitute", but always use 'magic'.
584 {not in Vi}
586 *:s_flags*
587 The flags that you can use for the substitute commands:
589 [&] Must be the first one: Keep the flags from the previous substitute
590 command. Examples: >
591 :&&
592 :s/this/that/&
593 < Note that ":s" and ":&" don't keep the flags.
594 {not in Vi}
596 [c] Confirm each substitution. Vim highlights the matching string (with
597 |hl-IncSearch|). You can type: *:s_c*
598 'y' to substitute this match
599 'l' to substitute this match and then quit ("last")
600 'n' to skip this match
601 <Esc> to quit substituting
602 'a' to substitute this and all remaining matches {not in Vi}
603 'q' to quit substituting {not in Vi}
604 CTRL-E to scroll the screen up {not in Vi, not available when
605 compiled without the +insert_expand feature}
606 CTRL-Y to scroll the screen down {not in Vi, not available when
607 compiled without the +insert_expand feature}
608 If the 'edcompatible' option is on, Vim remembers the [c] flag and
609 toggles it each time you use it, but resets it when you give a new
610 search pattern.
611 {not in Vi: highlighting of the match, other responses than 'y' or 'n'}
613 [e] When the search pattern fails, do not issue an error message and, in
614 particular, continue in maps as if no error occurred. This is most
615 useful to prevent the "No match" error from breaking a mapping. Vim
616 does not suppress the following error messages, however:
617 Regular expressions can't be delimited by letters
618 \ should be followed by /, ? or &
619 No previous substitute regular expression
620 Trailing characters
621 Interrupted
622 {not in Vi}
624 [g] Replace all occurrences in the line. Without this argument,
625 replacement occurs only for the first occurrence in each line. If
626 the 'edcompatible' option is on, Vim remembers this flag and toggles
627 it each time you use it, but resets it when you give a new search
628 pattern. If the 'gdefault' option is on, this flag is on by default
629 and the [g] argument switches it off.
631 [i] Ignore case for the pattern. The 'ignorecase' and 'smartcase' options
632 are not used.
633 {not in Vi}
635 [I] Don't ignore case for the pattern. The 'ignorecase' and 'smartcase'
636 options are not used.
637 {not in Vi}
639 [n] Report the number of matches, do not actually substitute. The [c]
640 flag is ignored. The matches are reported as if 'report' is zero.
641 Useful to |count-items|.
643 [p] Print the line containing the last substitute.
645 [#] Like [p] and prepend the line number.
647 [l] Like [p] but print the text like |:list|.
649 [r] Only useful in combination with ":&" or ":s" without arguments. ":&r"
650 works the same way as ":~": When the search pattern is empty, use the
651 previously used search pattern instead of the search pattern from the
652 last substitute or ":global". If the last command that did a search
653 was a substitute or ":global", there is no effect. If the last
654 command was a search command such as "/", use the pattern from that
655 command.
656 For ":s" with an argument this already happens: >
657 :s/blue/red/
658 /green
659 :s//red/ or :~ or :&r
660 < The last commands will replace "green" with "red". >
661 :s/blue/red/
662 /green
663 :&
664 < The last command will replace "blue" with "red".
665 {not in Vi}
667 Note that there is no flag to change the "magicness" of the pattern. A
668 different command is used instead, or you can use |/\v| and friends. The
669 reason is that the flags can only be found by skipping the pattern, and in
670 order to skip the pattern the "magicness" must be known. Catch 22!
672 If the {pattern} for the substitute command is empty, the command uses the
673 pattern from the last substitute or ":global" command. With the [r] flag, the
674 command uses the pattern from the last substitute, ":global", or search
675 command.
677 If the {string} is omitted the substitute is done as if it's empty. Thus the
678 matched pattern is deleted. The separator after {pattern} can also be left
679 out then. Example: >
680 :%s/TESTING
681 This deletes "TESTING" from all lines, but only one per line.
683 For compatibility with Vi these two exceptions are allowed:
684 "\/{string}/" and "\?{string}?" do the same as "//{string}/r".
685 "\&{string}&" does the same as "//{string}/".
686 *E146*
687 Instead of the '/' which surrounds the pattern and replacement string, you
688 can use any other single-byte character, but not an alphanumeric character,
689 '\', '"' or '|'. This is useful if you want to include a '/' in the search
690 pattern or replacement string. Example: >
691 :s+/+//+
693 For the definition of a pattern, see |pattern|. In Visual block mode, use
694 |/\%V| in the pattern to have the substitute work in the block only.
695 Otherwise it works on whole lines anyway.
697 *sub-replace-special* *:s\=*
698 When the {string} starts with "\=" it is evaluated as an expression, see
699 |sub-replace-expression|. You can use that for any special characters.
700 Otherwise these characters in {string} have a special meaning:
701 *:s%*
702 When {string} is equal to "%" and '/' is included with the 'cpoptions' option,
703 then the {string} of the previous substitute command is used. |cpo-/|
705 magic nomagic action ~
706 & \& replaced with the whole matched pattern *s/\&*
707 \& & replaced with &
708 \0 replaced with the whole matched pattern *\0* *s/\0*
709 \1 replaced with the matched pattern in the first
710 pair of () *s/\1*
711 \2 replaced with the matched pattern in the second
712 pair of () *s/\2*
713 .. .. *s/\3*
714 \9 replaced with the matched pattern in the ninth
715 pair of () *s/\9*
716 ~ \~ replaced with the {string} of the previous
717 substitute *s~*
718 \~ ~ replaced with ~ *s/\~*
719 \u next character made uppercase *s/\u*
720 \U following characters made uppercase, until \E *s/\U*
721 \l next character made lowercase *s/\l*
722 \L following characters made lowercase, until \E *s/\L*
723 \e end of \u, \U, \l and \L (NOTE: not <Esc>!) *s/\e*
724 \E end of \u, \U, \l and \L *s/\E*
725 <CR> split line in two at this point
726 (Type the <CR> as CTRL-V <Enter>) *s<CR>*
727 \r idem *s/\r*
728 \<CR> insert a carriage-return (CTRL-M)
729 (Type the <CR> as CTRL-V <Enter>) *s/\<CR>*
730 \n insert a <NL> (<NUL> in the file)
731 (does NOT break the line) *s/\n*
732 \b insert a <BS> *s/\b*
733 \t insert a <Tab> *s/\t*
734 \\ insert a single backslash *s/\\*
735 \x where x is any character not mentioned above:
736 Reserved for future expansion
738 Examples: >
739 :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx"
740 :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb"
741 :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines)
742 :s/$/\^M/ modifies "abcde" to "abcde^M"
743 :s/\w\+/\u\0/g modifies "bla bla" to "Bla Bla"
745 Note: In previous versions CTRL-V was handled in a special way. Since this is
746 not Vi compatible, this was removed. Use a backslash instead.
748 command text result ~
749 :s/aa/a^Ma/ aa a<line-break>a
750 :s/aa/a\^Ma/ aa a^Ma
751 :s/aa/a\\^Ma/ aa a\<line-break>a
753 (you need to type CTRL-V <CR> to get a ^M here)
755 The numbering of "\1", "\2" etc. is done based on which "\(" comes first in
756 the pattern (going left to right). When a parentheses group matches several
757 times, the last one will be used for "\1", "\2", etc. Example: >
758 :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x"
760 When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\),
761 either the first or second pattern in parentheses did not match, so either
762 \1 or \2 is empty. Example: >
763 :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x"
764 <
766 Substitute with an expression *sub-replace-expression*
767 *sub-replace-\=*
768 When the substitute string starts with "\=" the remainder is interpreted as an
769 expression. This does not work recursively: a substitute() function inside
770 the expression cannot use "\=" for the substitute string.
772 The special meaning for characters as mentioned at |sub-replace-special| does
773 not apply except "<CR>", "\<CR>" and "\\". Thus in the result of the
774 expression you need to use two backslashes get one, put a backslash before a
775 <CR> you want to insert and use a <CR> without a backslash where you want to
776 break the line.
778 For convenience a <NL> character is also used as a line break. Prepend a
779 backslash to get a real <NL> character (which will be a NUL in the file).
781 When the result is a |List| then the items are joined with separating line
782 breaks. Thus each item becomes a line, except that they can contain line
783 breaks themselves.
785 The whole matched text can be accessed with "submatch(0)". The text matched
786 with the first pair of () with "submatch(1)". Likewise for further
787 sub-matches in ().
789 Be careful: The separation character must not appear in the expression!
790 Consider using a character like "@" or ":". There is no problem if the result
791 of the expression contains the separation character.
793 Examples: >
794 :s@\n@\="\r" . expand("$HOME") . "\r"@
795 This replaces an end-of-line with a new line containing the value of $HOME. >
797 s/E/\="\<Char-0x20ac>"/g
798 This replaces 'E' characters with an euro sign. Read more in |<Char->|.
801 4.3 Search and replace *search-replace*
803 *:pro* *:promptfind*
804 :promptf[ind] [string]
805 Put up a Search dialog. When [string] is given, it is
806 used as the initial search string.
807 {only for Win32, Motif and GTK GUI}
809 *:promptr* *:promptrepl*
810 :promptr[epl] [string]
811 Put up a Search/Replace dialog. When [string] is
812 given, it is used as the initial search string.
813 {only for Win32, Motif and GTK GUI}
816 4.4 Changing tabs *change-tabs*
817 *:ret* *:retab*
818 :[range]ret[ab][!] [new_tabstop]
819 Replace all sequences of white-space containing a
820 <Tab> with new strings of white-space using the new
821 tabstop value given. If you do not specify a new
822 tabstop size or it is zero, Vim uses the current value
823 of 'tabstop'.
824 The current value of 'tabstop' is always used to
825 compute the width of existing tabs.
826 With !, Vim also replaces strings of only normal
827 spaces with tabs where appropriate.
828 With 'expandtab' on, Vim replaces all tabs with the
829 appropriate number of spaces.
830 This command sets 'tabstop' to the new value given,
831 and if performed on the whole file, which is default,
832 should not make any visible change.
833 Careful: This command modifies any <Tab> characters
834 inside of strings in a C program. Use "\t" to avoid
835 this (that's a good habit anyway).
836 ":retab!" may also change a sequence of spaces by
837 <Tab> characters, which can mess up a printf().
838 {not in Vi}
839 Not available when |+ex_extra| feature was disabled at
840 compile time.
842 *retab-example*
843 Example for using autocommands and ":retab" to edit a file which is stored
844 with tabstops at 8 but edited with tabstops set at 4. Warning: white space
845 inside of strings can change! Also see 'softtabstop' option. >
847 :auto BufReadPost *.xx retab! 4
848 :auto BufWritePre *.xx retab! 8
849 :auto BufWritePost *.xx retab! 4
850 :auto BufNewFile *.xx set ts=4
852 ==============================================================================
853 5. Copying and moving text *copy-move*
855 *quote*
856 "{a-zA-Z0-9.%#:-"} Use register {a-zA-Z0-9.%#:-"} for next delete, yank
857 or put (use uppercase character to append with
858 delete and yank) ({.%#:} only work with put).
860 *:reg* *:registers*
861 :reg[isters] Display the contents of all numbered and named
862 registers. {not in Vi}
864 :reg[isters] {arg} Display the contents of the numbered and named
865 registers that are mentioned in {arg}. For example: >
866 :dis 1a
867 < to display registers '1' and 'a'. Spaces are allowed
868 in {arg}. {not in Vi}
870 *:di* *:display*
871 :di[splay] [arg] Same as :registers. {not in Vi}
873 *y* *yank*
874 ["x]y{motion} Yank {motion} text [into register x]. When no
875 characters are to be yanked (e.g., "y0" in column 1),
876 this is an error when 'cpoptions' includes the 'E'
877 flag.
879 *yy*
880 ["x]yy Yank [count] lines [into register x] |linewise|.
882 *Y*
883 ["x]Y yank [count] lines [into register x] (synonym for
884 yy, |linewise|). If you like "Y" to work from the
885 cursor to the end of line (which is more logical,
886 but not Vi-compatible) use ":map Y y$".
888 *v_y*
889 {Visual}["x]y Yank the highlighted text [into register x] (for
890 {Visual} see |Visual-mode|). {not in Vi}
892 *v_Y*
893 {Visual}["x]Y Yank the highlighted lines [into register x] (for
894 {Visual} see |Visual-mode|). {not in Vi}
896 *:y* *:yank*
897 :[range]y[ank] [x] Yank [range] lines [into register x].
899 :[range]y[ank] [x] {count}
900 Yank {count} lines, starting with last line number
901 in [range] (default: current line |cmdline-ranges|),
902 [into register x].
904 *p* *put* *E353*
905 ["x]p Put the text [from register x] after the cursor
906 [count] times. {Vi: no count}
908 *P*
909 ["x]P Put the text [from register x] before the cursor
910 [count] times. {Vi: no count}
912 *<MiddleMouse>*
913 ["x]<MiddleMouse> Put the text from a register before the cursor [count]
914 times. Uses the "* register, unless another is
915 specified.
916 Leaves the cursor at the end of the new text.
917 Using the mouse only works when 'mouse' contains 'n'
918 or 'a'.
919 {not in Vi}
920 If you have a scrollwheel and often accidentally paste
921 text, you can use these mappings to disable the
922 pasting with the middle mouse button: >
923 :map <MiddleMouse> <Nop>
924 :imap <MiddleMouse> <Nop>
925 < You might want to disable the multi-click versions
926 too, see |double-click|.
928 *gp*
929 ["x]gp Just like "p", but leave the cursor just after the new
930 text. {not in Vi}
932 *gP*
933 ["x]gP Just like "P", but leave the cursor just after the new
934 text. {not in Vi}
936 *:pu* *:put*
937 :[line]pu[t] [x] Put the text [from register x] after [line] (default
938 current line). This always works |linewise|, thus
939 this command can be used to put a yanked block as new
940 lines.
941 The cursor is left on the first non-blank in the last
942 new line.
943 The register can also be '=' followed by an optional
944 expression. The expression continues until the end of
945 the command. You need to escape the '|' and '"'
946 characters to prevent them from terminating the
947 command. Example: >
948 :put ='path' . \",/test\"
949 < If there is no expression after '=', Vim uses the
950 previous expression. You can see it with ":dis =".
952 :[line]pu[t]! [x] Put the text [from register x] before [line] (default
953 current line).
955 ["x]]p or *]p* *]<MiddleMouse>*
956 ["x]]<MiddleMouse> Like "p", but adjust the indent to the current line.
957 Using the mouse only works when 'mouse' contains 'n'
958 or 'a'. {not in Vi}
960 ["x][P or *[P*
961 ["x]]P or *]P*
962 ["x][p or *[p* *[<MiddleMouse>*
963 ["x][<MiddleMouse> Like "P", but adjust the indent to the current line.
964 Using the mouse only works when 'mouse' contains 'n'
965 or 'a'. {not in Vi}
967 You can use these commands to copy text from one place to another. Do this
968 by first getting the text into a register with a yank, delete or change
969 command, then inserting the register contents with a put command. You can
970 also use these commands to move text from one file to another, because Vim
971 preserves all registers when changing buffers (the CTRL-^ command is a quick
972 way to toggle between two files).
974 *linewise-register* *characterwise-register*
975 You can repeat the put commands with "." (except for :put) and undo them. If
976 the command that was used to get the text into the register was |linewise|,
977 Vim inserts the text below ("p") or above ("P") the line where the cursor is.
978 Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With
979 the ":put" command, Vim always inserts the text in the next line. You can
980 exchange two characters with the command sequence "xp". You can exchange two
981 lines with the command sequence "ddp". You can exchange two words with the
982 command sequence "deep" (start with the cursor in the blank space before the
983 first word). You can use the "']" or "`]" command after the put command to
984 move the cursor to the end of the inserted text, or use "'[" or "`[" to move
985 the cursor to the start.
987 *put-Visual-mode* *v_p* *v_P*
988 When using a put command like |p| or |P| in Visual mode, Vim will try to
989 replace the selected text with the contents of the register. Whether this
990 works well depends on the type of selection and the type of the text in the
991 register. With blockwise selection it also depends on the size of the block
992 and whether the corners are on an existing character. (Implementation detail:
993 it actually works by first putting the register after the selection and then
994 deleting the selection.)
996 *blockwise-register*
997 If you use a blockwise Visual mode command to get the text into the register,
998 the block of text will be inserted before ("P") or after ("p") the cursor
999 column in the current and next lines. Vim makes the whole block of text start
1000 in the same column. Thus the inserted text looks the same as when it was
1001 yanked or deleted. Vim may replace some <Tab> characters with spaces to make
1002 this happen. However, if the width of the block is not a multiple of a <Tab>
1003 width and the text after the inserted block contains <Tab>s, that text may be
1004 misaligned.
1006 Note that after a characterwise yank command, Vim leaves the cursor on the
1007 first yanked character that is closest to the start of the buffer. This means
1008 that "yl" doesn't move the cursor, but "yh" moves the cursor one character
1009 left.
1010 Rationale: In Vi the "y" command followed by a backwards motion would
1011 sometimes not move the cursor to the first yanked character,
1012 because redisplaying was skipped. In Vim it always moves to
1013 the first character, as specified by Posix.
1014 With a linewise yank command the cursor is put in the first line, but the
1015 column is unmodified, thus it may not be on the first yanked character.
1017 There are nine types of registers: *registers* *E354*
1018 1. The unnamed register ""
1019 2. 10 numbered registers "0 to "9
1020 3. The small delete register "-
1021 4. 26 named registers "a to "z or "A to "Z
1022 5. four read-only registers ":, "., "% and "#
1023 6. the expression register "=
1024 7. The selection and drop registers "*, "+ and "~
1025 8. The black hole register "_
1026 9. Last search pattern register "/
1028 1. Unnamed register "" *quote_quote* *quotequote*
1029 Vim fills this register with text deleted with the "d", "c", "s", "x" commands
1030 or copied with the yank "y" command, regardless of whether or not a specific
1031 register was used (e.g. "xdd). This is like the unnamed register is pointing
1032 to the last used register. An exception is the '_' register: "_dd does not
1033 store the deleted text in any register.
1034 Vim uses the contents of the unnamed register for any put command (p or P)
1035 which does not specify a register. Additionally you can access it with the
1036 name '"'. This means you have to type two double quotes. Writing to the ""
1037 register writes to register "0.
1038 {Vi: register contents are lost when changing files, no '"'}
1040 2. Numbered registers "0 to "9 *quote_number* *quote0* *quote1*
1041 *quote2* *quote3* *quote4* *quote9*
1042 Vim fills these registers with text from yank and delete commands.
1043 Numbered register 0 contains the text from the most recent yank command,
1044 unless the command specified another register with ["x].
1045 Numbered register 1 contains the text deleted by the most recent delete or
1046 change command, unless the command specified another register or the text is
1047 less than one line (the small delete register is used then). An exception is
1048 made for the delete operator with these movement commands: |%|, |(|, |)|, |`|,
1049 |/|, |?|, |n|, |N|, |{| and |}|. Register "1 is always used then (this is Vi
1050 compatible). The "- register is used as well if the delete is within a line.
1051 With each successive deletion or change, Vim shifts the previous contents
1052 of register 1 into register 2, 2 into 3, and so forth, losing the previous
1053 contents of register 9.
1054 {Vi: numbered register contents are lost when changing files; register 0 does
1055 not exist}
1057 3. Small delete register "- *quote_-* *quote-*
1058 This register contains text from commands that delete less than one line,
1059 except when the command specifies a register with ["x].
1060 {not in Vi}
1062 4. Named registers "a to "z or "A to "Z *quote_alpha* *quotea*
1063 Vim fills these registers only when you say so. Specify them as lowercase
1064 letters to replace their previous contents or as uppercase letters to append
1065 to their previous contents. When the '>' flag is present in 'cpoptions' then
1066 a line break is inserted before the appended text.
1068 5. Read-only registers ":, "., "% and "#
1069 These are '%', '#', ':' and '.'. You can use them only with the "p", "P",
1070 and ":put" commands and with CTRL-R. {not in Vi}
1071 *quote_.* *quote.* *E29*
1072 ". Contains the last inserted text (the same as what is inserted
1073 with the insert mode commands CTRL-A and CTRL-@). Note: this
1074 doesn't work with CTRL-R on the command-line. It works a bit
1075 differently, like inserting the text instead of putting it
1076 ('textwidth' and other options affect what is inserted).
1077 *quote_%* *quote%*
1078 "% Contains the name of the current file.
1079 *quote_#* *quote#*
1080 "# Contains the name of the alternate file.
1081 *quote_:* *quote:* *E30*
1082 ": Contains the most recent executed command-line. Example: Use
1083 "@:" to repeat the previous command-line command.
1084 The command-line is only stored in this register when at least
1085 one character of it was typed. Thus it remains unchanged if
1086 the command was completely from a mapping.
1087 {not available when compiled without the |+cmdline_hist|
1088 feature}
1090 6. Expression register "= *quote_=* *quote=* *@=*
1091 This is not really a register that stores text, but is a way to use an
1092 expression in commands which use a register. The expression register is
1093 read-only; you cannot put text into it. After the '=', the cursor moves to
1094 the command-line, where you can enter any expression (see |expression|). All
1095 normal command-line editing commands are available, including a special
1096 history for expressions. When you end the command-line by typing <CR>, Vim
1097 computes the result of the expression. If you end it with <Esc>, Vim abandons
1098 the expression. If you do not enter an expression, Vim uses the previous
1099 expression (like with the "/" command). The expression must evaluate to a
1100 string. If the result is a number it's turned into a string. A List,
1101 Dictionary or FuncRef results in an error message (use string() to convert).
1102 If the "= register is used for the "p" command, the string is split up at <NL>
1103 characters. If the string ends in a <NL>, it is regarded as a linewise
1104 register. {not in Vi}
1106 7. Selection and drop registers "*, "+ and "~
1107 Use these register for storing and retrieving the selected text for the GUI.
1108 See |quotestar| and |quoteplus|. When the clipboard is not available or not
1109 working, the unnamed register is used instead. For Unix systems the clipboard
1110 is only available when the |+xterm_clipboard| feature is present. {not in Vi}
1112 Note that there is only a distinction between "* and "+ for X11 systems. For
1113 an explanation of the difference, see |x11-selection|. Under MS-Windows, use
1114 of "* and "+ is actually synonymous and refers to the |gui-clipboard|.
1116 *quote_~* *quote~* *<Drop>*
1117 The read-only "~ register stores the dropped text from the last drag'n'drop
1118 operation. When something has been dropped onto Vim, the "~ register is
1119 filled in and the <Drop> pseudo key is sent for notification. You can remap
1120 this key if you want; the default action (for all modes) is to insert the
1121 contents of the "~ register at the cursor position. {not in Vi}
1122 {only available when compiled with the |+dnd| feature, currently only with the
1123 GTK GUI}
1125 Note: The "~ register is only used when dropping plain text onto Vim.
1126 Drag'n'drop of URI lists is handled internally.
1128 8. Black hole register "_ *quote_*
1129 When writing to this register, nothing happens. This can be used to delete
1130 text without affecting the normal registers. When reading from this register,
1131 nothing is returned. {not in Vi}
1133 9. Last search pattern register "/ *quote_/* *quote/*
1134 Contains the most recent search-pattern. This is used for "n" and 'hlsearch'.
1135 It is writable with ":let", you can change it to have 'hlsearch' highlight
1136 other matches without actually searching. You can't yank or delete into this
1137 register. {not in Vi}
1139 *@/*
1140 You can write to a register with a ":let" command |:let-@|. Example: >
1141 :let @/ = "the"
1143 If you use a put command without specifying a register, Vim uses the register
1144 that was last filled (this is also the contents of the unnamed register). If
1145 you are confused, use the ":dis" command to find out what Vim will put (this
1146 command displays all named and numbered registers; the unnamed register is
1147 labelled '"').
1149 The next three commands always work on whole lines.
1151 :[range]co[py] {address} *:co* *:copy*
1152 Copy the lines given by [range] to below the line
1153 given by {address}.
1155 *:t*
1156 :t Synonym for copy.
1158 :[range]m[ove] {address} *:m* *:mo* *:move* *E134*
1159 Move the lines given by [range] to below the line
1160 given by {address}.
1162 ==============================================================================
1163 6. Formatting text *formatting*
1165 :[range]ce[nter] [width] *:ce* *:center*
1166 Center lines in [range] between [width] columns
1167 (default 'textwidth' or 80 when 'textwidth' is 0).
1168 {not in Vi}
1169 Not available when |+ex_extra| feature was disabled at
1170 compile time.
1172 :[range]ri[ght] [width] *:ri* *:right*
1173 Right-align lines in [range] at [width] columns
1174 (default 'textwidth' or 80 when 'textwidth' is 0).
1175 {not in Vi}
1176 Not available when |+ex_extra| feature was disabled at
1177 compile time.
1179 *:le* *:left*
1180 :[range]le[ft] [indent]
1181 Left-align lines in [range]. Sets the indent in the
1182 lines to [indent] (default 0). {not in Vi}
1183 Not available when |+ex_extra| feature was disabled at
1184 compile time.
1186 *gq*
1187 gq{motion} Format the lines that {motion} moves over.
1188 Formatting is done with one of three methods:
1189 1. If 'formatexpr' is not empty the expression is
1190 evaluated. This can differ for each buffer.
1191 2. If 'formatprg' is not empty an external program
1192 is used.
1193 3. Otherwise formatting is done internally.
1195 In the third case the 'textwidth' option controls the
1196 length of each formatted line (see below).
1197 If the 'textwidth' option is 0, the formatted line
1198 length is the screen width (with a maximum width of
1199 79).
1200 The 'formatoptions' option controls the type of
1201 formatting |fo-table|.
1202 The cursor is left on the first non-blank of the last
1203 formatted line.
1204 NOTE: The "Q" command formerly performed this
1205 function. If you still want to use "Q" for
1206 formatting, use this mapping: >
1207 :nnoremap Q gq
1209 gqgq *gqgq* *gqq*
1210 gqq Format the current line. {not in Vi}
1212 *v_gq*
1213 {Visual}gq Format the highlighted text. (for {Visual} see
1214 |Visual-mode|). {not in Vi}
1216 *gw*
1217 gw{motion} Format the lines that {motion} moves over. Similar to
1218 |gq| but puts the cursor back at the same position in
1219 the text. However, 'formatprg' and 'formatexpr' are
1220 not used. {not in Vi}
1222 gwgw *gwgw* *gww*
1223 gww Format the current line as with "gw". {not in Vi}
1225 *v_gw*
1226 {Visual}gw Format the highlighted text as with "gw". (for
1227 {Visual} see |Visual-mode|). {not in Vi}
1229 Example: To format the current paragraph use: *gqap* >
1230 gqap
1232 The "gq" command leaves the cursor in the line where the motion command takes
1233 the cursor. This allows you to repeat formatting repeated with ".". This
1234 works well with "gqj" (format current and next line) and "gq}" (format until
1235 end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on
1236 the first formatted line (as with using a filter command).
1238 If you want to format the current paragraph and continue where you were, use: >
1239 gwap
1240 If you always want to keep paragraphs formatted you may want to add the 'a'
1241 flag to 'formatoptions'. See |auto-format|.
1243 If the 'autoindent' option is on, Vim uses the indent of the first line for
1244 the following lines.
1246 Formatting does not change empty lines (but it does change lines with only
1247 white space!).
1249 The 'joinspaces' option is used when lines are joined together.
1251 You can set the 'formatexpr' option to an expression or the 'formatprg' option
1252 to the name of an external program for Vim to use for text formatting. The
1253 'textwidth' and other options have no effect on formatting by an external
1254 program.
1256 *right-justify*
1257 There is no command in Vim to right justify text. You can do it with
1258 an external command, like "par" (e.g.: "!}par" to format until the end of the
1259 paragraph) or set 'formatprg' to "par".
1261 *format-comments*
1262 Vim can format comments in a special way. Vim recognizes a comment by a
1263 specific string at the start of the line (ignoring white space). Three types
1264 of comments can be used:
1266 - A comment string that repeats at the start of each line. An example is the
1267 type of comment used in shell scripts, starting with "#".
1268 - A comment string that occurs only in the first line, not in the following
1269 lines. An example is this list with dashes.
1270 - Three-piece comments that have a start string, an end string, and optional
1271 lines in between. The strings for the start, middle and end are different.
1272 An example is the C-style comment:
1273 /*
1274 * this is a C comment
1275 */
1277 The 'comments' option is a comma-separated list of parts. Each part defines a
1278 type of comment string. A part consists of:
1279 {flags}:{string}
1281 {string} is the literal text that must appear.
1283 {flags}:
1284 n Nested comment. Nesting with mixed parts is allowed. If 'comments'
1285 is "n:),n:>" a line starting with "> ) >" is a comment.
1287 b Blank (<Space>, <Tab> or <EOL>) required after {string}.
1289 f Only the first line has the comment string. Do not repeat comment on
1290 the next line, but preserve indentation (e.g., a bullet-list).
1292 s Start of three-piece comment
1294 m Middle of a three-piece comment
1296 e End of a three-piece comment
1298 l Left adjust middle with start or end (default). Only recognized when
1299 used together with 's' or 'e'.
1301 r Right adjust middle with start or end. Only recognized when used
1302 together with 's' or 'e'.
1304 O Don't use this one for the "O" command.
1306 x Allows three-piece comments to be ended by just typing the last
1307 character of the end-comment string as the first character on a new
1308 line, when the middle-comment string has already been inserted
1309 automatically. See below for more details.
1311 {digits}
1312 When together with 's' or 'e': add extra indent for the middle part.
1313 This can be used to left-align the middle part with the start or end
1314 and then add an offset.
1316 -{digits}
1317 Like {digits} but reduce the indent. This only works when there is
1318 some indent for the start or end part that can be removed.
1320 When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the
1321 comment string repeats at the start of each line. The flags field may be
1322 empty.
1324 Any blank space in the text before and after the {string} is part of the
1325 {string}, so do not include leading or trailing blanks unless the blanks are a
1326 required part of the comment string.
1328 When one comment leader is part of another, specify the part after the whole.
1329 For example, to include both "-" and "->", use >
1330 :set comments=f:->,f:-
1332 A three-piece comment must always be given as start,middle,end, with no other
1333 parts in between. An example of a three-piece comment is >
1334 sr:/*,mb:*,ex:*/
1335 for C-comments. To avoid recognizing "*ptr" as a comment, the middle string
1336 includes the 'b' flag. For three-piece comments, Vim checks the text after
1337 the start and middle strings for the end string. If Vim finds the end string,
1338 the comment does not continue on the next line. Three-piece comments must
1339 have a middle string because otherwise Vim can't recognize the middle lines.
1341 Notice the use of the "x" flag in the above three-piece comment definition.
1342 When you hit Return in a C-comment, Vim will insert the middle comment leader
1343 for the new line, e.g. " * ". To close this comment you just have to type "/"
1344 before typing anything else on the new line. This will replace the
1345 middle-comment leader with the end-comment leader, leaving just " */". There
1346 is no need to hit BackSpace first.
1348 Examples: >
1349 "b:*" Includes lines starting with "*", but not if the "*" is
1350 followed by a non-blank. This avoids a pointer dereference
1351 like "*str" to be recognized as a comment.
1352 "n:>" Includes a line starting with ">", ">>", ">>>", etc.
1353 "fb:-" Format a list that starts with "- ".
1355 By default, "b:#" is included. This means that a line that starts with
1356 "#include" is not recognized as a comment line. But a line that starts with
1357 "# define" is recognized. This is a compromise.
1359 Often the alignment can be changed from right alignment to a left alignment
1360 with an additional space. For example, for Javadoc comments, this can be
1361 used (insert a backslash before the space when using ":set"): >
1362 s1:/*,mb:*,ex:*/
1363 Note that an offset is included with start, so that the middle part is left
1364 aligned with the start and then an offset of one character added. This makes
1365 it possible to left align the start and middle for this construction: >
1366 /**
1367 * comment
1368 */
1370 {not available when compiled without the |+comments| feature}
1372 *fo-table*
1373 You can use the 'formatoptions' option to influence how Vim formats text.
1374 'formatoptions' is a string that can contain any of the letters below. The
1375 default setting is "tcq". You can separate the option letters with commas for
1376 readability.
1378 letter meaning when present in 'formatoptions' ~
1380 t Auto-wrap text using textwidth
1381 c Auto-wrap comments using textwidth, inserting the current comment
1382 leader automatically.
1383 r Automatically insert the current comment leader after hitting
1384 <Enter> in Insert mode.
1385 o Automatically insert the current comment leader after hitting 'o' or
1386 'O' in Normal mode.
1387 q Allow formatting of comments with "gq".
1388 Note that formatting will not change blank lines or lines containing
1389 only the comment leader. A new paragraph starts after such a line,
1390 or when the comment leader changes.
1391 w Trailing white space indicates a paragraph continues in the next line.
1392 A line that ends in a non-white character ends a paragraph.
1393 a Automatic formatting of paragraphs. Every time text is inserted or
1394 deleted the paragraph will be reformatted. See |auto-format|.
1395 When the 'c' flag is present this only happens for recognized
1396 comments.
1397 n When formatting text, recognize numbered lists. This actually uses
1398 the 'formatlistpat' option, thus any kind of list can be used. The
1399 indent of the text after the number is used for the next line. The
1400 default is to find a number, optionally be followed by '.', ':', ')',
1401 ']' or '}'. Note that 'autoindent' must be set too. Doesn't work
1402 well together with "2".
1403 Example: >
1404 1. the first item
1405 wraps
1406 2. the second item
1407 2 When formatting text, use the indent of the second line of a paragraph
1408 for the rest of the paragraph, instead of the indent of the first
1409 line. This supports paragraphs in which the first line has a
1410 different indent than the rest. Note that 'autoindent' must be set
1411 too. Example: >
1412 first line of a paragraph
1413 second line of the same paragraph
1414 third line.
1415 v Vi-compatible auto-wrapping in insert mode: Only break a line at a
1416 blank that you have entered during the current insert command. (Note:
1417 this is not 100% Vi compatible. Vi has some "unexpected features" or
1418 bugs in this area. It uses the screen column instead of the line
1419 column.)
1420 b Like 'v', but only auto-wrap if you enter a blank at or before
1421 the wrap margin. If the line was longer than 'textwidth' when you
1422 started the insert, or you do not enter a blank in the insert before
1423 reaching 'textwidth', Vim does not perform auto-wrapping.
1424 l Long lines are not broken in insert mode: When a line was longer than
1425 'textwidth' when the insert command started, Vim does not
1426 automatically format it.
1427 m Also break at a multi-byte character above 255. This is useful for
1428 Asian text where every character is a word on its own.
1429 M When joining lines, don't insert a space before or after a multi-byte
1430 character. Overrules the 'B' flag.
1431 B When joining lines, don't insert a space between two multi-byte
1432 characters. Overruled by the 'M' flag.
1433 1 Don't break a line after a one-letter word. It's broken before it
1434 instead (if possible).
1437 With 't' and 'c' you can specify when Vim performs auto-wrapping:
1438 value action ~
1439 "" no automatic formatting (you can use "gq" for manual formatting)
1440 "t" automatic formatting of text, but not comments
1441 "c" automatic formatting for comments, but not text (good for C code)
1442 "tc" automatic formatting for text and comments
1444 Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but
1445 does insert comment leaders according to the 'comments' option). An exception
1446 is when the 'a' flag is present. |auto-format|
1448 Note that when 'paste' is on, Vim does no formatting at all.
1450 Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping;
1451 'textwidth' is still useful for formatting with "gq".
1453 If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some
1454 built in stuff to treat these types of comments a bit more cleverly.
1455 Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in
1456 'formatoptions') gives the correct start of the line automatically. The same
1457 happens with formatting and auto-wrapping. Opening a line after a line
1458 starting with "/*" or "*" and containing "*/", will cause no comment leader to
1459 be inserted, and the indent of the new line is taken from the line containing
1460 the start of the comment.
1461 E.g.:
1462 /* ~
1463 * Your typical comment. ~
1464 */ ~
1465 The indent on this line is the same as the start of the above
1466 comment.
1468 All of this should be really cool, especially in conjunction with the new
1469 :autocmd command to prepare different settings for different types of file.
1471 Some examples:
1472 for C code (only format comments): >
1473 :set fo=croq
1474 < for Mail/news (format all, don't start comment with "o" command): >
1475 :set fo=tcrq
1476 <
1478 Automatic formatting *auto-format*
1480 When the 'a' flag is present in 'formatoptions' text is formatted
1481 automatically when inserting text or deleting text. This works nice for
1482 editing text paragraphs. A few hints on how to use this:
1484 - You need to properly define paragraphs. The simplest is paragraphs that are
1485 separated by a blank line. When there is no separating blank line, consider
1486 using the 'w' flag and adding a space at the end of each line in the
1487 paragraphs except the last one.
1489 - You can set the 'formatoptions' based on the type of file |filetype| or
1490 specifically for one file with a |modeline|.
1492 - Set 'formatoptions' to "aw2tq" to make text with indents like this:
1494 bla bla foobar bla
1495 bla foobar bla foobar bla
1496 bla bla foobar bla
1497 bla foobar bla bla foobar
1499 - Add the 'c' flag to only auto-format comments. Useful in source code.
1501 - Set 'textwidth' to the desired width. If it is zero then 79 is used, or the
1502 width of the screen if this is smaller.
1504 And a few warnings:
1506 - When part of the text is not properly separated in paragraphs, making
1507 changes in this text will cause it to be formatted anyway. Consider doing >
1509 :set fo-=a
1511 - When using the 'w' flag (trailing space means paragraph continues) and
1512 deleting the last line of a paragraph with |dd|, the paragraph will be
1513 joined with the next one.
1515 - Changed text is saved for undo. Formatting is also a change. Thus each
1516 format action saves text for undo. This may consume quite a lot of memory.
1518 - Formatting a long paragraph and/or with complicated indenting may be slow.
1520 ==============================================================================
1521 7. Sorting text *sorting*
1523 Vim has a sorting function and a sorting command. The sorting function can be
1524 found here: |sort()|.
1526 *:sor* *:sort*
1527 :[range]sor[t][!] [i][u][r][n][x][o] [/{pattern}/]
1528 Sort lines in [range]. When no range is given all
1529 lines are sorted.
1531 With [!] the order is reversed.
1533 With [i] case is ignored.
1535 With [n] sorting is done on the first decimal number
1536 in the line (after or inside a {pattern} match).
1538 With [x] sorting is done on the first hexadecimal
1539 number in the line (after or inside a {pattern}
1540 match). A leading "0x" or "0X" is ignored.
1542 With [o] sorting is done on the first octal number in
1543 the line (after or inside a {pattern} match).
1545 With [u] only keep the first of a sequence of
1546 identical lines (ignoring case when [i] is used).
1547 Without this flag, a sequence of identical lines
1548 will be kept in their original order.
1549 Note that leading and trailing white space may cause
1550 lines to be different.
1552 When /{pattern}/ is specified and there is no [r] flag
1553 the text matched with {pattern} is skipped, so that
1554 you sort on what comes after the match.
1555 Instead of the slash any non-letter can be used.
1556 For example, to sort on the second comma-separated
1557 field: >
1558 :sort /[^,]*,/
1559 < To sort on the text at virtual column 10 (thus
1560 ignoring the difference between tabs and spaces): >
1561 :sort /.*\%10v/
1562 < To sort on the first number in the line, no matter
1563 what is in front of it: >
1564 :sort /.\{-}\ze\d/
1565 < (Explanation: ".\{-}" matches any text, "\ze" sets the
1566 end of the match and \d matches a digit.)
1567 With [r] sorting is done on the matching {pattern}
1568 instead of skipping past it as described above.
1569 For example, to sort on only the first three letters
1570 of each line: >
1571 :sort /\a\a\a/ r
1573 < If a {pattern} is used, any lines which don't have a
1574 match for {pattern} are kept in their current order,
1575 but separate from the lines which do match {pattern}.
1576 If you sorted in reverse, they will be in reverse
1577 order after the sorted lines, otherwise they will be
1578 in their original order, right before the sorted
1579 lines.
1581 If {pattern} is empty (e.g. // is specified), the
1582 last search pattern is used. This allows trying out
1583 a pattern first.
1585 Note that using ":sort" with ":global" doesn't sort the matching lines, it's
1586 quite useless.
1588 The details about sorting depend on the library function used. There is no
1589 guarantee that sorting is "stable" or obeys the current locale. You will have
1590 to try it out.
1592 The sorting can be interrupted, but if you interrupt it too late in the
1593 process you may end up with duplicated lines. This also depends on the system
1594 library function used.
1596 vim:tw=78:ts=8:ft=help:norl: