blob: 29a2c9f3ee4724477a2e011d7f7c9c088d407344 [file] [log] [blame]
Bram Moolenaare5180522005-12-10 20:19:46 +00001*change.txt* For Vim version 7.0aa. Last change: 2005 Dec 10
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7This file describes commands that delete or change text. In this context,
8changing text means deleting the text and replacing it with other text using
9one command. You can undo all of these commands. You can repeat the non-Ex
10commands with the "." command.
11
121. Deleting text |deleting|
132. Delete and insert |delete-insert|
143. Simple changes |simple-change| *changing*
154. Complex changes |complex-change|
Bram Moolenaar47136d72004-10-12 20:02:24 +000016 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|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000205. Copying and moving text |copy-move|
216. Formatting text |formatting|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +0000227. Sorting text |sorting|
Bram Moolenaar071d4272004-06-13 20:20:40 +000023
24For inserting text see |insert.txt|.
25
26==============================================================================
271. Deleting text *deleting* *E470*
28
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>}
38
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'|.
43
44 *d*
45["x]d{motion} Delete text that {motion} moves over [into register
46 x]. See below for exceptions.
47
48 *dd*
49["x]dd Delete [count] lines [into register x] |linewise|.
50
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|)
Bram Moolenaar4399ef42005-02-12 14:29:27 +000056 When the '#' flag is in 'cpoptions' the count is
57 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +000058
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}
63
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].
67
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}
73
74 *:d* *:de* *:del* *:delete*
75:[range]d[elete] [x] Delete [range] lines (default: current line) [into
76 register x].
77
78:[range]d[elete] [x] {count}
79 Delete {count} lines, starting with [range]
80 (default: current line |cmdline-ranges|) [into
81 register x].
82
83These 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.
86
87An exception for the d{motion} command: If the motion is not linewise, the
88start and end of the motion are not in the same line, and there are only
89blanks before the start and after the end of the motion, the delete becomes
90linewise. This means that the delete also removes the line of blanks that you
91might expect to remain.
92
93Trying to delete an empty region of text (e.g., "d0" in the first column)
94is an error when 'cpoptions' includes the 'E' flag.
95
96 *J*
97J Join [count] lines, with a minimum of two lines.
98 Remove the indent and insert up to two spaces (see
99 below).
100
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}
105
106 *gJ*
107gJ Join [count] lines, with a minimum of two lines.
108 Don't insert or remove any spaces. {not in Vi}
109
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}
114
115 *:j* *:join*
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000116:[range]j[oin][!] [flags]
117 Join [range] lines. Same as "J", except with [!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000118 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: !}
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000123 See |ex-flags| for [flags].
Bram Moolenaar071d4272004-06-13 20:20:40 +0000124
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000125:[range]j[oin][!] {count} [flags]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000126 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: !}
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000131 See |ex-flags| for [flags].
Bram Moolenaar071d4272004-06-13 20:20:40 +0000132
133These commands delete the <EOL> between lines. This has the effect of joining
134multiple lines into one line. You can repeat these commands (except ":j") and
135undo them.
136
137These commands, except "gJ", insert one space in place of the <EOL> unless
138there is trailing white space or the next line starts with a ')'. These
139commands, except "gJ", delete any leading white space on the next line. If
140the 'joinspaces' option is on, these commands insert two spaces after a '.',
141'!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces
142only after a '.').
143The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting
144spaces before and after a multi-byte character |fo-table|.
145
146
147==============================================================================
1482. Delete and insert *delete-insert* *replacing*
149
150 *R*
151R 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.
155
156 *gR*
157gR 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}
164
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.
174
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.
179
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|).
184
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|).
189
190 *S*
191["x]S Delete [count] lines [into register x] and start
192 insert. Synonym for "cc" |linewise|.
193
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}
198
199 *v_r*
200{Visual}["x]r{char} Replace all selected characters by {char}.
201
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}
213
214Notes:
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.
222
223See |registers| for an explanation of registers.
224
225Replace mode is just like Insert mode, except that every character you enter
226deletes one character. If you reach the end of a line, Vim appends any
227further characters (just like Insert mode). In Replace mode, the backspace
228key restores the original text (if there was any). (See section "Insert and
229Replace mode" |mode-ins-repl|).
230
231 *cw* *cW*
232Special case: "cw" and "cW" work the same as "ce" and "cE" if the cursor is
233on a non-blank. This is because Vim interprets "cw" as change-word, and a
234word does not include the following white space. {Vi: "cw" when on a blank
235followed by other blanks changes only the first blank; this is probably a
236bug, because "dw" deletes all the blanks; use the 'w' flag in 'cpoptions' to
237make it work like Vi anyway}
238
239If you prefer "cw" to include the space after a word, use this mapping: >
240 :map cw dwi
241<
242 *:c* *:ch* *:change*
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000243:{range}c[hange][!] Replace lines of text with some different text.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000244 Type a line containing only "." to stop replacing.
245 Without {range}, this command changes only the current
246 line.
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000247 Adding [!] toggles 'autoindent' for the time this
248 command is executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000249
250==============================================================================
2513. Simple changes *simple-change*
252
253 *r*
254r{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.
273
274 *gr*
275gr{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}
282
283 *digraph-arg*
284The argument for Normal mode commands like |r| and |t| is a single character.
285When 'cpo' doesn't contain the 'D' flag, this character can also be entered
286like |digraphs|. First type CTRL-K and then the two digraph characters.
287{not available when compiled without the |+digraphs| feature}
288
289 *case*
290The following commands change the case of letters. The currently active
291|locale| is used. See |:language|. The LC_CTYPE value matters here.
292
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}
298
299~{motion} 'tildeop' option: switch case of {motion} text. {Vi:
300 tilde cannot be used as an operator}
301
302 *g~*
303g~{motion} Switch case of {motion} text. {not in Vi}
304
305g~g~ *g~g~* *g~~*
306g~~ Switch case of current line. {not in Vi}.
307
308 *v_~*
309{Visual}~ Switch case of highlighted text (for {Visual} see
310 |Visual-mode|). {not in Vi}
311
312 *v_U*
313{Visual}U Make highlighted text uppercase (for {Visual} see
314 |Visual-mode|). {not in Vi}
315
316 *gU* *uppercase*
317gU{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.
323
324
325gUgU *gUgU* *gUU*
326gUU Make current line uppercase. {not in Vi}.
327
328 *v_u*
329{Visual}u Make highlighted text lowercase (for {Visual} see
330 |Visual-mode|). {not in Vi}
331
332 *gu* *lowercase*
333gu{motion} Make {motion} text lowercase. {not in Vi}
334
335gugu *gugu* *guu*
336guu Make current line lowercase. {not in Vi}.
337
338 *g?* *rot13*
339g?{motion} Rot13 encode {motion} text. {not in Vi}
340
341 *v_g?*
342{Visual}g? Rot13 encode the highlighted text (for {Visual} see
343 |Visual-mode|). {not in Vi}
344
345g?g? *g?g?* *g??*
346g?? Rot13 encode current line. {not in Vi}.
347
348
349Adding and subtracting ~
350 *CTRL-A*
351CTRL-A Add [count] to the number or alphabetic character at
352 or after the cursor. {not in Vi}
353
354 *CTRL-X*
355CTRL-X Subtract [count] from the number or alphabetic
356 character at or after the cursor. {not in Vi}
357
358The CTRL-A and CTRL-X commands work for (signed) decimal numbers, unsigned
359octal and hexadecimal numbers and alphabetic characters. This depends on the
360'nrformats' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000361- When 'nrformats' includes "octal", Vim considers numbers starting with a '0'
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000362 to be octal, unless the number includes a '8' or '9'. Other numbers are
363 decimal and may have a preceding minus sign.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000364 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.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000366- 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.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000373
374For numbers with leading zeros (including all octal and hexadecimal numbers),
375Vim preserves the number of characters in the number when possible. CTRL-A on
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000376"0077" results in "0100", CTRL-X on "0x100" results in "0x0ff".
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000377There is one exception: When a number that starts with a zero is found not to
378be octal (it contains a '8' or '9'), but 'nrformats' does include "octal",
379leading zeros are removed to avoid that the result may be recognized as an
380octal number.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000381
382Note that when 'nrformats' includes "octal", decimal numbers with leading
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000383zeros cause mistakes, because they can be confused with octal numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000384
385The CTRL-A command is very useful in a macro. Example: Use the following
386steps to make a numbered list.
387
3881. Create the first list entry, make sure it starts with a number.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003892. qa - start recording into register 'a'
Bram Moolenaar071d4272004-06-13 20:20:40 +00003903. Y - yank the entry
3914. p - put a copy of the entry below the first one
3925. CTRL-A - increment the number
3936. q - stop recording
3947. <count>@a - repeat the yank, put and increment <count> times
395
396
397SHIFTING LINES LEFT OR RIGHT *shift-left-right*
398
399 *<*
400<{motion} Shift {motion} lines one 'shiftwidth' leftwards.
401
402 *<<*
403<< Shift [count] lines one 'shiftwidth' leftwards.
404
405 *v_<*
406{Visual}[count]< Shift the highlighted lines [count] 'shiftwidth'
407 leftwards (for {Visual} see |Visual-mode|). {not in
408 Vi}
409
410 *>*
411 >{motion} Shift {motion} lines one 'shiftwidth' rightwards.
412
413 *>>*
414 >> Shift [count] lines one 'shiftwidth' rightwards.
415
416 *v_>*
417{Visual}[count]> Shift the highlighted lines [count] 'shiftwidth'
418 rightwards (for {Visual} see |Visual-mode|). {not in
419 Vi}
420
421 *:<*
422:[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<'
423 for shifting multiple 'shiftwidth's.
424
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.
428
429:[range]le[ft] [indent] left align lines in [range]. Sets the indent in the
430 lines to [indent] (default 0). {not in Vi}
431
432 *:>*
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000433:[range]> [flags] Shift {count} [range] lines one 'shiftwidth' right.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000434 Repeat '>' for shifting multiple 'shiftwidth's.
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000435 See |ex-flags| for [flags].
Bram Moolenaar071d4272004-06-13 20:20:40 +0000436
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000437:[range]> {count} [flags]
438 Shift {count} lines one 'shiftwidth' right, starting
Bram Moolenaar071d4272004-06-13 20:20:40 +0000439 with [range] (default current line |cmdline-ranges|).
440 Repeat '>' for shifting multiple 'shiftwidth's.
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000441 See |ex-flags| for [flags].
Bram Moolenaar071d4272004-06-13 20:20:40 +0000442
443The ">" and "<" commands are handy for changing the indentation within
444programs. Use the 'shiftwidth' option to set the size of the white space
445which these commands insert or delete. Normally the 'shiftwidth' option is 8,
446but you can set it to, say, 3 to make smaller indents. The shift leftwards
447stops when there is no indent. The shift right does not affect empty lines.
448
449If the 'shiftround' option is on, the indent is rounded to a multiple of
450'shiftwidth'.
451
452If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains
453'#', shift right does not affect lines starting with '#' (these are supposed
454to be C preprocessor lines that must stay in column 1).
455
456When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as
457much as possible to make the indent. You can use ">><<" to replace an indent
458made out of spaces with the same indent made out of <Tab>s (and a few spaces
459if necessary). If the 'expandtab' option is on, Vim uses only spaces. Then
460you can use ">><<" to replace <Tab>s in the indent by spaces (or use
461":retab!").
462
463To move a line several 'shiftwidth's, use Visual mode or the ":" commands.
464For 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
469
470==============================================================================
4714. Complex changes *complex-change*
472
Bram Moolenaar47136d72004-10-12 20:02:24 +00004734.1 Filter commands *filter*
474
475A filter is a program that accepts text at standard input, changes it in some
476way, and sends it to standard output. You can use the commands below to send
477some text through a filter, so that it is replace by the filter output.
478Examples of filters are "sort", which sorts lines alphabetically, and
479"indent", which formats C program files (you need a version of indent that
480works like a filter; not all versions do). The 'shell' option specifies the
481shell Vim uses to execute the filter command (See also the 'shelltype'
482option). You can repeat filter commands with ".". Vim does not recognize a
483comment (starting with '"') after the ":!" command.
484
485 *!*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000486!{motion}{filter} Filter {motion} text lines through the external
487 program {filter}.
488
489 *!!*
490!!{filter} Filter [count] lines through the external program
491 {filter}.
492
493 *v_!*
494{Visual}!{filter} Filter the highlighted lines through the external
495 program {filter} (for {Visual} see |Visual-mode|).
496 {not in Vi}
497
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 When the 'R' flag is included in 'cpoptions' marks in
507 the filtered lines are deleted, unless the
508 |:keepmarks| command is used. Example: >
509 :keepmarks '<,'>!sort
510< When the number of lines after filtering is less than
511 before, marks in the missing lines are deleted anyway.
512
513 *=*
514={motion} Filter {motion} lines through the external program
515 given with the 'equalprg' option. When the 'equalprg'
516 option is empty (this is the default), use the
517 internal formatting function |C-indenting|. But when
518 'indentexpr' is not empty, it will be used instead
519 |indent-expression|.
520
521 *==*
522== Filter [count] lines like with ={motion}.
523
524 *v_=*
525{Visual}= Filter the highlighted lines like with ={motion}.
526 {not in Vi}
527
Bram Moolenaar071d4272004-06-13 20:20:40 +0000528
Bram Moolenaar47136d72004-10-12 20:02:24 +00005294.2 Substitute *:substitute*
530 *:s* *:su*
Bram Moolenaar05159a02005-02-26 23:04:13 +0000531:[range]s[ubstitute]/{pattern}/{string}/[flags] [count]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000532 For each line in [range] replace a match of {pattern}
533 with {string}.
534 For the {pattern} see |pattern|.
535 {string} can be a literal string, or something
536 special; see |sub-replace-special|.
537 When [range] and [count] are omitted, replace in the
538 current line only.
539 When [count] is given, replace in [count] lines,
540 starting with the last line in [range]. When [range]
541 is omitted start in the current line.
542 Also see |cmdline-ranges|.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000543 See |:s_flags| for [flags].
Bram Moolenaar071d4272004-06-13 20:20:40 +0000544
Bram Moolenaar05159a02005-02-26 23:04:13 +0000545:[range]s[ubstitute] [flags] [count]
546:[range]&[&][flags] [count] *:&*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000547 Repeat last :substitute with same search pattern and
548 substitute string, but without the same flags. You
Bram Moolenaar05159a02005-02-26 23:04:13 +0000549 may add [flags], see |:s_flags|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000550 Note that after ":substitute" the '&' flag can't be
551 used, it's recognized as a pattern separator.
552 The space between ":substitute" and the 'c', 'g' and
553 'r' flags isn't required, but in scripts it's a good
554 idea to keep it to avoid confusion.
555
Bram Moolenaar05159a02005-02-26 23:04:13 +0000556:[range]~[&][flags] [count] *:~*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000557 Repeat last substitute with same substitute string
558 but with last used search pattern. This is like
Bram Moolenaar05159a02005-02-26 23:04:13 +0000559 ":&r". See |:s_flags| for [flags].
Bram Moolenaar071d4272004-06-13 20:20:40 +0000560
Bram Moolenaar05159a02005-02-26 23:04:13 +0000561 *&*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000562& Synonym for ":s//~/" (repeat last substitute). Note
563 that the flags are not remembered, thus it might
564 actually work differently. You can use ":&&" to keep
565 the flags.
566
Bram Moolenaar05159a02005-02-26 23:04:13 +0000567 *g&*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000568g& Synonym for ":%s//~/&" (repeat last substitute on all
569 lines with the same flags).
570 Mnemonic: global substitute. {not in Vi}
571
572 *:snomagic* *:sno*
573:[range]sno[magic] ... Same as ":substitute", but always use 'nomagic'.
574 {not in Vi}
575
576 *:smagic* *:sm*
577:[range]sm[agic] ... Same as ":substitute", but always use 'magic'.
578 {not in Vi}
579
580 *:s_flags*
581The flags that you can use for the substitute commands:
582
583[&] Must be the first one: Keep the flags from the previous substitute
584 command. Examples: >
585 :&&
586 :s/this/that/&
587< Note that ":s" and ":&" don't keep the flags.
588 {not in Vi}
589
590[c] Confirm each substitution. Vim highlights the matching string (with
591 |hl-IncSearch|). You can type: *:s_c*
592 'y' to substitute this match
593 'l' to substitute this match and then quit ("last")
594 'n' to skip this match
595 <Esc> to quit substituting
596 'a' to substitute this and all remaining matches {not in Vi}
597 'q' to quit substituting {not in Vi}
598 CTRL-E to scroll the screen up {not in Vi, not available when
599 compiled without the +insert_expand feature}
600 CTRL-Y to scroll the screen down {not in Vi, not available when
601 compiled without the +insert_expand feature}
602 If the 'edcompatible' option is on, Vim remembers the [c] flag and
603 toggles it each time you use it, but resets it when you give a new
604 search pattern.
605 {not in Vi: highlighting of the match, other responses than 'y' or 'n'}
606
607[e] When the search pattern fails, do not issue an error message and, in
608 particular, continue in maps as if no error occurred. This is most
609 useful to prevent the "No match" error from breaking a mapping. Vim
610 does not suppress the following error messages, however:
611 Regular expressions can't be delimited by letters
612 \ should be followed by /, ? or &
613 No previous substitute regular expression
614 Trailing characters
615 Interrupted
616 {not in Vi}
617
618[g] Replace all occurrences in the line. Without this argument,
619 replacement occurs only for the first occurrence in each line. If
620 the 'edcompatible' option is on, Vim remembers this flag and toggles
621 it each time you use it, but resets it when you give a new search
622 pattern. If the 'gdefault' option is on, this flag is on by default
623 and the [g] argument switches it off.
624
625[i] Ignore case for the pattern. The 'ignorecase' and 'smartcase' options
626 are not used.
627 {not in Vi}
628
629[I] Don't ignore case for the pattern. The 'ignorecase' and 'smartcase'
630 options are not used.
631 {not in Vi}
632
Bram Moolenaar05159a02005-02-26 23:04:13 +0000633[n] Report the number of matches, do not actually substitute. The [c]
634 flag is ignored. The matches are reported as if 'report' is zero.
635 Useful to |count-items|.
636
Bram Moolenaar071d4272004-06-13 20:20:40 +0000637[p] Print the line containing the last substitute.
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000638
639[#] Like [p] and prepend the line number.
640
641[l] Like [l] but print the text like |:list|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000642
643[r] Only useful in combination with ":&" or ":s" without arguments. ":&r"
644 works the same way as ":~": When the search pattern is empty, use the
645 previously used search pattern instead of the search pattern from the
646 last substitute or ":global". If the last command that did a search
647 was a substitute or ":global", there is no effect. If the last
648 command was a search command such as "/", use the pattern from that
649 command.
650 For ":s" with an argument this already happens: >
651 :s/blue/red/
652 /green
653 :s//red/ or :~ or :&r
654< The last commands will replace "green" with "red". >
655 :s/blue/red/
656 /green
657 :&
658< The last command will replace "blue" with "red".
659 {not in Vi}
660
661Note that there is no flag to change the "magicness" of the pattern. A
662different command is used instead. The reason is that the flags can only be
663found by skipping the pattern, and in order to skip the pattern the
664"magicness" must be known. Catch 22!
665
666If the {pattern} for the substitute command is empty, the command uses the
667pattern from the last substitute or ":global" command. With the [r] flag, the
668command uses the pattern from the last substitute, ":global", or search
669command.
670
671For compatibility with Vi these two exceptions are allowed:
672"\/{string}/" and "\?{string}?" do the same as "//{string}/r".
673"\&{string}&" does the same as "//{string}/".
674 *E146*
675Instead of the '/' which surrounds the pattern and replacement string, you
676can use any other character, but not an alphanumeric character, '\', '"' or
677'|'. This is useful if you want to include a '/' in the search pattern or
678replacement string. Example: >
679 :s+/+//+
680
681For the definition of a pattern, see |pattern|.
682
683 *sub-replace-special* *:s\=*
684When the {string} starts with "\=" it is evaluated as an expression, see
Bram Moolenaar5a8684e2005-07-30 22:43:24 +0000685|sub-replace-expression|. You can use that for any special characters.
686Otherwise these characters in {string} have a special meaning:
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000687 *:s%*
688When {string} is equal to "%" and '/' is included with the 'cpotions' option,
689then the {string} of the previous substitute command is used. |cpo-/|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000690
691magic nomagic action ~
692 & \& replaced with the whole matched pattern *s/\&*
693 \& & replaced with &
694 \0 replaced with the whole matched pattern *\0* *s/\0*
695 \1 replaced with the matched pattern in the first
696 pair of () *s/\1*
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000697 \2 replaced with the matched pattern in the second
Bram Moolenaar071d4272004-06-13 20:20:40 +0000698 pair of () *s/\2*
699 .. .. *s/\3*
700 \9 replaced with the matched pattern in the ninth
701 pair of () *s/\9*
702 ~ \~ replaced with the {string} of the previous
703 substitute *s~*
704 \~ ~ replaced with ~ *s/\~*
705 \u next character made uppercase *s/\u*
706 \U following characters made uppercase, until \E *s/\U*
707 \l next character made lowercase *s/\l*
708 \L following characters made lowercase, until \E *s/\L*
709 \e end of \u, \U, \l and \L (NOTE: not <Esc>!) *s/\e*
710 \E end of \u, \U, \l and \L *s/\E*
711 <CR> split line in two at this point
712 (Type the <CR> as CTRL-V <Enter>) *s<CR>*
713 \r idem *s/\r*
714 \<CR> insert a carriage-return (CTRL-M)
715 (Type the <CR> as CTRL-V <Enter>) *s/\<CR>*
716 \n insert a <NL> (<NUL> in the file)
717 (does NOT break the line) *s/\n*
718 \b insert a <BS> *s/\b*
719 \t insert a <Tab> *s/\t*
720 \\ insert a single backslash *s/\\*
721 \x where x is any character not mentioned above:
722 Reserved for future expansion
723
724Examples: >
725 :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx"
726 :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb"
727 :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines)
728 :s/$/\^M/ modifies "abcde" to "abcde^M"
729
730Note: In previous versions CTRL-V was handled in a special way. Since this is
731not Vi compatible, this was removed. Use a backslash instead.
732
733command text result ~
734:s/aa/a^Ma/ aa a<line-break>a
735:s/aa/a\^Ma/ aa a^Ma
736:s/aa/a\\^Ma/ aa a\<line-break>a
737
738(you need to type CTRL-V <CR> to get a ^M here)
739
740The numbering of "\1", "\2" etc. is done based on which "\(" comes first in
741the pattern (going left to right). When a parentheses group matches several
742times, the last one will be used for "\1", "\2", etc. Example: >
743 :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x"
744
745When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\),
746either the first or second pattern in parentheses did not match, so either
747\1 or \2 is empty. Example: >
748 :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x"
749<
750
751Substitute with an expression *sub-replace-expression*
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000752 *sub-replace-\=*
753When the substitute string starts with "\=" the remainder is interpreted as an
Bram Moolenaar071d4272004-06-13 20:20:40 +0000754expression. This does not work recursively: a substitute() function inside
755the expression cannot use "\=" for the substitute string.
756
757The special meaning for characters as mentioned at |sub-replace-special| does
758not apply except "<CR>", "\<CR>" and "\\". Thus in the result of the
759expression you need to use two backslashes get one, put a backslash before a
760<CR> you want to insert and use a <CR> without a backslash where you want to
761break the line.
762
763For convenience a <NL> character is also used as a line break. Prepend a
764backslash to get a real <NL> character (which will be a NUL in the file).
765
766The whole matched text can be accessed with "submatch(0)". The text matched
767with the first pair of () with "submatch(1)". Likewise for further
768sub-matches in ().
769
770Be careful: The separation character must not appear in the expression!
771Consider using a character like "@" or ":". There is no problem if the result
772of the expression contains the separation character.
773
Bram Moolenaar5a8684e2005-07-30 22:43:24 +0000774Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000775 :s@\n@\="\r" . expand("$HOME") . "\r"@
Bram Moolenaar5a8684e2005-07-30 22:43:24 +0000776This replaces an end-of-line with a new line containing the value of $HOME. >
777
778 s/E/\="\<Char-0x20ac>"/g
779This replaces 'E' characters with an euro sign. Read more in |<Char->|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000780
781
Bram Moolenaar47136d72004-10-12 20:02:24 +00007824.3 Search and replace *search-replace*
783
784 *:pro* *:promptfind*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000785:promptf[ind] [string]
786 Put up a Search dialog. When [string] is given, it is
787 used as the initial search string.
788 {only for Win32, Motif and GTK GUI}
789
790 *:promptr* *:promptrepl*
791:promptr[epl] [string]
792 Put up a Search/Replace dialog. When [string] is
793 given, it is used as the initial search string.
794 {only for Win32, Motif and GTK GUI}
795
Bram Moolenaar47136d72004-10-12 20:02:24 +0000796
7974.4 Changing tabs *change-tabs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000798 *:ret* *:retab*
799:[range]ret[ab][!] [new_tabstop]
800 Replace all sequences of white-space containing a
801 <Tab> with new strings of white-space using the new
802 tabstop value given. If you do not specify a new
803 tabstop size or it is zero, Vim uses the current value
804 of 'tabstop'.
805 The current value of 'tabstop' is always used to
806 compute the width of existing tabs.
807 With !, Vim also replaces strings of only normal
808 spaces with tabs where appropriate.
809 With 'expandtab' on, Vim replaces all tabs with the
810 appropriate number of spaces.
811 This command sets 'tabstop' to the new value given,
812 and if performed on the whole file, which is default,
813 should not make any visible change.
814 Careful: This command modifies any <Tab> characters
815 inside of strings in a C program. Use "\t" to avoid
816 this (that's a good habit anyway).
817 ":retab!" may also change a sequence of spaces by
818 <Tab> characters, which can mess up a printf().
819 {not in Vi}
820 Not available when |+ex_extra| feature was disabled at
821 compile time.
822
823 *retab-example*
824Example for using autocommands and ":retab" to edit a file which is stored
825with tabstops at 8 but edited with tabstops set at 4. Warning: white space
826inside of strings can change! Also see 'softtabstop' option. >
827
828 :auto BufReadPost *.xx retab! 4
829 :auto BufWritePre *.xx retab! 8
830 :auto BufWritePost *.xx retab! 4
831 :auto BufNewFile *.xx set ts=4
832
833==============================================================================
8345. Copying and moving text *copy-move*
835
836 *quote*
837"{a-zA-Z0-9.%#:-"} Use register {a-zA-Z0-9.%#:-"} for next delete, yank
838 or put (use uppercase character to append with
839 delete and yank) ({.%#:} only work with put).
840
841 *:reg* *:registers*
842:reg[isters] Display the contents of all numbered and named
843 registers. {not in Vi}
844
845:reg[isters] {arg} Display the contents of the numbered and named
846 registers that are mentioned in {arg}. For example: >
847 :dis 1a
848< to display registers '1' and 'a'. Spaces are allowed
849 in {arg}. {not in Vi}
850
851 *:di* *:display*
852:di[splay] [arg] Same as :registers. {not in Vi}
853
854 *y* *yank*
855["x]y{motion} Yank {motion} text [into register x]. When no
856 characters are to be yanked (e.g., "y0" in column 1),
857 this is an error when 'cpoptions' includes the 'E'
858 flag.
859
860 *yy*
861["x]yy Yank [count] lines [into register x] |linewise|.
862
863 *Y*
864["x]Y yank [count] lines [into register x] (synonym for
865 yy, |linewise|). If you like "Y" to work from the
866 cursor to the end of line (which is more logical,
867 but not Vi-compatible) use ":map Y y$".
868
869 *v_y*
870{Visual}["x]y Yank the highlighted text [into register x] (for
871 {Visual} see |Visual-mode|). {not in Vi}
872
873 *v_Y*
874{Visual}["x]Y Yank the highlighted lines [into register x] (for
875 {Visual} see |Visual-mode|). {not in Vi}
876
877 *:y* *:yank*
878:[range]y[ank] [x] Yank [range] lines [into register x].
879
880:[range]y[ank] [x] {count}
881 Yank {count} lines, starting with last line number
882 in [range] (default: current line |cmdline-ranges|),
883 [into register x].
884
885 *p* *put* *E353*
886["x]p Put the text [from register x] after the cursor
887 [count] times. {Vi: no count}
888
889 *P*
890["x]P Put the text [from register x] before the cursor
891 [count] times. {Vi: no count}
892
893 *<MiddleMouse>*
894["x]<MiddleMouse> Put the text from a register before the cursor [count]
895 times. Uses the "* register, unless another is
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000896 specified.
897 Leaves the cursor at the end of the new text.
898 Using the mouse only works when 'mouse' contains 'n'
899 or 'a'.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000900 {not in Vi}
901 If you have a scrollwheel and often accidentally paste
902 text, you can use these mappings to disable the
903 pasting with the middle mouse button: >
904 :map <MiddleMouse> <Nop>
905 :imap <MiddleMouse> <Nop>
906< You might want to disable the multi-click versions
907 too, see |double-click|.
908
909 *gp*
910["x]gp Just like "p", but leave the cursor just after the new
911 text. {not in Vi}
912
913 *gP*
914["x]gP Just like "P", but leave the cursor just after the new
915 text. {not in Vi}
916
917 *:pu* *:put*
918:[line]pu[t] [x] Put the text [from register x] after [line] (default
919 current line). This always works |linewise|, thus
920 this command can be used to put a yanked block as new
921 lines.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000922 The cursor is left on the first non-blank in the last
923 new line.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000924 The register can also be '=' followed by an optional
925 expression. The expression continues until the end of
926 the command. You need to escape the '|' and '"'
927 characters to prevent them from terminating the
928 command. Example: >
929 :put ='path' . \",/test\"
930< If there is no expression after '=', Vim uses the
931 previous expression. You can see it with ":dis =".
932
933:[line]pu[t]! [x] Put the text [from register x] before [line] (default
934 current line).
935
936["x]]p or *]p* *]<MiddleMouse>*
937["x]]<MiddleMouse> Like "p", but adjust the indent to the current line.
938 Using the mouse only works when 'mouse' contains 'n'
939 or 'a'. {not in Vi}
940
941["x][P or *[P*
942["x]]P or *]P*
943["x][p or *[p* *[<MiddleMouse>*
944["x][<MiddleMouse> Like "P", but adjust the indent to the current line.
945 Using the mouse only works when 'mouse' contains 'n'
946 or 'a'. {not in Vi}
947
948You can use these commands to copy text from one place to another. Do this
949by first getting the text into a register with a yank, delete or change
950command, then inserting the register contents with a put command. You can
951also use these commands to move text from one file to another, because Vim
952preserves all registers when changing buffers (the CTRL-^ command is a quick
953way to toggle between two files).
954
955 *linewise-register* *characterwise-register*
956You can repeat the put commands with "." (except for :put) and undo them. If
957the command that was used to get the text into the register was |linewise|,
958Vim inserts the text below ("p") or above ("P") the line where the cursor is.
959Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With
960the ":put" command, Vim always inserts the text in the next line. You can
961exchange two characters with the command sequence "xp". You can exchange two
962lines with the command sequence "ddp". You can exchange two words with the
963command sequence "deep" (start with the cursor in the blank space before the
964first word). You can use the "']" or "`]" command after the put command to
965move the cursor to the end of the inserted text, or use "'[" or "`[" to move
966the cursor to the start.
967
968 *put-Visual-mode* *v_p* *v_P*
969When using a put command like |p| or |P| in Visual mode, Vim will try to
970replace the selected text with the contents of the register. Whether this
971works well depends on the type of selection and the type of the text in the
972register. With blockwise selection it also depends on the size of the block
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000973and whether the corners are on an existing character. (Implementation detail:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000974it actually works by first putting the register after the selection and then
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000975deleting the selection.)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000976
977 *blockwise-register*
978If you use a blockwise Visual mode command to get the text into the register,
979the block of text will be inserted before ("P") or after ("p") the cursor
980column in the current and next lines. Vim makes the whole block of text start
981in the same column. Thus the inserted text looks the same as when it was
982yanked or deleted. Vim may replace some <Tab> characters with spaces to make
983this happen. However, if the width of the block is not a multiple of a <Tab>
984width and the text after the inserted block contains <Tab>s, that text may be
985misaligned.
986
987Note that after a characterwise yank command, Vim leaves the cursor on the
988first yanked character that is closest to the start of the buffer. This means
989that "yl" doesn't move the cursor, but "yh" moves the cursor one character
990left.
991Rationale: In Vi the "y" command followed by a backwards motion would
992 sometimes not move the cursor to the first yanked character,
993 because redisplaying was skipped. In Vim it always moves to
994 the first character, as specified by Posix.
995With a linewise yank command the cursor is put in the first line, but the
996column is unmodified, thus it may not be on the first yanked character.
997
998There are nine types of registers: *registers* *E354*
9991. The unnamed register ""
10002. 10 numbered registers "0 to "9
10013. The small delete register "-
10024. 26 named registers "a to "z or "A to "Z
10035. four read-only registers ":, "., "% and "#
10046. the expression register "=
10057. The selection and drop registers "*, "+ and "~
10068. The black hole register "_
10079. Last search pattern register "/
1008
10091. Unnamed register "" *quote_quote* *quotequote*
1010Vim fills this register with text deleted with the "d", "c", "s", "x" commands
1011or copied with the yank "y" command, regardless of whether or not a specific
Bram Moolenaared203462004-06-16 11:19:22 +00001012register was used (e.g. "xdd). This is like the unnamed register is pointing
1013to the last used register. An exception is the '_' register: "_dd does not
Bram Moolenaar81695252004-12-29 20:58:21 +00001014store the deleted text in any register.
1015Vim uses the contents of the unnamed register for any put command (p or P)
1016which does not specify a register. Additionally you can access it with the
1017name '"'. This means you have to type two double quotes. Writing to the ""
1018register writes to register "0.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001019{Vi: register contents are lost when changing files, no '"'}
1020
10212. Numbered registers "0 to "9 *quote_number* *quote0* *quote1*
1022 *quote2* *quote3* *quote4* *quote9*
1023Vim fills these registers with text from yank and delete commands.
1024 Numbered register 0 contains the text from the most recent yank command,
1025unless the command specified another register with ["x].
1026 Numbered register 1 contains the text deleted by the most recent delete or
1027change command, unless the command specified another register or the text is
1028less than one line (the small delete register is used then). An exception is
Bram Moolenaar81695252004-12-29 20:58:21 +00001029made for the delete operator with these movement commands: |%|, |(|, |)|, |`|,
1030|/|, |?|, |n|, |N|, |{| and |}|. Register "1 is always used then (this is Vi
1031compatible). The "- register is used as well if the delete is within a line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001032 With each successive deletion or change, Vim shifts the previous contents
1033of register 1 into register 2, 2 into 3, and so forth, losing the previous
1034contents of register 9.
1035{Vi: numbered register contents are lost when changing files; register 0 does
1036not exist}
1037
10383. Small delete register "- *quote_-* *quote-*
1039This register contains text from commands that delete less than one line,
1040except when the command specifies a register with ["x].
1041{not in Vi}
1042
10434. Named registers "a to "z or "A to "Z *quote_alpha* *quotea*
1044Vim fills these registers only when you say so. Specify them as lowercase
1045letters to replace their previous contents or as uppercase letters to append
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001046to their previous contents. When the '>' flag is present in 'cpoptions' then
1047a line break is inserted before the appended text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001048
10495. Read-only registers ":, "., "% and "#
1050These are '%', '#', ':' and '.'. You can use them only with the "p", "P",
1051and ":put" commands and with CTRL-R. {not in Vi}
1052 *quote_.* *quote.* *E29*
1053 ". Contains the last inserted text (the same as what is inserted
1054 with the insert mode commands CTRL-A and CTRL-@). Note: this
1055 doesn't work with CTRL-R on the command-line. It works a bit
1056 differently, like inserting the text instead of putting it
1057 ('textwidth' and other options affect what is inserted).
1058 *quote_%* *quote%*
1059 "% Contains the name of the current file.
1060 *quote_#* *quote#*
1061 "# Contains the name of the alternate file.
1062 *quote_:* *quote:* *E30*
1063 ": Contains the most recent executed command-line. Example: Use
1064 "@:" to repeat the previous command-line command.
1065 The command-line is only stored in this register when at least
1066 one character of it was typed. Thus it remains unchanged if
1067 the command was completely from a mapping.
1068 {not available when compiled without the |+cmdline_hist|
1069 feature}
1070
10716. Expression register "= *quote_=* *quote=*
1072This is not really a register that stores text, but is a way to use an
1073expression in commands which use a register. The expression register is
1074read-only; you cannot put text into it. After the '=', the cursor moves to
1075the command-line, where you can enter any expression (see |expression|). All
1076normal command-line editing commands are available, including a special
1077history for expressions. When you end the command-line by typing <CR>, Vim
1078computes the result of the expression. If you end it with <Esc>, Vim abandons
1079the expression. If you do not enter an expression, Vim uses the previous
Bram Moolenaar6bab4d12005-06-16 21:53:56 +00001080expression (like with the "/" command). The expression must evaluate to a
1081string. If the result is a number it's turned into a string. A List,
1082Dictionary or FuncRef results in an error message (use string() to convert).
1083If the "= register is used for the "p" command, the string is split up at <NL>
1084characters. If the string ends in a <NL>, it is regarded as a linewise
1085register. {not in Vi}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001086
10877. Selection and drop registers "*, "+ and "~
1088Use these register for storing and retrieving the selected text for the GUI.
1089See |quotestar| and |quoteplus|. When the clipboard is not available or not
Bram Moolenaarf4d11452005-12-02 00:46:37 +00001090working, the unnamed register is used instead. For Unix systems the clipboard
1091is only available when the |+xterm_clipboard| feature is present. {not in Vi}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001092
1093Note that there is only a distinction between "* and "+ for X11 systems. For
1094an explanation of the difference, see |x11-selection|. Under MS-Windows, use
1095of "* and "+ is actually synonymous and refers to the |gui-clipboard|.
1096
1097 *quote_~* *quote~* *<Drop>*
1098The read-only "~ register stores the dropped text from the last drag'n'drop
1099operation. When something has been dropped onto Vim, the "~ register is
1100filled in and the <Drop> pseudo key is sent for notification. You can remap
1101this key if you want; the default action (for all modes) is to insert the
1102contents of the "~ register at the cursor position. {not in Vi}
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001103{only available when compiled with the |+dnd| feature, currently only with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001104GTK GUI}
1105
1106Note: The "~ register is only used when dropping plain text onto Vim.
1107Drag'n'drop of URI lists is handled internally.
1108
11098. Black hole register "_ *quote_*
1110When writing to this register, nothing happens. This can be used to delete
1111text without affecting the normal registers. When reading from this register,
1112nothing is returned. {not in Vi}
1113
11149. Last search pattern register "/ *quote_/* *quote/*
1115Contains the most recent search-pattern. This is used for "n" and 'hlsearch'.
1116It is writable with ":let", you can change it to have 'hlsearch' highlight
1117other matches without actually searching. You can't yank or delete into this
1118register. {not in Vi}
1119
1120 *@/*
1121You can write to a register with a ":let" command |:let-@|. Example: >
1122 :let @/ = "the"
1123
1124If you use a put command without specifying a register, Vim uses the register
1125that was last filled (this is also the contents of the unnamed register). If
1126you are confused, use the ":dis" command to find out what Vim will put (this
1127command displays all named and numbered registers; the unnamed register is
1128labelled '"').
1129
1130The next three commands always work on whole lines.
1131
1132:[range]co[py] {address} *:co* *:copy*
1133 Copy the lines given by [range] to below the line
1134 given by {address}.
1135
1136 *:t*
1137:t Synonym for copy.
1138
1139:[range]m[ove] {address} *:m* *:mo* *:move* *E134*
1140 Move the lines given by [range] to below the line
1141 given by {address}.
1142
1143==============================================================================
11446. Formatting text *formatting*
1145
1146:[range]ce[nter] [width] *:ce* *:center*
1147 Center lines in [range] between [width] columns
1148 (default 'textwidth' or 80 when 'textwidth' is 0).
1149 {not in Vi}
1150 Not available when |+ex_extra| feature was disabled at
1151 compile time.
1152
1153:[range]ri[ght] [width] *:ri* *:right*
1154 Right-align lines in [range] at [width] columns
1155 (default 'textwidth' or 80 when 'textwidth' is 0).
1156 {not in Vi}
1157 Not available when |+ex_extra| feature was disabled at
1158 compile time.
1159
1160 *:le* *:left*
1161:[range]le[ft] [indent]
1162 Left-align lines in [range]. Sets the indent in the
1163 lines to [indent] (default 0). {not in Vi}
1164 Not available when |+ex_extra| feature was disabled at
1165 compile time.
1166
1167 *gq*
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00001168gq{motion} Format the lines that {motion} moves over.
1169 If 'formatprg' is empty formatting is done internally
1170 and the 'textwidth' option controls the length of each
1171 formatted line (see below).
1172 If the 'textwidth' option is 0, the formatted line
1173 length is the screen width (with a maximum width of
1174 79). {not in Vi}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001175 The 'formatoptions' option controls the type of
1176 formatting |fo-table|.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00001177 The cursor is left on the first non-blank of the last
1178 formatted line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001179 NOTE: The "Q" command formerly performed this
1180 function. If you still want to use "Q" for
1181 formatting, use this mapping: >
1182 :nnoremap Q gq
1183
1184gqgq *gqgq* *gqq*
1185gqq Format the current line. {not in Vi}
1186
1187 *v_gq*
1188{Visual}gq Format the highlighted text. (for {Visual} see
1189 |Visual-mode|). {not in Vi}
1190
1191 *gw*
1192gw{motion} Format the lines that {motion} moves over. Similar to
1193 |gq| but puts the cursor back at the same position in
1194 the text. However, 'formatprg' is not used.
1195 {not in Vi}
1196
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001197gwgw *gwgw* *gww*
1198gww Format the current line as with "gw". {not in Vi}
1199
1200 *v_gw*
1201{Visual}gw Format the highlighted text as with "gw". (for
1202 {Visual} see |Visual-mode|). {not in Vi}
1203
Bram Moolenaar071d4272004-06-13 20:20:40 +00001204Example: To format the current paragraph use: *gqap* >
1205 gqap
1206
1207The "gq" command leaves the cursor in the line where the motion command takes
1208the cursor. This allows you to repeat formatting repeated with ".". This
1209works well with "gqj" (format current and next line) and "gq}" (format until
1210end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on
1211the first formatted line (as with using a filter command).
1212
1213If you want to format the current paragraph and continue where you were, use: >
1214 gwap
1215If you always want to keep paragraphs formatted you may want to add the 'a'
1216flag to 'formatoptions'. See |auto-format|.
1217
1218If the 'autoindent' option is on, Vim uses the indent of the first line for
1219the following lines.
1220
1221Formatting does not change empty lines (but it does change lines with only
1222white space!).
1223
1224The 'joinspaces' option is used when lines are joined together.
1225
1226You can set the 'formatprg' option to the name of an external program for Vim
1227to use for text formatting. The 'textwidth' and other options have no effect
1228on formatting by an external program.
1229
1230 *right-justify*
1231There is no command in Vim to right justify text. You can do it with
1232an external command, like "par" (e.g.: "!}par" to format until the end of the
1233paragraph) or set 'formatprg' to "par".
1234
1235 *format-comments*
1236Vim can format comments in a special way. Vim recognizes a comment by a
1237specific string at the start of the line (ignoring white space). Three types
1238of comments can be used:
1239
1240- A comment string that repeats at the start of each line. An example is the
1241 type of comment used in shell scripts, starting with "#".
1242- A comment string that occurs only in the first line, not in the following
1243 lines. An example is this list with dashes.
1244- Three-piece comments that have a start string, an end string, and optional
1245 lines in between. The strings for the start, middle and end are different.
1246 An example is the C-style comment:
1247 /*
1248 * this is a C comment
1249 */
1250
1251The 'comments' option is a comma-separated list of parts. Each part defines a
1252type of comment string. A part consists of:
1253 {flags}:{string}
1254
1255{string} is the literal text that must appear.
1256
1257{flags}:
1258 n Nested comment. Nesting with mixed parts is allowed. If 'comments'
1259 is "n:),n:>" a line starting with "> ) >" is a comment.
1260
1261 b Blank (<Space>, <Tab> or <EOL>) required after {string}.
1262
1263 f Only the first line has the comment string. Do not repeat comment on
1264 the next line, but preserve indentation (e.g., a bullet-list).
1265
1266 s Start of three-piece comment
1267
1268 m Middle of a three-piece comment
1269
1270 e End of a three-piece comment
1271
1272 l Left adjust middle with start or end (default). Only recognized when
1273 used together with 's' or 'e'.
1274
1275 r Right adjust middle with start or end. Only recognized when used
1276 together with 's' or 'e'.
1277
1278 O Don't use this one for the "O" command.
1279
1280 x Allows three-piece comments to be ended by just typing the last
1281 character of the end-comment string as the first character on a new
1282 line, when the middle-comment string has already been inserted
1283 automatically. See below for more details.
1284
1285 {digits}
1286 When together with 's' or 'e': add extra indent for the middle part.
1287 This can be used to left-align the middle part with the start or end
1288 and then add an offset.
1289
1290 -{digits}
1291 Like {digits} but reduce the indent. This only works when there is
1292 some indent for the start or end part that can be removed.
1293
1294When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the
1295comment string repeats at the start of each line. The flags field may be
1296empty.
1297
1298Any blank space in the text before and after the {string} is part of the
1299{string}, so do not include leading or trailing blanks unless the blanks are a
1300required part of the comment string.
1301
1302When one comment leader is part of another, specify the part after the whole.
1303For example, to include both "-" and "->", use >
1304 :set comments=f:->,f:-
1305
1306A three-piece comment must always be given as start,middle,end, with no other
1307parts in between. An example of a three-piece comment is >
1308 sr:/*,mb:*,ex:*/
1309for C-comments. To avoid recognizing "*ptr" as a comment, the middle string
1310includes the 'b' flag. For three-piece comments, Vim checks the text after
1311the start and middle strings for the end string. If Vim finds the end string,
1312the comment does not continue on the next line. Three-piece comments must
1313have a middle string because otherwise Vim can't recognize the middle lines.
1314
1315Notice the use of the "x" flag in the above three-piece comment definition.
1316When you hit Return in a C-comment, Vim will insert the middle comment leader
1317for the new line, e.g. " * ". To close this comment you just have to type "/"
1318before typing anything else on the new line. This will replace the
1319middle-comment leader with the end-comment leader, leaving just " */". There
1320is no need to hit BackSpace first.
1321
1322Examples: >
1323 "b:*" Includes lines starting with "*", but not if the "*" is
1324 followed by a non-blank. This avoids a pointer dereference
1325 like "*str" to be recognized as a comment.
1326 "n:>" Includes a line starting with ">", ">>", ">>>", etc.
1327 "fb:-" Format a list that starts with "- ".
1328
1329By default, "b:#" is included. This means that a line that starts with
1330"#include" is not recognized as a comment line. But a line that starts with
1331"# define" is recognized. This is a compromise.
1332
1333Often the alignment can be changed from right alignment to a left alignment
1334with an additional space. For example, for Javadoc comments, this can be
1335used (insert a backslash before the space when using ":set"): >
1336 s1:/*,mb:*,ex:*/
1337Note that an offset is included with start, so that the middle part is left
1338aligned with the start and then an offset of one character added. This makes
1339it possible to left align the start and middle for this construction: >
1340 /**
1341 * comment
1342 */
1343
1344{not available when compiled without the |+comments| feature}
1345
1346 *fo-table*
1347You can use the 'formatoptions' option to influence how Vim formats text.
1348'formatoptions' is a string that can contain any of the letters below. The
1349default setting is "tcq". You can separate the option letters with commas for
1350readability.
1351
1352letter meaning when present in 'formatoptions' ~
1353
1354t Auto-wrap text using textwidth (does not apply to comments)
1355c Auto-wrap comments using textwidth, inserting the current comment
1356 leader automatically.
1357r Automatically insert the current comment leader after hitting
1358 <Enter> in Insert mode.
1359o Automatically insert the current comment leader after hitting 'o' or
1360 'O' in Normal mode.
1361q Allow formatting of comments with "gq".
1362 Note that formatting will not change blank lines or lines containing
1363 only the comment leader. A new paragraph starts after such a line,
1364 or when the comment leader changes.
1365w Trailing white space indicates a paragraph continues in the next line.
1366 A line that ends in a non-white character ends a paragraph.
1367a Automatic formatting of paragraphs. Every time text is inserted or
1368 deleted the paragraph will be reformatted. See |auto-format|.
1369 When the 'c' flag is present this only happens for recognized
1370 comments.
Bram Moolenaar86b68352004-12-27 21:59:20 +00001371n When formatting text, recognize numbered lists. This actually uses
1372 the 'formatlistpat' option, thus any kind of list can be used. The
1373 indent of the text after the number is used for the next line. The
1374 default is to find a number, optionally be followed by '.', ':', ')',
1375 ']' or '}'. Note that 'autoindent' must be set too. Doesn't work
1376 well together with "2".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001377 Example: >
1378 1. the first item
1379 wraps
1380 2. the second item
13812 When formatting text, use the indent of the second line of a paragraph
1382 for the rest of the paragraph, instead of the indent of the first
1383 line. This supports paragraphs in which the first line has a
1384 different indent than the rest. Note that 'autoindent' must be set
1385 too. Example: >
1386 first line of a paragraph
1387 second line of the same paragraph
1388 third line.
1389v Vi-compatible auto-wrapping in insert mode: Only break a line at a
1390 blank that you have entered during the current insert command. (Note:
1391 this is not 100% Vi compatible. Vi has some "unexpected features" or
1392 bugs in this area. It uses the screen column instead of the line
1393 column.)
1394b Like 'v', but only auto-wrap if you enter a blank at or before
1395 the wrap margin. If the line was longer than 'textwidth' when you
1396 started the insert, or you do not enter a blank in the insert before
1397 reaching 'textwidth', Vim does not perform auto-wrapping.
1398l Long lines are not broken in insert mode: When a line was longer than
1399 'textwidth' when the insert command started, Vim does not
1400 automatically format it.
1401m Also break at a multi-byte character above 255. This is useful for
1402 Asian text where every character is a word on its own.
1403M When joining lines, don't insert a space before or after a multi-byte
1404 character. Overrules the 'B' flag.
1405B When joining lines, don't insert a space between two multi-byte
1406 characters. Overruled by the 'M' flag.
14071 Don't break a line after a one-letter word. It's broken before it
1408 instead (if possible).
1409
1410
1411With 't' and 'c' you can specify when Vim performs auto-wrapping:
1412value action ~
1413"" no automatic formatting (you can use "gq" for manual formatting)
1414"t" automatic formatting of text, but not comments
1415"c" automatic formatting for comments, but not text (good for C code)
1416"tc" automatic formatting for text and comments
1417
1418Note that when 'textwidth' is 0, Vim does no formatting anyway (but does
1419insert comment leaders according to the 'comments' option).
1420
1421Note that when 'paste' is on, Vim does no formatting at all.
1422
1423Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping;
1424'textwidth' is still useful for formatting with "gq".
1425
1426If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some
1427built in stuff to treat these types of comments a bit more cleverly.
1428Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in
1429'formatoptions') gives the correct start of the line automatically. The same
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001430happens with formatting and auto-wrapping. Opening a line after a line
Bram Moolenaar071d4272004-06-13 20:20:40 +00001431starting with "/*" or "*" and containing "*/", will cause no comment leader to
1432be inserted, and the indent of the new line is taken from the line containing
1433the start of the comment.
1434E.g.:
1435 /* ~
1436 * Your typical comment. ~
1437 */ ~
1438 The indent on this line is the same as the start of the above
1439 comment.
1440
1441All of this should be really cool, especially in conjunction with the new
1442:autocmd command to prepare different settings for different types of file.
1443
1444Some examples:
1445 for C code (only format comments): >
1446 :set fo=croq
1447< for Mail/news (format all, don't start comment with "o" command): >
1448 :set fo=tcrq
1449<
1450
1451Automatic formatting *auto-format*
1452
1453When the 'a' flag is present in 'formatoptions' text is formatted
1454automatically when inserting text or deleting text. This works nice for
1455editing text paragraphs. A few hints on how to use this:
1456
1457- You need to properly define paragraphs. The simplest is paragraphs that are
1458 separated by a blank line. When there is no separating blank line, consider
1459 using the 'w' flag and adding a space at the end of each line in the
1460 paragraphs except the last one.
1461
1462- You can set the 'formatoptions' based on the type of file |filetype| or
1463 specifically for one file with a |modeline|.
1464
1465- Set 'formatoptions' to "aw2tq" to make text with indents like this:
1466
1467 bla bla foobar bla
1468 bla foobar bla foobar bla
1469 bla bla foobar bla
1470 bla foobar bla bla foobar
1471
1472- Add the 'c' flag to only auto-format comments. Useful in source code.
1473
1474And a few warnings:
1475
1476- When part of the text is not properly separated in paragraphs, making
1477 changes in this text will cause it to be formatted anyway. Consider doing >
1478
1479 :set fo-=a
1480
1481- When using the 'w' flag (trailing space means paragraph continues) and
1482 deleting the last line of a paragraph with |dd|, the paragraph will be
1483 joined with the next one.
1484
1485- Changed text is saved for undo. Formatting is also a change. Thus each
1486 format action saves text for undo. This may consume quite a lot of memory.
1487
1488- Formatting a long paragraph and/or with complicated indenting may be slow.
1489
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001490==============================================================================
14917. Sorting text *sorting*
1492
1493Vim has a sorting function and a sorting command. The sorting function can be
1494found here: |sort()|.
1495
1496 *:sor* *:sort*
Bram Moolenaare5180522005-12-10 20:19:46 +00001497:[range]sor[t][!] [i][u][n][x][o] [/{pattern}/]
1498 Sort lines in [range]. When no range is given all
1499 lines are sorted.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001500
1501 With [!] the order is reversed.
1502
1503 With [i] case is ignored.
1504
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00001505 With [n] sorting is done on the first decimal number
1506 in the line (after a {pattern} match).
1507
1508 With [x] sorting is done on the first hexadecimal
1509 number in the line (after a {pattern} match). A
1510 leading "0x" or "0X" is ignored.
1511
1512 With [o] sorting is done on the first octal number in
1513 the line (after a {pattern} match).
1514
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001515 With [u] only keep the first of a sequence of
1516 identical lines (ignoring case when [i] is used).
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00001517 Note that leading and trailing white space may cause
1518 lines to be different.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001519
1520 When /{pattern}/ is specified the text matched with
1521 {pattern} is skipped, so that you sort on what comes
1522 after the match. For lines without a match sorting
1523 starts in the first column (e.g., for empty lines).
1524 Instead of the slash any non-letter can be used.
1525 For example, to sort on the second comma-separated
1526 field: >
1527 :sort /[^,]*,/
1528< To sort on the text at virtual column 10 (thus
1529 ignoring the difference between tabs and spaces): >
1530 :sort /.*\%10v/
1531<
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00001532Note that using ":sort" with ":global" doesn't sort the matching lines, it's
1533quite useless.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001534
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00001535The details about sorting depend on the library function used. There is no
1536guarantee that sorting is "stable" or obeys the current locale. You will have
1537to try it out.
1538
Bram Moolenaarae5bce12005-08-15 21:41:48 +00001539The sorting itself cannot be interrupted, because of using a system library
1540function. You can interrupt the preparation (for undo) and putting the sorted
1541lines into the buffer. In the last case you may end up with duplicated lines.
1542
Bram Moolenaar071d4272004-06-13 20:20:40 +00001543 vim:tw=78:ts=8:ft=help:norl: