| blob | e97be4d6dda117c73f3c4f02f41430765e207674 |
1 *change.txt* For Vim version 7.1b. Last change: 2007 Jan 07
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}.
349 Adding and subtracting ~
350 *CTRL-A*
351 CTRL-A Add [count] to the number or alphabetic character at
352 or after the cursor. {not in Vi}
354 *CTRL-X*
355 CTRL-X Subtract [count] from the number or alphabetic
356 character at or after the cursor. {not in Vi}
358 The CTRL-A and CTRL-X commands work for (signed) decimal numbers, unsigned
359 octal and hexadecimal numbers and alphabetic characters. This depends on the
360 'nrformats' option.
361 - When 'nrformats' includes "octal", Vim considers numbers starting with a '0'
362 to be octal, unless the number includes a '8' or '9'. Other numbers are
363 decimal and may have a preceding minus sign.
364 If the cursor is on a number, the commands apply to that number; otherwise
365 Vim uses the number to the right of the cursor.
366 - When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or
367 '0X' are hexadecimal. The case of the rightmost letter in the number
368 determines the case of the resulting hexadecimal number. If there is no
369 letter in the current number, Vim uses the previously detected case.
370 - When 'nrformats' includes "alpha", Vim will change the alphabetic character
371 under or after the cursor. This is useful to make lists with an alphabetic
372 index.
374 For numbers with leading zeros (including all octal and hexadecimal numbers),
375 Vim preserves the number of characters in the number when possible. CTRL-A on
376 "0077" results in "0100", CTRL-X on "0x100" results in "0x0ff".
377 There is one exception: When a number that starts with a zero is found not to
378 be octal (it contains a '8' or '9'), but 'nrformats' does include "octal",
379 leading zeros are removed to avoid that the result may be recognized as an
380 octal number.
382 Note that when 'nrformats' includes "octal", decimal numbers with leading
383 zeros cause mistakes, because they can be confused with octal numbers.
385 The CTRL-A command is very useful in a macro. Example: Use the following
386 steps to make a numbered list.
388 1. Create the first list entry, make sure it starts with a number.
389 2. qa - start recording into register 'a'
390 3. Y - yank the entry
391 4. p - put a copy of the entry below the first one
392 5. CTRL-A - increment the number
393 6. q - stop recording
394 7. <count>@a - repeat the yank, put and increment <count> times
397 SHIFTING LINES LEFT OR RIGHT *shift-left-right*
399 *<*
400 <{motion} Shift {motion} lines one 'shiftwidth' leftwards.
402 *<<*
403 << Shift [count] lines one 'shiftwidth' leftwards.
405 *v_<*
406 {Visual}[count]< Shift the highlighted lines [count] 'shiftwidth'
407 leftwards (for {Visual} see |Visual-mode|). {not in
408 Vi}
410 *>*
411 >{motion} Shift {motion} lines one 'shiftwidth' rightwards.
413 *>>*
414 >> Shift [count] lines one 'shiftwidth' rightwards.
416 *v_>*
417 {Visual}[count]> Shift the highlighted lines [count] 'shiftwidth'
418 rightwards (for {Visual} see |Visual-mode|). {not in
419 Vi}
421 *:<*
422 :[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<'
423 for shifting multiple 'shiftwidth's.
425 :[range]< {count} Shift {count} lines one 'shiftwidth' left, starting
426 with [range] (default current line |cmdline-ranges|).
427 Repeat '<' for shifting multiple 'shiftwidth's.
429 :[range]le[ft] [indent] left align lines in [range]. Sets the indent in the
430 lines to [indent] (default 0). {not in Vi}
432 *:>*
433 :[range]> [flags] Shift {count} [range] lines one 'shiftwidth' right.
434 Repeat '>' for shifting multiple 'shiftwidth's.
435 See |ex-flags| for [flags].
437 :[range]> {count} [flags]
438 Shift {count} lines one 'shiftwidth' right, starting
439 with [range] (default current line |cmdline-ranges|).
440 Repeat '>' for shifting multiple 'shiftwidth's.
441 See |ex-flags| for [flags].
443 The ">" and "<" commands are handy for changing the indentation within
444 programs. Use the 'shiftwidth' option to set the size of the white space
445 which these commands insert or delete. Normally the 'shiftwidth' option is 8,
446 but you can set it to, say, 3 to make smaller indents. The shift leftwards
447 stops when there is no indent. The shift right does not affect empty lines.
449 If the 'shiftround' option is on, the indent is rounded to a multiple of
450 'shiftwidth'.
452 If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains
453 '#', shift right does not affect lines starting with '#' (these are supposed
454 to be C preprocessor lines that must stay in column 1).
456 When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as
457 much as possible to make the indent. You can use ">><<" to replace an indent
458 made out of spaces with the same indent made out of <Tab>s (and a few spaces
459 if necessary). If the 'expandtab' option is on, Vim uses only spaces. Then
460 you can use ">><<" to replace <Tab>s in the indent by spaces (or use
461 ":retab!").
463 To move a line several 'shiftwidth's, use Visual mode or the ":" commands.
464 For example: >
465 Vjj4> move three lines 4 indents to the right
466 :<<< move current line 3 indents to the left
467 :>> 5 move 5 lines 2 indents to the right
468 :5>> move line 5 2 indents to the right
470 ==============================================================================
471 4. Complex changes *complex-change*
473 4.1 Filter commands *filter*
475 A filter is a program that accepts text at standard input, changes it in some
476 way, and sends it to standard output. You can use the commands below to send
477 some text through a filter, so that it is replace by the filter output.
478 Examples of filters are "sort", which sorts lines alphabetically, and
479 "indent", which formats C program files (you need a version of indent that
480 works like a filter; not all versions do). The 'shell' option specifies the
481 shell Vim uses to execute the filter command (See also the 'shelltype'
482 option). You can repeat filter commands with ".". Vim does not recognize a
483 comment (starting with '"') after the ":!" command.
485 *!*
486 !{motion}{filter} Filter {motion} text lines through the external
487 program {filter}.
489 *!!*
490 !!{filter} Filter [count] lines through the external program
491 {filter}.
493 *v_!*
494 {Visual}!{filter} Filter the highlighted lines through the external
495 program {filter} (for {Visual} see |Visual-mode|).
496 {not in Vi}
498 :{range}![!]{filter} [!][arg] *:range!*
499 Filter {range} lines through the external program
500 {filter}. Vim replaces the optional bangs with the
501 latest given command and appends the optional [arg].
502 Vim saves the output of the filter command in a
503 temporary file and then reads the file into the
504 buffer. Vim uses the 'shellredir' option to redirect
505 the filter output to the temporary file.
506 However, if the 'shelltemp' option is off then pipes
507 are used when possible (on Unix).
508 When the 'R' flag is included in 'cpoptions' marks in
509 the filtered lines are deleted, unless the
510 |:keepmarks| command is used. Example: >
511 :keepmarks '<,'>!sort
512 < When the number of lines after filtering is less than
513 before, marks in the missing lines are deleted anyway.
515 *=*
516 ={motion} Filter {motion} lines through the external program
517 given with the 'equalprg' option. When the 'equalprg'
518 option is empty (this is the default), use the
519 internal formatting function |C-indenting|. But when
520 'indentexpr' is not empty, it will be used instead
521 |indent-expression|.
523 *==*
524 == Filter [count] lines like with ={motion}.
526 *v_=*
527 {Visual}= Filter the highlighted lines like with ={motion}.
528 {not in Vi}
531 4.2 Substitute *:substitute*
532 *:s* *:su*
533 :[range]s[ubstitute]/{pattern}/{string}/[flags] [count]
534 For each line in [range] replace a match of {pattern}
535 with {string}.
536 For the {pattern} see |pattern|.
537 {string} can be a literal string, or something
538 special; see |sub-replace-special|.
539 When [range] and [count] are omitted, replace in the
540 current line only.
541 When [count] is given, replace in [count] lines,
542 starting with the last line in [range]. When [range]
543 is omitted start in the current line.
544 Also see |cmdline-ranges|.
545 See |:s_flags| for [flags].
547 :[range]s[ubstitute] [flags] [count]
548 :[range]&[&][flags] [count] *:&*
549 Repeat last :substitute with same search pattern and
550 substitute string, but without the same flags. You
551 may add [flags], see |:s_flags|.
552 Note that after ":substitute" the '&' flag can't be
553 used, it's recognized as a pattern separator.
554 The space between ":substitute" and the 'c', 'g' and
555 'r' flags isn't required, but in scripts it's a good
556 idea to keep it to avoid confusion.
558 :[range]~[&][flags] [count] *:~*
559 Repeat last substitute with same substitute string
560 but with last used search pattern. This is like
561 ":&r". See |:s_flags| for [flags].
563 *&*
564 & Synonym for ":s//~/" (repeat last substitute). Note
565 that the flags are not remembered, thus it might
566 actually work differently. You can use ":&&" to keep
567 the flags.
569 *g&*
570 g& Synonym for ":%s//~/&" (repeat last substitute on all
571 lines with the same flags).
572 Mnemonic: global substitute. {not in Vi}
574 *:snomagic* *:sno*
575 :[range]sno[magic] ... Same as ":substitute", but always use 'nomagic'.
576 {not in Vi}
578 *:smagic* *:sm*
579 :[range]sm[agic] ... Same as ":substitute", but always use 'magic'.
580 {not in Vi}
582 *:s_flags*
583 The flags that you can use for the substitute commands:
585 [&] Must be the first one: Keep the flags from the previous substitute
586 command. Examples: >
587 :&&
588 :s/this/that/&
589 < Note that ":s" and ":&" don't keep the flags.
590 {not in Vi}
592 [c] Confirm each substitution. Vim highlights the matching string (with
593 |hl-IncSearch|). You can type: *:s_c*
594 'y' to substitute this match
595 'l' to substitute this match and then quit ("last")
596 'n' to skip this match
597 <Esc> to quit substituting
598 'a' to substitute this and all remaining matches {not in Vi}
599 'q' to quit substituting {not in Vi}
600 CTRL-E to scroll the screen up {not in Vi, not available when
601 compiled without the +insert_expand feature}
602 CTRL-Y to scroll the screen down {not in Vi, not available when
603 compiled without the +insert_expand feature}
604 If the 'edcompatible' option is on, Vim remembers the [c] flag and
605 toggles it each time you use it, but resets it when you give a new
606 search pattern.
607 {not in Vi: highlighting of the match, other responses than 'y' or 'n'}
609 [e] When the search pattern fails, do not issue an error message and, in
610 particular, continue in maps as if no error occurred. This is most
611 useful to prevent the "No match" error from breaking a mapping. Vim
612 does not suppress the following error messages, however:
613 Regular expressions can't be delimited by letters
614 \ should be followed by /, ? or &
615 No previous substitute regular expression
616 Trailing characters
617 Interrupted
618 {not in Vi}
620 [g] Replace all occurrences in the line. Without this argument,
621 replacement occurs only for the first occurrence in each line. If
622 the 'edcompatible' option is on, Vim remembers this flag and toggles
623 it each time you use it, but resets it when you give a new search
624 pattern. If the 'gdefault' option is on, this flag is on by default
625 and the [g] argument switches it off.
627 [i] Ignore case for the pattern. The 'ignorecase' and 'smartcase' options
628 are not used.
629 {not in Vi}
631 [I] Don't ignore case for the pattern. The 'ignorecase' and 'smartcase'
632 options are not used.
633 {not in Vi}
635 [n] Report the number of matches, do not actually substitute. The [c]
636 flag is ignored. The matches are reported as if 'report' is zero.
637 Useful to |count-items|.
639 [p] Print the line containing the last substitute.
641 [#] Like [p] and prepend the line number.
643 [l] Like [p] but print the text like |:list|.
645 [r] Only useful in combination with ":&" or ":s" without arguments. ":&r"
646 works the same way as ":~": When the search pattern is empty, use the
647 previously used search pattern instead of the search pattern from the
648 last substitute or ":global". If the last command that did a search
649 was a substitute or ":global", there is no effect. If the last
650 command was a search command such as "/", use the pattern from that
651 command.
652 For ":s" with an argument this already happens: >
653 :s/blue/red/
654 /green
655 :s//red/ or :~ or :&r
656 < The last commands will replace "green" with "red". >
657 :s/blue/red/
658 /green
659 :&
660 < The last command will replace "blue" with "red".
661 {not in Vi}
663 Note that there is no flag to change the "magicness" of the pattern. A
664 different command is used instead. The reason is that the flags can only be
665 found by skipping the pattern, and in order to skip the pattern the
666 "magicness" must be known. Catch 22!
668 If the {pattern} for the substitute command is empty, the command uses the
669 pattern from the last substitute or ":global" command. With the [r] flag, the
670 command uses the pattern from the last substitute, ":global", or search
671 command.
673 If the {string} is omitted the substitute is done as if it's empty. Thus the
674 matched pattern is deleted. The separator after {pattern} can also be left
675 out then. Example: >
676 :%s/TESTING
677 This deletes "TESTING" from all lines, but only one per line.
679 For compatibility with Vi these two exceptions are allowed:
680 "\/{string}/" and "\?{string}?" do the same as "//{string}/r".
681 "\&{string}&" does the same as "//{string}/".
682 *E146*
683 Instead of the '/' which surrounds the pattern and replacement string, you
684 can use any other single-byte character, but not an alphanumeric character,
685 '\', '"' or '|'. This is useful if you want to include a '/' in the search
686 pattern or replacement string. Example: >
687 :s+/+//+
689 For the definition of a pattern, see |pattern|.
691 *sub-replace-special* *:s\=*
692 When the {string} starts with "\=" it is evaluated as an expression, see
693 |sub-replace-expression|. You can use that for any special characters.
694 Otherwise these characters in {string} have a special meaning:
695 *:s%*
696 When {string} is equal to "%" and '/' is included with the 'cpoptions' option,
697 then the {string} of the previous substitute command is used. |cpo-/|
699 magic nomagic action ~
700 & \& replaced with the whole matched pattern *s/\&*
701 \& & replaced with &
702 \0 replaced with the whole matched pattern *\0* *s/\0*
703 \1 replaced with the matched pattern in the first
704 pair of () *s/\1*
705 \2 replaced with the matched pattern in the second
706 pair of () *s/\2*
707 .. .. *s/\3*
708 \9 replaced with the matched pattern in the ninth
709 pair of () *s/\9*
710 ~ \~ replaced with the {string} of the previous
711 substitute *s~*
712 \~ ~ replaced with ~ *s/\~*
713 \u next character made uppercase *s/\u*
714 \U following characters made uppercase, until \E *s/\U*
715 \l next character made lowercase *s/\l*
716 \L following characters made lowercase, until \E *s/\L*
717 \e end of \u, \U, \l and \L (NOTE: not <Esc>!) *s/\e*
718 \E end of \u, \U, \l and \L *s/\E*
719 <CR> split line in two at this point
720 (Type the <CR> as CTRL-V <Enter>) *s<CR>*
721 \r idem *s/\r*
722 \<CR> insert a carriage-return (CTRL-M)
723 (Type the <CR> as CTRL-V <Enter>) *s/\<CR>*
724 \n insert a <NL> (<NUL> in the file)
725 (does NOT break the line) *s/\n*
726 \b insert a <BS> *s/\b*
727 \t insert a <Tab> *s/\t*
728 \\ insert a single backslash *s/\\*
729 \x where x is any character not mentioned above:
730 Reserved for future expansion
732 Examples: >
733 :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx"
734 :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb"
735 :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines)
736 :s/$/\^M/ modifies "abcde" to "abcde^M"
737 :s/\w\+/\u\0/g modifies "bla bla" to "Bla Bla"
739 Note: In previous versions CTRL-V was handled in a special way. Since this is
740 not Vi compatible, this was removed. Use a backslash instead.
742 command text result ~
743 :s/aa/a^Ma/ aa a<line-break>a
744 :s/aa/a\^Ma/ aa a^Ma
745 :s/aa/a\\^Ma/ aa a\<line-break>a
747 (you need to type CTRL-V <CR> to get a ^M here)
749 The numbering of "\1", "\2" etc. is done based on which "\(" comes first in
750 the pattern (going left to right). When a parentheses group matches several
751 times, the last one will be used for "\1", "\2", etc. Example: >
752 :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x"
754 When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\),
755 either the first or second pattern in parentheses did not match, so either
756 \1 or \2 is empty. Example: >
757 :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x"
758 <
760 Substitute with an expression *sub-replace-expression*
761 *sub-replace-\=*
762 When the substitute string starts with "\=" the remainder is interpreted as an
763 expression. This does not work recursively: a substitute() function inside
764 the expression cannot use "\=" for the substitute string.
766 The special meaning for characters as mentioned at |sub-replace-special| does
767 not apply except "<CR>", "\<CR>" and "\\". Thus in the result of the
768 expression you need to use two backslashes get one, put a backslash before a
769 <CR> you want to insert and use a <CR> without a backslash where you want to
770 break the line.
772 For convenience a <NL> character is also used as a line break. Prepend a
773 backslash to get a real <NL> character (which will be a NUL in the file).
775 When the result is a |List| then the items are joined with separating line
776 breaks. Thus each item becomes a line, except that they can contain line
777 breaks themselves.
779 The whole matched text can be accessed with "submatch(0)". The text matched
780 with the first pair of () with "submatch(1)". Likewise for further
781 sub-matches in ().
783 Be careful: The separation character must not appear in the expression!
784 Consider using a character like "@" or ":". There is no problem if the result
785 of the expression contains the separation character.
787 Examples: >
788 :s@\n@\="\r" . expand("$HOME") . "\r"@
789 This replaces an end-of-line with a new line containing the value of $HOME. >
791 s/E/\="\<Char-0x20ac>"/g
792 This replaces 'E' characters with an euro sign. Read more in |<Char->|.
795 4.3 Search and replace *search-replace*
797 *:pro* *:promptfind*
798 :promptf[ind] [string]
799 Put up a Search dialog. When [string] is given, it is
800 used as the initial search string.
801 {only for Win32, Motif and GTK GUI}
803 *:promptr* *:promptrepl*
804 :promptr[epl] [string]
805 Put up a Search/Replace dialog. When [string] is
806 given, it is used as the initial search string.
807 {only for Win32, Motif and GTK GUI}
810 4.4 Changing tabs *change-tabs*
811 *:ret* *:retab*
812 :[range]ret[ab][!] [new_tabstop]
813 Replace all sequences of white-space containing a
814 <Tab> with new strings of white-space using the new
815 tabstop value given. If you do not specify a new
816 tabstop size or it is zero, Vim uses the current value
817 of 'tabstop'.
818 The current value of 'tabstop' is always used to
819 compute the width of existing tabs.
820 With !, Vim also replaces strings of only normal
821 spaces with tabs where appropriate.
822 With 'expandtab' on, Vim replaces all tabs with the
823 appropriate number of spaces.
824 This command sets 'tabstop' to the new value given,
825 and if performed on the whole file, which is default,
826 should not make any visible change.
827 Careful: This command modifies any <Tab> characters
828 inside of strings in a C program. Use "\t" to avoid
829 this (that's a good habit anyway).
830 ":retab!" may also change a sequence of spaces by
831 <Tab> characters, which can mess up a printf().
832 {not in Vi}
833 Not available when |+ex_extra| feature was disabled at
834 compile time.
836 *retab-example*
837 Example for using autocommands and ":retab" to edit a file which is stored
838 with tabstops at 8 but edited with tabstops set at 4. Warning: white space
839 inside of strings can change! Also see 'softtabstop' option. >
841 :auto BufReadPost *.xx retab! 4
842 :auto BufWritePre *.xx retab! 8
843 :auto BufWritePost *.xx retab! 4
844 :auto BufNewFile *.xx set ts=4
846 ==============================================================================
847 5. Copying and moving text *copy-move*
849 *quote*
850 "{a-zA-Z0-9.%#:-"} Use register {a-zA-Z0-9.%#:-"} for next delete, yank
851 or put (use uppercase character to append with
852 delete and yank) ({.%#:} only work with put).
854 *:reg* *:registers*
855 :reg[isters] Display the contents of all numbered and named
856 registers. {not in Vi}
858 :reg[isters] {arg} Display the contents of the numbered and named
859 registers that are mentioned in {arg}. For example: >
860 :dis 1a
861 < to display registers '1' and 'a'. Spaces are allowed
862 in {arg}. {not in Vi}
864 *:di* *:display*
865 :di[splay] [arg] Same as :registers. {not in Vi}
867 *y* *yank*
868 ["x]y{motion} Yank {motion} text [into register x]. When no
869 characters are to be yanked (e.g., "y0" in column 1),
870 this is an error when 'cpoptions' includes the 'E'
871 flag.
873 *yy*
874 ["x]yy Yank [count] lines [into register x] |linewise|.
876 *Y*
877 ["x]Y yank [count] lines [into register x] (synonym for
878 yy, |linewise|). If you like "Y" to work from the
879 cursor to the end of line (which is more logical,
880 but not Vi-compatible) use ":map Y y$".
882 *v_y*
883 {Visual}["x]y Yank the highlighted text [into register x] (for
884 {Visual} see |Visual-mode|). {not in Vi}
886 *v_Y*
887 {Visual}["x]Y Yank the highlighted lines [into register x] (for
888 {Visual} see |Visual-mode|). {not in Vi}
890 *:y* *:yank*
891 :[range]y[ank] [x] Yank [range] lines [into register x].
893 :[range]y[ank] [x] {count}
894 Yank {count} lines, starting with last line number
895 in [range] (default: current line |cmdline-ranges|),
896 [into register x].
898 *p* *put* *E353*
899 ["x]p Put the text [from register x] after the cursor
900 [count] times. {Vi: no count}
902 *P*
903 ["x]P Put the text [from register x] before the cursor
904 [count] times. {Vi: no count}
906 *<MiddleMouse>*
907 ["x]<MiddleMouse> Put the text from a register before the cursor [count]
908 times. Uses the "* register, unless another is
909 specified.
910 Leaves the cursor at the end of the new text.
911 Using the mouse only works when 'mouse' contains 'n'
912 or 'a'.
913 {not in Vi}
914 If you have a scrollwheel and often accidentally paste
915 text, you can use these mappings to disable the
916 pasting with the middle mouse button: >
917 :map <MiddleMouse> <Nop>
918 :imap <MiddleMouse> <Nop>
919 < You might want to disable the multi-click versions
920 too, see |double-click|.
922 *gp*
923 ["x]gp Just like "p", but leave the cursor just after the new
924 text. {not in Vi}
926 *gP*
927 ["x]gP Just like "P", but leave the cursor just after the new
928 text. {not in Vi}
930 *:pu* *:put*
931 :[line]pu[t] [x] Put the text [from register x] after [line] (default
932 current line). This always works |linewise|, thus
933 this command can be used to put a yanked block as new
934 lines.
935 The cursor is left on the first non-blank in the last
936 new line.
937 The register can also be '=' followed by an optional
938 expression. The expression continues until the end of
939 the command. You need to escape the '|' and '"'
940 characters to prevent them from terminating the
941 command. Example: >
942 :put ='path' . \",/test\"
943 < If there is no expression after '=', Vim uses the
944 previous expression. You can see it with ":dis =".
946 :[line]pu[t]! [x] Put the text [from register x] before [line] (default
947 current line).
949 ["x]]p or *]p* *]<MiddleMouse>*
950 ["x]]<MiddleMouse> Like "p", but adjust the indent to the current line.
951 Using the mouse only works when 'mouse' contains 'n'
952 or 'a'. {not in Vi}
954 ["x][P or *[P*
955 ["x]]P or *]P*
956 ["x][p or *[p* *[<MiddleMouse>*
957 ["x][<MiddleMouse> Like "P", but adjust the indent to the current line.
958 Using the mouse only works when 'mouse' contains 'n'
959 or 'a'. {not in Vi}
961 You can use these commands to copy text from one place to another. Do this
962 by first getting the text into a register with a yank, delete or change
963 command, then inserting the register contents with a put command. You can
964 also use these commands to move text from one file to another, because Vim
965 preserves all registers when changing buffers (the CTRL-^ command is a quick
966 way to toggle between two files).
968 *linewise-register* *characterwise-register*
969 You can repeat the put commands with "." (except for :put) and undo them. If
970 the command that was used to get the text into the register was |linewise|,
971 Vim inserts the text below ("p") or above ("P") the line where the cursor is.
972 Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With
973 the ":put" command, Vim always inserts the text in the next line. You can
974 exchange two characters with the command sequence "xp". You can exchange two
975 lines with the command sequence "ddp". You can exchange two words with the
976 command sequence "deep" (start with the cursor in the blank space before the
977 first word). You can use the "']" or "`]" command after the put command to
978 move the cursor to the end of the inserted text, or use "'[" or "`[" to move
979 the cursor to the start.
981 *put-Visual-mode* *v_p* *v_P*
982 When using a put command like |p| or |P| in Visual mode, Vim will try to
983 replace the selected text with the contents of the register. Whether this
984 works well depends on the type of selection and the type of the text in the
985 register. With blockwise selection it also depends on the size of the block
986 and whether the corners are on an existing character. (Implementation detail:
987 it actually works by first putting the register after the selection and then
988 deleting the selection.)
990 *blockwise-register*
991 If you use a blockwise Visual mode command to get the text into the register,
992 the block of text will be inserted before ("P") or after ("p") the cursor
993 column in the current and next lines. Vim makes the whole block of text start
994 in the same column. Thus the inserted text looks the same as when it was
995 yanked or deleted. Vim may replace some <Tab> characters with spaces to make
996 this happen. However, if the width of the block is not a multiple of a <Tab>
997 width and the text after the inserted block contains <Tab>s, that text may be
998 misaligned.
1000 Note that after a characterwise yank command, Vim leaves the cursor on the
1001 first yanked character that is closest to the start of the buffer. This means
1002 that "yl" doesn't move the cursor, but "yh" moves the cursor one character
1003 left.
1004 Rationale: In Vi the "y" command followed by a backwards motion would
1005 sometimes not move the cursor to the first yanked character,
1006 because redisplaying was skipped. In Vim it always moves to
1007 the first character, as specified by Posix.
1008 With a linewise yank command the cursor is put in the first line, but the
1009 column is unmodified, thus it may not be on the first yanked character.
1011 There are nine types of registers: *registers* *E354*
1012 1. The unnamed register ""
1013 2. 10 numbered registers "0 to "9
1014 3. The small delete register "-
1015 4. 26 named registers "a to "z or "A to "Z
1016 5. four read-only registers ":, "., "% and "#
1017 6. the expression register "=
1018 7. The selection and drop registers "*, "+ and "~
1019 8. The black hole register "_
1020 9. Last search pattern register "/
1022 1. Unnamed register "" *quote_quote* *quotequote*
1023 Vim fills this register with text deleted with the "d", "c", "s", "x" commands
1024 or copied with the yank "y" command, regardless of whether or not a specific
1025 register was used (e.g. "xdd). This is like the unnamed register is pointing
1026 to the last used register. An exception is the '_' register: "_dd does not
1027 store the deleted text in any register.
1028 Vim uses the contents of the unnamed register for any put command (p or P)
1029 which does not specify a register. Additionally you can access it with the
1030 name '"'. This means you have to type two double quotes. Writing to the ""
1031 register writes to register "0.
1032 {Vi: register contents are lost when changing files, no '"'}
1034 2. Numbered registers "0 to "9 *quote_number* *quote0* *quote1*
1035 *quote2* *quote3* *quote4* *quote9*
1036 Vim fills these registers with text from yank and delete commands.
1037 Numbered register 0 contains the text from the most recent yank command,
1038 unless the command specified another register with ["x].
1039 Numbered register 1 contains the text deleted by the most recent delete or
1040 change command, unless the command specified another register or the text is
1041 less than one line (the small delete register is used then). An exception is
1042 made for the delete operator with these movement commands: |%|, |(|, |)|, |`|,
1043 |/|, |?|, |n|, |N|, |{| and |}|. Register "1 is always used then (this is Vi
1044 compatible). The "- register is used as well if the delete is within a line.
1045 With each successive deletion or change, Vim shifts the previous contents
1046 of register 1 into register 2, 2 into 3, and so forth, losing the previous
1047 contents of register 9.
1048 {Vi: numbered register contents are lost when changing files; register 0 does
1049 not exist}
1051 3. Small delete register "- *quote_-* *quote-*
1052 This register contains text from commands that delete less than one line,
1053 except when the command specifies a register with ["x].
1054 {not in Vi}
1056 4. Named registers "a to "z or "A to "Z *quote_alpha* *quotea*
1057 Vim fills these registers only when you say so. Specify them as lowercase
1058 letters to replace their previous contents or as uppercase letters to append
1059 to their previous contents. When the '>' flag is present in 'cpoptions' then
1060 a line break is inserted before the appended text.
1062 5. Read-only registers ":, "., "% and "#
1063 These are '%', '#', ':' and '.'. You can use them only with the "p", "P",
1064 and ":put" commands and with CTRL-R. {not in Vi}
1065 *quote_.* *quote.* *E29*
1066 ". Contains the last inserted text (the same as what is inserted
1067 with the insert mode commands CTRL-A and CTRL-@). Note: this
1068 doesn't work with CTRL-R on the command-line. It works a bit
1069 differently, like inserting the text instead of putting it
1070 ('textwidth' and other options affect what is inserted).
1071 *quote_%* *quote%*
1072 "% Contains the name of the current file.
1073 *quote_#* *quote#*
1074 "# Contains the name of the alternate file.
1075 *quote_:* *quote:* *E30*
1076 ": Contains the most recent executed command-line. Example: Use
1077 "@:" to repeat the previous command-line command.
1078 The command-line is only stored in this register when at least
1079 one character of it was typed. Thus it remains unchanged if
1080 the command was completely from a mapping.
1081 {not available when compiled without the |+cmdline_hist|
1082 feature}
1084 6. Expression register "= *quote_=* *quote=* *@=*
1085 This is not really a register that stores text, but is a way to use an
1086 expression in commands which use a register. The expression register is
1087 read-only; you cannot put text into it. After the '=', the cursor moves to
1088 the command-line, where you can enter any expression (see |expression|). All
1089 normal command-line editing commands are available, including a special
1090 history for expressions. When you end the command-line by typing <CR>, Vim
1091 computes the result of the expression. If you end it with <Esc>, Vim abandons
1092 the expression. If you do not enter an expression, Vim uses the previous
1093 expression (like with the "/" command). The expression must evaluate to a
1094 string. If the result is a number it's turned into a string. A List,
1095 Dictionary or FuncRef results in an error message (use string() to convert).
1096 If the "= register is used for the "p" command, the string is split up at <NL>
1097 characters. If the string ends in a <NL>, it is regarded as a linewise
1098 register. {not in Vi}
1100 7. Selection and drop registers "*, "+ and "~
1101 Use these register for storing and retrieving the selected text for the GUI.
1102 See |quotestar| and |quoteplus|. When the clipboard is not available or not
1103 working, the unnamed register is used instead. For Unix systems the clipboard
1104 is only available when the |+xterm_clipboard| feature is present. {not in Vi}
1106 Note that there is only a distinction between "* and "+ for X11 systems. For
1107 an explanation of the difference, see |x11-selection|. Under MS-Windows, use
1108 of "* and "+ is actually synonymous and refers to the |gui-clipboard|.
1110 *quote_~* *quote~* *<Drop>*
1111 The read-only "~ register stores the dropped text from the last drag'n'drop
1112 operation. When something has been dropped onto Vim, the "~ register is
1113 filled in and the <Drop> pseudo key is sent for notification. You can remap
1114 this key if you want; the default action (for all modes) is to insert the
1115 contents of the "~ register at the cursor position. {not in Vi}
1116 {only available when compiled with the |+dnd| feature, currently only with the
1117 GTK GUI}
1119 Note: The "~ register is only used when dropping plain text onto Vim.
1120 Drag'n'drop of URI lists is handled internally.
1122 8. Black hole register "_ *quote_*
1123 When writing to this register, nothing happens. This can be used to delete
1124 text without affecting the normal registers. When reading from this register,
1125 nothing is returned. {not in Vi}
1127 9. Last search pattern register "/ *quote_/* *quote/*
1128 Contains the most recent search-pattern. This is used for "n" and 'hlsearch'.
1129 It is writable with ":let", you can change it to have 'hlsearch' highlight
1130 other matches without actually searching. You can't yank or delete into this
1131 register. {not in Vi}
1133 *@/*
1134 You can write to a register with a ":let" command |:let-@|. Example: >
1135 :let @/ = "the"
1137 If you use a put command without specifying a register, Vim uses the register
1138 that was last filled (this is also the contents of the unnamed register). If
1139 you are confused, use the ":dis" command to find out what Vim will put (this
1140 command displays all named and numbered registers; the unnamed register is
1141 labelled '"').
1143 The next three commands always work on whole lines.
1145 :[range]co[py] {address} *:co* *:copy*
1146 Copy the lines given by [range] to below the line
1147 given by {address}.
1149 *:t*
1150 :t Synonym for copy.
1152 :[range]m[ove] {address} *:m* *:mo* *:move* *E134*
1153 Move the lines given by [range] to below the line
1154 given by {address}.
1156 ==============================================================================
1157 6. Formatting text *formatting*
1159 :[range]ce[nter] [width] *:ce* *:center*
1160 Center lines in [range] between [width] columns
1161 (default 'textwidth' or 80 when 'textwidth' is 0).
1162 {not in Vi}
1163 Not available when |+ex_extra| feature was disabled at
1164 compile time.
1166 :[range]ri[ght] [width] *:ri* *:right*
1167 Right-align lines in [range] at [width] columns
1168 (default 'textwidth' or 80 when 'textwidth' is 0).
1169 {not in Vi}
1170 Not available when |+ex_extra| feature was disabled at
1171 compile time.
1173 *:le* *:left*
1174 :[range]le[ft] [indent]
1175 Left-align lines in [range]. Sets the indent in the
1176 lines to [indent] (default 0). {not in Vi}
1177 Not available when |+ex_extra| feature was disabled at
1178 compile time.
1180 *gq*
1181 gq{motion} Format the lines that {motion} moves over.
1182 Formatting is done with one of three methods:
1183 1. If 'formatexpr' is not empty the expression is
1184 evaluated. This can differ for each buffer.
1185 2. If 'formatprg' is not empty an external program
1186 is used.
1187 3. Otherwise formatting is done internally.
1189 In the third case the 'textwidth' option controls the
1190 length of each formatted line (see below).
1191 If the 'textwidth' option is 0, the formatted line
1192 length is the screen width (with a maximum width of
1193 79).
1194 The 'formatoptions' option controls the type of
1195 formatting |fo-table|.
1196 The cursor is left on the first non-blank of the last
1197 formatted line.
1198 NOTE: The "Q" command formerly performed this
1199 function. If you still want to use "Q" for
1200 formatting, use this mapping: >
1201 :nnoremap Q gq
1203 gqgq *gqgq* *gqq*
1204 gqq Format the current line. {not in Vi}
1206 *v_gq*
1207 {Visual}gq Format the highlighted text. (for {Visual} see
1208 |Visual-mode|). {not in Vi}
1210 *gw*
1211 gw{motion} Format the lines that {motion} moves over. Similar to
1212 |gq| but puts the cursor back at the same position in
1213 the text. However, 'formatprg' and 'formatexpr' are
1214 not used. {not in Vi}
1216 gwgw *gwgw* *gww*
1217 gww Format the current line as with "gw". {not in Vi}
1219 *v_gw*
1220 {Visual}gw Format the highlighted text as with "gw". (for
1221 {Visual} see |Visual-mode|). {not in Vi}
1223 Example: To format the current paragraph use: *gqap* >
1224 gqap
1226 The "gq" command leaves the cursor in the line where the motion command takes
1227 the cursor. This allows you to repeat formatting repeated with ".". This
1228 works well with "gqj" (format current and next line) and "gq}" (format until
1229 end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on
1230 the first formatted line (as with using a filter command).
1232 If you want to format the current paragraph and continue where you were, use: >
1233 gwap
1234 If you always want to keep paragraphs formatted you may want to add the 'a'
1235 flag to 'formatoptions'. See |auto-format|.
1237 If the 'autoindent' option is on, Vim uses the indent of the first line for
1238 the following lines.
1240 Formatting does not change empty lines (but it does change lines with only
1241 white space!).
1243 The 'joinspaces' option is used when lines are joined together.
1245 You can set the 'formatexpr' option to an expression or the 'formatprg' option
1246 to the name of an external program for Vim to use for text formatting. The
1247 'textwidth' and other options have no effect on formatting by an external
1248 program.
1250 *right-justify*
1251 There is no command in Vim to right justify text. You can do it with
1252 an external command, like "par" (e.g.: "!}par" to format until the end of the
1253 paragraph) or set 'formatprg' to "par".
1255 *format-comments*
1256 Vim can format comments in a special way. Vim recognizes a comment by a
1257 specific string at the start of the line (ignoring white space). Three types
1258 of comments can be used:
1260 - A comment string that repeats at the start of each line. An example is the
1261 type of comment used in shell scripts, starting with "#".
1262 - A comment string that occurs only in the first line, not in the following
1263 lines. An example is this list with dashes.
1264 - Three-piece comments that have a start string, an end string, and optional
1265 lines in between. The strings for the start, middle and end are different.
1266 An example is the C-style comment:
1267 /*
1268 * this is a C comment
1269 */
1271 The 'comments' option is a comma-separated list of parts. Each part defines a
1272 type of comment string. A part consists of:
1273 {flags}:{string}
1275 {string} is the literal text that must appear.
1277 {flags}:
1278 n Nested comment. Nesting with mixed parts is allowed. If 'comments'
1279 is "n:),n:>" a line starting with "> ) >" is a comment.
1281 b Blank (<Space>, <Tab> or <EOL>) required after {string}.
1283 f Only the first line has the comment string. Do not repeat comment on
1284 the next line, but preserve indentation (e.g., a bullet-list).
1286 s Start of three-piece comment
1288 m Middle of a three-piece comment
1290 e End of a three-piece comment
1292 l Left adjust middle with start or end (default). Only recognized when
1293 used together with 's' or 'e'.
1295 r Right adjust middle with start or end. Only recognized when used
1296 together with 's' or 'e'.
1298 O Don't use this one for the "O" command.
1300 x Allows three-piece comments to be ended by just typing the last
1301 character of the end-comment string as the first character on a new
1302 line, when the middle-comment string has already been inserted
1303 automatically. See below for more details.
1305 {digits}
1306 When together with 's' or 'e': add extra indent for the middle part.
1307 This can be used to left-align the middle part with the start or end
1308 and then add an offset.
1310 -{digits}
1311 Like {digits} but reduce the indent. This only works when there is
1312 some indent for the start or end part that can be removed.
1314 When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the
1315 comment string repeats at the start of each line. The flags field may be
1316 empty.
1318 Any blank space in the text before and after the {string} is part of the
1319 {string}, so do not include leading or trailing blanks unless the blanks are a
1320 required part of the comment string.
1322 When one comment leader is part of another, specify the part after the whole.
1323 For example, to include both "-" and "->", use >
1324 :set comments=f:->,f:-
1326 A three-piece comment must always be given as start,middle,end, with no other
1327 parts in between. An example of a three-piece comment is >
1328 sr:/*,mb:*,ex:*/
1329 for C-comments. To avoid recognizing "*ptr" as a comment, the middle string
1330 includes the 'b' flag. For three-piece comments, Vim checks the text after
1331 the start and middle strings for the end string. If Vim finds the end string,
1332 the comment does not continue on the next line. Three-piece comments must
1333 have a middle string because otherwise Vim can't recognize the middle lines.
1335 Notice the use of the "x" flag in the above three-piece comment definition.
1336 When you hit Return in a C-comment, Vim will insert the middle comment leader
1337 for the new line, e.g. " * ". To close this comment you just have to type "/"
1338 before typing anything else on the new line. This will replace the
1339 middle-comment leader with the end-comment leader, leaving just " */". There
1340 is no need to hit BackSpace first.
1342 Examples: >
1343 "b:*" Includes lines starting with "*", but not if the "*" is
1344 followed by a non-blank. This avoids a pointer dereference
1345 like "*str" to be recognized as a comment.
1346 "n:>" Includes a line starting with ">", ">>", ">>>", etc.
1347 "fb:-" Format a list that starts with "- ".
1349 By default, "b:#" is included. This means that a line that starts with
1350 "#include" is not recognized as a comment line. But a line that starts with
1351 "# define" is recognized. This is a compromise.
1353 Often the alignment can be changed from right alignment to a left alignment
1354 with an additional space. For example, for Javadoc comments, this can be
1355 used (insert a backslash before the space when using ":set"): >
1356 s1:/*,mb:*,ex:*/
1357 Note that an offset is included with start, so that the middle part is left
1358 aligned with the start and then an offset of one character added. This makes
1359 it possible to left align the start and middle for this construction: >
1360 /**
1361 * comment
1362 */
1364 {not available when compiled without the |+comments| feature}
1366 *fo-table*
1367 You can use the 'formatoptions' option to influence how Vim formats text.
1368 'formatoptions' is a string that can contain any of the letters below. The
1369 default setting is "tcq". You can separate the option letters with commas for
1370 readability.
1372 letter meaning when present in 'formatoptions' ~
1374 t Auto-wrap text using textwidth
1375 c Auto-wrap comments using textwidth, inserting the current comment
1376 leader automatically.
1377 r Automatically insert the current comment leader after hitting
1378 <Enter> in Insert mode.
1379 o Automatically insert the current comment leader after hitting 'o' or
1380 'O' in Normal mode.
1381 q Allow formatting of comments with "gq".
1382 Note that formatting will not change blank lines or lines containing
1383 only the comment leader. A new paragraph starts after such a line,
1384 or when the comment leader changes.
1385 w Trailing white space indicates a paragraph continues in the next line.
1386 A line that ends in a non-white character ends a paragraph.
1387 a Automatic formatting of paragraphs. Every time text is inserted or
1388 deleted the paragraph will be reformatted. See |auto-format|.
1389 When the 'c' flag is present this only happens for recognized
1390 comments.
1391 n When formatting text, recognize numbered lists. This actually uses
1392 the 'formatlistpat' option, thus any kind of list can be used. The
1393 indent of the text after the number is used for the next line. The
1394 default is to find a number, optionally be followed by '.', ':', ')',
1395 ']' or '}'. Note that 'autoindent' must be set too. Doesn't work
1396 well together with "2".
1397 Example: >
1398 1. the first item
1399 wraps
1400 2. the second item
1401 2 When formatting text, use the indent of the second line of a paragraph
1402 for the rest of the paragraph, instead of the indent of the first
1403 line. This supports paragraphs in which the first line has a
1404 different indent than the rest. Note that 'autoindent' must be set
1405 too. Example: >
1406 first line of a paragraph
1407 second line of the same paragraph
1408 third line.
1409 v Vi-compatible auto-wrapping in insert mode: Only break a line at a
1410 blank that you have entered during the current insert command. (Note:
1411 this is not 100% Vi compatible. Vi has some "unexpected features" or
1412 bugs in this area. It uses the screen column instead of the line
1413 column.)
1414 b Like 'v', but only auto-wrap if you enter a blank at or before
1415 the wrap margin. If the line was longer than 'textwidth' when you
1416 started the insert, or you do not enter a blank in the insert before
1417 reaching 'textwidth', Vim does not perform auto-wrapping.
1418 l Long lines are not broken in insert mode: When a line was longer than
1419 'textwidth' when the insert command started, Vim does not
1420 automatically format it.
1421 m Also break at a multi-byte character above 255. This is useful for
1422 Asian text where every character is a word on its own.
1423 M When joining lines, don't insert a space before or after a multi-byte
1424 character. Overrules the 'B' flag.
1425 B When joining lines, don't insert a space between two multi-byte
1426 characters. Overruled by the 'M' flag.
1427 1 Don't break a line after a one-letter word. It's broken before it
1428 instead (if possible).
1431 With 't' and 'c' you can specify when Vim performs auto-wrapping:
1432 value action ~
1433 "" no automatic formatting (you can use "gq" for manual formatting)
1434 "t" automatic formatting of text, but not comments
1435 "c" automatic formatting for comments, but not text (good for C code)
1436 "tc" automatic formatting for text and comments
1438 Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but
1439 does insert comment leaders according to the 'comments' option). An exception
1440 is when the 'a' flag is present. |auto-format|
1442 Note that when 'paste' is on, Vim does no formatting at all.
1444 Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping;
1445 'textwidth' is still useful for formatting with "gq".
1447 If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some
1448 built in stuff to treat these types of comments a bit more cleverly.
1449 Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in
1450 'formatoptions') gives the correct start of the line automatically. The same
1451 happens with formatting and auto-wrapping. Opening a line after a line
1452 starting with "/*" or "*" and containing "*/", will cause no comment leader to
1453 be inserted, and the indent of the new line is taken from the line containing
1454 the start of the comment.
1455 E.g.:
1456 /* ~
1457 * Your typical comment. ~
1458 */ ~
1459 The indent on this line is the same as the start of the above
1460 comment.
1462 All of this should be really cool, especially in conjunction with the new
1463 :autocmd command to prepare different settings for different types of file.
1465 Some examples:
1466 for C code (only format comments): >
1467 :set fo=croq
1468 < for Mail/news (format all, don't start comment with "o" command): >
1469 :set fo=tcrq
1470 <
1472 Automatic formatting *auto-format*
1474 When the 'a' flag is present in 'formatoptions' text is formatted
1475 automatically when inserting text or deleting text. This works nice for
1476 editing text paragraphs. A few hints on how to use this:
1478 - You need to properly define paragraphs. The simplest is paragraphs that are
1479 separated by a blank line. When there is no separating blank line, consider
1480 using the 'w' flag and adding a space at the end of each line in the
1481 paragraphs except the last one.
1483 - You can set the 'formatoptions' based on the type of file |filetype| or
1484 specifically for one file with a |modeline|.
1486 - Set 'formatoptions' to "aw2tq" to make text with indents like this:
1488 bla bla foobar bla
1489 bla foobar bla foobar bla
1490 bla bla foobar bla
1491 bla foobar bla bla foobar
1493 - Add the 'c' flag to only auto-format comments. Useful in source code.
1495 - Set 'textwidth' to the desired width. If it is zero then 79 is used, or the
1496 width of the screen if this is smaller.
1498 And a few warnings:
1500 - When part of the text is not properly separated in paragraphs, making
1501 changes in this text will cause it to be formatted anyway. Consider doing >
1503 :set fo-=a
1505 - When using the 'w' flag (trailing space means paragraph continues) and
1506 deleting the last line of a paragraph with |dd|, the paragraph will be
1507 joined with the next one.
1509 - Changed text is saved for undo. Formatting is also a change. Thus each
1510 format action saves text for undo. This may consume quite a lot of memory.
1512 - Formatting a long paragraph and/or with complicated indenting may be slow.
1514 ==============================================================================
1515 7. Sorting text *sorting*
1517 Vim has a sorting function and a sorting command. The sorting function can be
1518 found here: |sort()|.
1520 *:sor* *:sort*
1521 :[range]sor[t][!] [i][u][r][n][x][o] [/{pattern}/]
1522 Sort lines in [range]. When no range is given all
1523 lines are sorted.
1525 With [!] the order is reversed.
1527 With [i] case is ignored.
1529 With [n] sorting is done on the first decimal number
1530 in the line (after or inside a {pattern} match).
1532 With [x] sorting is done on the first hexadecimal
1533 number in the line (after or inside a {pattern}
1534 match). A leading "0x" or "0X" is ignored.
1536 With [o] sorting is done on the first octal number in
1537 the line (after or inside a {pattern} match).
1539 With [u] only keep the first of a sequence of
1540 identical lines (ignoring case when [i] is used).
1541 Without this flag, a sequence of identical lines
1542 will be kept in their original order.
1543 Note that leading and trailing white space may cause
1544 lines to be different.
1546 When /{pattern}/ is specified and there is no [r] flag
1547 the text matched with {pattern} is skipped, so that
1548 you sort on what comes after the match.
1549 Instead of the slash any non-letter can be used.
1550 For example, to sort on the second comma-separated
1551 field: >
1552 :sort /[^,]*,/
1553 < To sort on the text at virtual column 10 (thus
1554 ignoring the difference between tabs and spaces): >
1555 :sort /.*\%10v/
1556 < To sort on the first number in the line, no matter
1557 what is in front of it: >
1558 :sort /.*\ze\d/
1560 < With [r] sorting is done on the matching {pattern}
1561 instead of skipping past it as described above.
1562 For example, to sort on only the first three letters
1563 of each line: >
1564 :sort /\a\a\a/ r
1566 < If a {pattern} is used, any lines which don't have a
1567 match for {pattern} are kept in their current order,
1568 but separate from the lines which do match {pattern}.
1569 If you sorted in reverse, they will be in reverse
1570 order after the sorted lines, otherwise they will be
1571 in their original order, right before the sorted
1572 lines.
1574 Note that using ":sort" with ":global" doesn't sort the matching lines, it's
1575 quite useless.
1577 The details about sorting depend on the library function used. There is no
1578 guarantee that sorting is "stable" or obeys the current locale. You will have
1579 to try it out.
1581 The sorting can be interrupted, but if you interrupt it too late in the
1582 process you may end up with duplicated lines. This also depends on the system
1583 library function used.
1585 vim:tw=78:ts=8:ft=help:norl: