Merge branch 'vim-with-runtime' into feat/quickfix-title
[vim_extended.git] / runtime / doc / change.txt
blob99ad77652c5cb085a8ebf2bcec520ae0efdbcaf6
1 *change.txt*    For Vim version 7.2.  Last change: 2010 Mar 23
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: When the cursor is in a word, "cw" and "cW" do not include the
233 white space after a word, they only change up to the end of the word.  This is
234 because Vim interprets "cw" as change-word, and a word does not include the
235 following white space.
236 {Vi: "cw" when on a blank followed by other blanks changes only the first
237 blank; this is probably a bug, because "dw" deletes all the blanks; use the
238 'w' flag in 'cpoptions' to make it work like Vi anyway}
240 If you prefer "cw" to include the space after a word, use this mapping: >
241         :map cw dwi
242 Or use "caw" (see |aw|).
244                                                         *:c* *:ch* *:change*
245 :{range}c[hange][!]     Replace lines of text with some different text.
246                         Type a line containing only "." to stop replacing.
247                         Without {range}, this command changes only the current
248                         line.
249                         Adding [!] toggles 'autoindent' for the time this
250                         command is executed.
252 ==============================================================================
253 3. Simple changes                                       *simple-change*
255                                                         *r*
256 r{char}                 Replace the character under the cursor with {char}.
257                         If {char} is a <CR> or <NL>, a line break replaces the
258                         character.  To replace with a real <CR>, use CTRL-V
259                         <CR>.  CTRL-V <NL> replaces with a <Nul>.
260                         {Vi: CTRL-V <CR> still replaces with a line break,
261                         cannot replace something with a <CR>}
262                         If you give a [count], Vim replaces [count] characters
263                         with [count] {char}s.  When {char} is a <CR> or <NL>,
264                         however, Vim inserts only one <CR>: "5r<CR>" replaces
265                         five characters with a single line break.
266                         When {char} is a <CR> or <NL>, Vim performs
267                         autoindenting.  This works just like deleting the
268                         characters that are replaced and then doing
269                         "i<CR><Esc>".
270                         {char} can be entered as a digraph |digraph-arg|.
271                         |:lmap| mappings apply to {char}.  The CTRL-^ command
272                         in Insert mode can be used to switch this on/off
273                         |i_CTRL-^|.  See |utf-8-char-arg| about using
274                         composing characters when 'encoding' is Unicode.
276                                                         *gr*
277 gr{char}                Replace the virtual characters under the cursor with
278                         {char}.  This replaces in screen space, not file
279                         space.  See |gR| and |Virtual-Replace-mode| for more
280                         details.  As with |r| a count may be given.
281                         {char} can be entered like with |r|.
282                         {not available when compiled without the +vreplace
283                         feature}
285                                                 *digraph-arg*
286 The argument for Normal mode commands like |r| and |t| is a single character.
287 When 'cpo' doesn't contain the 'D' flag, this character can also be entered
288 like |digraphs|.  First type CTRL-K and then the two digraph characters.
289 {not available when compiled without the |+digraphs| feature}
291                                                 *case*
292 The following commands change the case of letters.  The currently active
293 |locale| is used.  See |:language|.  The LC_CTYPE value matters here.
295                                                         *~*
296 ~                       'notildeop' option: Switch case of the character
297                         under the cursor and move the cursor to the right.
298                         If a [count] is given, do that many characters. {Vi:
299                         no count}
301 ~{motion}               'tildeop' option: switch case of {motion} text. {Vi:
302                         tilde cannot be used as an operator}
304                                                         *g~*
305 g~{motion}              Switch case of {motion} text. {not in Vi}
307 g~g~                                                    *g~g~* *g~~*
308 g~~                     Switch case of current line. {not in Vi}.
310                                                         *v_~*
311 {Visual}~               Switch case of highlighted text (for {Visual} see
312                         |Visual-mode|). {not in Vi}
314                                                         *v_U*
315 {Visual}U               Make highlighted text uppercase (for {Visual} see
316                         |Visual-mode|). {not in Vi}
318                                                         *gU* *uppercase*
319 gU{motion}              Make {motion} text uppercase. {not in Vi}
320                         Example: >
321                                 :map! <C-F> <Esc>gUiw`]a
322 <                       This works in Insert mode: press CTRL-F to make the
323                         word before the cursor uppercase.  Handy to type
324                         words in lowercase and then make them uppercase.
327 gUgU                                                    *gUgU* *gUU*
328 gUU                     Make current line uppercase. {not in Vi}.
330                                                         *v_u*
331 {Visual}u               Make highlighted text lowercase (for {Visual} see
332                         |Visual-mode|).  {not in Vi}
334                                                         *gu* *lowercase*
335 gu{motion}              Make {motion} text lowercase. {not in Vi}
337 gugu                                                    *gugu* *guu*
338 guu                     Make current line lowercase. {not in Vi}.
340                                                         *g?* *rot13*
341 g?{motion}              Rot13 encode {motion} text. {not in Vi}
343                                                         *v_g?*
344 {Visual}g?              Rot13 encode the highlighted text (for {Visual} see
345                         |Visual-mode|).  {not in Vi}
347 g?g?                                                    *g?g?* *g??*
348 g??                     Rot13 encode current line. {not in Vi}.
350 To turn one line into title caps, make every first letter of a word
351 uppercase: >
352         :s/\v<(.)(\w*)/\u\1\L\2/g
355 Adding and subtracting ~
356                                                         *CTRL-A*
357 CTRL-A                  Add [count] to the number or alphabetic character at
358                         or after the cursor.  {not in Vi}
360                                                         *CTRL-X*
361 CTRL-X                  Subtract [count] from the number or alphabetic
362                         character at or after the cursor.  {not in Vi}
364 The CTRL-A and CTRL-X commands work for (signed) decimal numbers, unsigned
365 octal and hexadecimal numbers and alphabetic characters.  This depends on the
366 'nrformats' option.
367 - When 'nrformats' includes "octal", Vim considers numbers starting with a '0'
368   to be octal, unless the number includes a '8' or '9'.  Other numbers are
369   decimal and may have a preceding minus sign.
370   If the cursor is on a number, the commands apply to that number; otherwise
371   Vim uses the number to the right of the cursor.
372 - When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or
373   '0X' are hexadecimal.  The case of the rightmost letter in the number
374   determines the case of the resulting hexadecimal number.  If there is no
375   letter in the current number, Vim uses the previously detected case.
376 - When 'nrformats' includes "alpha", Vim will change the alphabetic character
377   under or after the cursor.  This is useful to make lists with an alphabetic
378   index.
380 For numbers with leading zeros (including all octal and hexadecimal numbers),
381 Vim preserves the number of characters in the number when possible.  CTRL-A on
382 "0077" results in "0100", CTRL-X on "0x100" results in "0x0ff".
383 There is one exception: When a number that starts with a zero is found not to
384 be octal (it contains a '8' or '9'), but 'nrformats' does include "octal",
385 leading zeros are removed to avoid that the result may be recognized as an
386 octal number.
388 Note that when 'nrformats' includes "octal", decimal numbers with leading
389 zeros cause mistakes, because they can be confused with octal numbers.
391 The CTRL-A command is very useful in a macro.  Example: Use the following
392 steps to make a numbered list.
394 1. Create the first list entry, make sure it starts with a number.
395 2. qa        - start recording into register 'a'
396 3. Y         - yank the entry
397 4. p         - put a copy of the entry below the first one
398 5. CTRL-A    - increment the number
399 6. q         - stop recording
400 7. <count>@a - repeat the yank, put and increment <count> times
403 SHIFTING LINES LEFT OR RIGHT                            *shift-left-right*
405                                                         *<*
406 <{motion}               Shift {motion} lines one 'shiftwidth' leftwards.
408                                                         *<<*
409 <<                      Shift [count] lines one 'shiftwidth' leftwards.
411                                                         *v_<*
412 {Visual}[count]<        Shift the highlighted lines [count] 'shiftwidth'
413                         leftwards (for {Visual} see |Visual-mode|).  {not in
414                         Vi}
416                                                         *>*
417  >{motion}              Shift {motion} lines one 'shiftwidth' rightwards.
419                                                         *>>*
420  >>                     Shift [count] lines one 'shiftwidth' rightwards.
422                                                         *v_>*
423 {Visual}[count]>        Shift the highlighted lines [count] 'shiftwidth'
424                         rightwards (for {Visual} see |Visual-mode|).  {not in
425                         Vi}
427                                                         *:<*
428 :[range]<               Shift [range] lines one 'shiftwidth' left.  Repeat '<'
429                         for shifting multiple 'shiftwidth's.
431 :[range]< {count}       Shift {count} lines one 'shiftwidth' left, starting
432                         with [range] (default current line |cmdline-ranges|).
433                         Repeat '<' for shifting multiple 'shiftwidth's.
435 :[range]le[ft] [indent] left align lines in [range].  Sets the indent in the
436                         lines to [indent] (default 0).  {not in Vi}
438                                                         *:>*
439 :[range]> [flags]       Shift {count} [range] lines one 'shiftwidth' right.
440                         Repeat '>' for shifting multiple 'shiftwidth's.
441                         See |ex-flags| for [flags].
443 :[range]> {count} [flags]
444                         Shift {count} lines one 'shiftwidth' right, starting
445                         with [range] (default current line |cmdline-ranges|).
446                         Repeat '>' for shifting multiple 'shiftwidth's.
447                         See |ex-flags| for [flags].
449 The ">" and "<" commands are handy for changing the indentation within
450 programs.  Use the 'shiftwidth' option to set the size of the white space
451 which these commands insert or delete.  Normally the 'shiftwidth' option is 8,
452 but you can set it to, say, 3 to make smaller indents.  The shift leftwards
453 stops when there is no indent.  The shift right does not affect empty lines.
455 If the 'shiftround' option is on, the indent is rounded to a multiple of
456 'shiftwidth'.
458 If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains
459 '#', shift right does not affect lines starting with '#' (these are supposed
460 to be C preprocessor lines that must stay in column 1).
462 When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as
463 much as possible to make the indent.  You can use ">><<" to replace an indent
464 made out of spaces with the same indent made out of <Tab>s (and a few spaces
465 if necessary).  If the 'expandtab' option is on, Vim uses only spaces.  Then
466 you can use ">><<" to replace <Tab>s in the indent by spaces (or use
467 ":retab!").
469 To move a line several 'shiftwidth's, use Visual mode or the ":" commands.
470 For example: >
471         Vjj4>           move three lines 4 indents to the right
472         :<<<            move current line 3 indents to the left
473         :>> 5           move 5 lines 2 indents to the right
474         :5>>            move line 5 2 indents to the right
476 ==============================================================================
477 4. Complex changes                                      *complex-change*
479 4.1 Filter commands                                     *filter*
481 A filter is a program that accepts text at standard input, changes it in some
482 way, and sends it to standard output.  You can use the commands below to send
483 some text through a filter, so that it is replaced by the filter output.
484 Examples of filters are "sort", which sorts lines alphabetically, and
485 "indent", which formats C program files (you need a version of indent that
486 works like a filter; not all versions do).  The 'shell' option specifies the
487 shell Vim uses to execute the filter command (See also the 'shelltype'
488 option).  You can repeat filter commands with ".".  Vim does not recognize a
489 comment (starting with '"') after the ":!" command.
491                                                         *!*
492 !{motion}{filter}       Filter {motion} text lines through the external
493                         program {filter}.
495                                                         *!!*
496 !!{filter}              Filter [count] lines through the external program
497                         {filter}.
499                                                         *v_!*
500 {Visual}!{filter}       Filter the highlighted lines through the external
501                         program {filter} (for {Visual} see |Visual-mode|).
502                         {not in Vi}
504 :{range}![!]{filter} [!][arg]                           *:range!*
505                         Filter {range} lines through the external program
506                         {filter}.  Vim replaces the optional bangs with the
507                         latest given command and appends the optional [arg].
508                         Vim saves the output of the filter command in a
509                         temporary file and then reads the file into the buffer
510                         |tempfile|.  Vim uses the 'shellredir' option to
511                         redirect the filter output to the temporary file.
512                         However, if the 'shelltemp' option is off then pipes
513                         are used when possible (on Unix).
514                         When the 'R' flag is included in 'cpoptions' marks in
515                         the filtered lines are deleted, unless the
516                         |:keepmarks| command is used.  Example: >
517                                 :keepmarks '<,'>!sort
518 <                       When the number of lines after filtering is less than
519                         before, marks in the missing lines are deleted anyway.
521                                                         *=*
522 ={motion}               Filter {motion} lines through the external program
523                         given with the 'equalprg' option.  When the 'equalprg'
524                         option is empty (this is the default), use the
525                         internal formatting function |C-indenting|.  But when
526                         'indentexpr' is not empty, it will be used instead
527                         |indent-expression|.  When Vim was compiled without
528                         internal formatting then the "indent" program is used
529                         as a last resort.
531                                                         *==*
532 ==                      Filter [count] lines like with ={motion}.
534                                                         *v_=*
535 {Visual}=               Filter the highlighted lines like with ={motion}.
536                         {not in Vi}
539                                                 *tempfile* *setuid*
540 Vim uses temporary files for filtering, generating diffs and also for
541 tempname().  For Unix, the file will be in a private directory (only
542 accessible by the current user) to avoid security problems (e.g., a symlink
543 attack or other people reading your file).  When Vim exits the directory and
544 all files in it are deleted.  When Vim has the setuid bit set this may cause
545 problems, the temp file is owned by the setuid user but the filter command
546 probably runs as the original user.
547 On MS-DOS and OS/2 the first of these directories that works is used: $TMP,
548 $TEMP, c:\TMP, c:\TEMP.
549 For Unix the list of directories is: $TMPDIR, /tmp, current-dir, $HOME.
550 For MS-Windows the GetTempFileName() system function is used.
551 For other systems the tmpnam() library function is used.
555 4.2 Substitute                                          *:substitute*
556                                                         *:s* *:su*
557 :[range]s[ubstitute]/{pattern}/{string}/[flags] [count]
558                         For each line in [range] replace a match of {pattern}
559                         with {string}.
560                         For the {pattern} see |pattern|.
561                         {string} can be a literal string, or something
562                         special; see |sub-replace-special|.
563                         When [range] and [count] are omitted, replace in the
564                         current line only.
565                         When [count] is given, replace in [count] lines,
566                         starting with the last line in [range].  When [range]
567                         is omitted start in the current line.
568                         Also see |cmdline-ranges|.
569                         See |:s_flags| for [flags].
571 :[range]s[ubstitute] [flags] [count]
572 :[range]&[&][flags] [count]                                     *:&*
573                         Repeat last :substitute with same search pattern and
574                         substitute string, but without the same flags.  You
575                         may add [flags], see |:s_flags|.
576                         Note that after ":substitute" the '&' flag can't be
577                         used, it's recognized as a pattern separator.
578                         The space between ":substitute" and the 'c', 'g' and
579                         'r' flags isn't required, but in scripts it's a good
580                         idea to keep it to avoid confusion.
582 :[range]~[&][flags] [count]                                     *:~*
583                         Repeat last substitute with same substitute string
584                         but with last used search pattern.  This is like
585                         ":&r".  See |:s_flags| for [flags].
587                                                                 *&*
588 &                       Synonym for ":s" (repeat last substitute).  Note
589                         that the flags are not remembered, thus it might
590                         actually work differently.  You can use ":&&" to keep
591                         the flags.
593                                                                 *g&*
594 g&                      Synonym for ":%s//~/&" (repeat last substitute on all
595                         lines with the same flags).
596                         Mnemonic: global substitute. {not in Vi}
598                                                 *:snomagic* *:sno*
599 :[range]sno[magic] ...  Same as ":substitute", but always use 'nomagic'.
600                         {not in Vi}
602                                                 *:smagic* *:sm*
603 :[range]sm[agic] ...    Same as ":substitute", but always use 'magic'.
604                         {not in Vi}
606                                                         *:s_flags*
607 The flags that you can use for the substitute commands:
609 [&]     Must be the first one: Keep the flags from the previous substitute
610         command.  Examples: >
611                 :&&
612                 :s/this/that/&
613 <       Note that ":s" and ":&" don't keep the flags.
614         {not in Vi}
616 [c]     Confirm each substitution.  Vim highlights the matching string (with
617         |hl-IncSearch|).  You can type:                         *:s_c*
618             'y'     to substitute this match
619             'l'     to substitute this match and then quit ("last")
620             'n'     to skip this match
621             <Esc>   to quit substituting
622             'a'     to substitute this and all remaining matches {not in Vi}
623             'q'     to quit substituting {not in Vi}
624             CTRL-E  to scroll the screen up {not in Vi, not available when
625                         compiled without the +insert_expand feature}
626             CTRL-Y  to scroll the screen down {not in Vi, not available when
627                         compiled without the +insert_expand feature}
628         If the 'edcompatible' option is on, Vim remembers the [c] flag and
629         toggles it each time you use it, but resets it when you give a new
630         search pattern.
631         {not in Vi: highlighting of the match, other responses than 'y' or 'n'}
633 [e]     When the search pattern fails, do not issue an error message and, in
634         particular, continue in maps as if no error occurred.  This is most
635         useful to prevent the "No match" error from breaking a mapping.  Vim
636         does not suppress the following error messages, however:
637                 Regular expressions can't be delimited by letters
638                 \ should be followed by /, ? or &
639                 No previous substitute regular expression
640                 Trailing characters
641                 Interrupted
642         {not in Vi}
644 [g]     Replace all occurrences in the line.  Without this argument,
645         replacement occurs only for the first occurrence in each line.  If
646         the 'edcompatible' option is on, Vim remembers this flag and toggles
647         it each time you use it, but resets it when you give a new search
648         pattern.  If the 'gdefault' option is on, this flag is on by default
649         and the [g] argument switches it off.
651 [i]     Ignore case for the pattern.  The 'ignorecase' and 'smartcase' options
652         are not used.
653         {not in Vi}
655 [I]     Don't ignore case for the pattern.  The 'ignorecase' and 'smartcase'
656         options are not used.
657         {not in Vi}
659 [n]     Report the number of matches, do not actually substitute.  The [c]
660         flag is ignored.  The matches are reported as if 'report' is zero.
661         Useful to |count-items|.
663 [p]     Print the line containing the last substitute.
665 [#]     Like [p] and prepend the line number.
667 [l]     Like [p] but print the text like |:list|.
669 [r]     Only useful in combination with ":&" or ":s" without arguments.  ":&r"
670         works the same way as ":~":  When the search pattern is empty, use the
671         previously used search pattern instead of the search pattern from the
672         last substitute or ":global".  If the last command that did a search
673         was a substitute or ":global", there is no effect.  If the last
674         command was a search command such as "/", use the pattern from that
675         command.
676         For ":s" with an argument this already happens: >
677                 :s/blue/red/
678                 /green
679                 :s//red/   or  :~   or  :&r
680 <       The last commands will replace "green" with "red". >
681                 :s/blue/red/
682                 /green
683                 :&
684 <       The last command will replace "blue" with "red".
685         {not in Vi}
687 Note that there is no flag to change the "magicness" of the pattern.  A
688 different command is used instead, or you can use |/\v| and friends.  The
689 reason is that the flags can only be found by skipping the pattern, and in
690 order to skip the pattern the "magicness" must be known.  Catch 22!
692 If the {pattern} for the substitute command is empty, the command uses the
693 pattern from the last substitute or ":global" command.  With the [r] flag, the
694 command uses the pattern from the last substitute, ":global", or search
695 command.
697 If the {string} is omitted the substitute is done as if it's empty.  Thus the
698 matched pattern is deleted.  The separator after {pattern} can also be left
699 out then.  Example: >
700         :%s/TESTING
701 This deletes "TESTING" from all lines, but only one per line.
703 For compatibility with Vi these two exceptions are allowed:
704 "\/{string}/" and "\?{string}?" do the same as "//{string}/r".
705 "\&{string}&" does the same as "//{string}/".
706                                                         *E146*
707 Instead of the '/' which surrounds the pattern and replacement string, you
708 can use any other single-byte character, but not an alphanumeric character,
709 '\', '"' or '|'.  This is useful if you want to include a '/' in the search
710 pattern or replacement string.  Example: >
711         :s+/+//+
713 For the definition of a pattern, see |pattern|.  In Visual block mode, use
714 |/\%V| in the pattern to have the substitute work in the block only.
715 Otherwise it works on whole lines anyway.
717                                         *sub-replace-special* *:s\=*
718 When the {string} starts with "\=" it is evaluated as an expression, see
719 |sub-replace-expression|.  You can use that for any special characters.
720 Otherwise these characters in {string} have a special meaning:
721                                                                 *:s%*
722 When {string} is equal to "%" and '/' is included with the 'cpoptions' option,
723 then the {string} of the previous substitute command is used. |cpo-/|
725 magic   nomagic   action    ~
726   &       \&      replaced with the whole matched pattern            *s/\&*
727  \&        &      replaced with &
728       \0          replaced with the whole matched pattern          *\0* *s/\0*
729       \1          replaced with the matched pattern in the first
730                   pair of ()                                         *s/\1*
731       \2          replaced with the matched pattern in the second
732                   pair of ()                                         *s/\2*
733       ..          ..                                                 *s/\3*
734       \9          replaced with the matched pattern in the ninth
735                   pair of ()                                         *s/\9*
736   ~       \~      replaced with the {string} of the previous
737                   substitute                                         *s~*
738  \~        ~      replaced with ~                                    *s/\~*
739       \u          next character made uppercase                      *s/\u*
740       \U          following characters made uppercase, until \E      *s/\U*
741       \l          next character made lowercase                      *s/\l*
742       \L          following characters made lowercase, until \E      *s/\L*
743       \e          end of \u, \U, \l and \L (NOTE: not <Esc>!)        *s/\e*
744       \E          end of \u, \U, \l and \L                           *s/\E*
745       <CR>        split line in two at this point
746                   (Type the <CR> as CTRL-V <Enter>)                  *s<CR>*
747       \r          idem                                               *s/\r*
748       \<CR>       insert a carriage-return (CTRL-M)
749                   (Type the <CR> as CTRL-V <Enter>)                  *s/\<CR>*
750       \n          insert a <NL> (<NUL> in the file)
751                   (does NOT break the line)                          *s/\n*
752       \b          insert a <BS>                                      *s/\b*
753       \t          insert a <Tab>                                     *s/\t*
754       \\          insert a single backslash                          *s/\\*
755       \x          where x is any character not mentioned above:
756                   Reserved for future expansion
758 Examples: >
759   :s/a\|b/xxx\0xxx/g             modifies "a b"      to "xxxaxxx xxxbxxx"
760   :s/\([abc]\)\([efg]\)/\2\1/g   modifies "af fa bg" to "fa fa gb"
761   :s/abcde/abc^Mde/              modifies "abcde"    to "abc", "de" (two lines)
762   :s/$/\^M/                      modifies "abcde"    to "abcde^M"
763   :s/\w\+/\u\0/g                 modifies "bla bla"  to "Bla Bla"
765 Note: In previous versions CTRL-V was handled in a special way.  Since this is
766 not Vi compatible, this was removed.  Use a backslash instead.
768 command         text    result ~
769 :s/aa/a^Ma/     aa      a<line-break>a
770 :s/aa/a\^Ma/    aa      a^Ma
771 :s/aa/a\\^Ma/   aa      a\<line-break>a
773 (you need to type CTRL-V <CR> to get a ^M here)
775 The numbering of "\1", "\2" etc. is done based on which "\(" comes first in
776 the pattern (going left to right).  When a parentheses group matches several
777 times, the last one will be used for "\1", "\2", etc.  Example: >
778   :s/\(\(a[a-d] \)*\)/\2/      modifies "aa ab x" to "ab x"
780 When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\),
781 either the first or second pattern in parentheses did not match, so either
782 \1 or \2 is empty.  Example: >
783   :s/\([ab]\)\|\([cd]\)/\1x/g   modifies "a b c d"  to "ax bx x x"
786 Substitute with an expression                   *sub-replace-expression*
787                                                 *sub-replace-\=*
788 When the substitute string starts with "\=" the remainder is interpreted as an
789 expression.  This does not work recursively: a substitute() function inside
790 the expression cannot use "\=" for the substitute string.
792 The special meaning for characters as mentioned at |sub-replace-special| does
793 not apply except for "<CR>", "\<CR>" and "\\".  Thus in the result of the
794 expression you need to use two backslashes to get one, put a backslash before a
795 <CR> you want to insert, and use a <CR> without a backslash where you want to
796 break the line.
798 For convenience a <NL> character is also used as a line break.  Prepend a
799 backslash to get a real <NL> character (which will be a NUL in the file).
801 When the result is a |List| then the items are joined with separating line
802 breaks.  Thus each item becomes a line, except that they can contain line
803 breaks themselves.
805 The whole matched text can be accessed with "submatch(0)".  The text matched
806 with the first pair of () with "submatch(1)".  Likewise for further
807 sub-matches in ().
809 Be careful: The separation character must not appear in the expression!
810 Consider using a character like "@" or ":".  There is no problem if the result
811 of the expression contains the separation character.
813 Examples: >
814         :s@\n@\="\r" . expand("$HOME") . "\r"@
815 This replaces an end-of-line with a new line containing the value of $HOME. >
817         s/E/\="\<Char-0x20ac>"/g
818 This replaces each 'E' character with a euro sign.  Read more in |<Char->|.
821 4.3 Search and replace                                  *search-replace*
823                                                         *:pro* *:promptfind*
824 :promptf[ind] [string]
825                         Put up a Search dialog.  When [string] is given, it is
826                         used as the initial search string.
827                         {only for Win32, Motif and GTK GUI}
829                                                 *:promptr* *:promptrepl*
830 :promptr[epl] [string]
831                         Put up a Search/Replace dialog.  When [string] is
832                         given, it is used as the initial search string.
833                         {only for Win32, Motif and GTK GUI}
836 4.4 Changing tabs                                       *change-tabs*
837                                                         *:ret* *:retab*
838 :[range]ret[ab][!] [new_tabstop]
839                         Replace all sequences of white-space containing a
840                         <Tab> with new strings of white-space using the new
841                         tabstop value given.  If you do not specify a new
842                         tabstop size or it is zero, Vim uses the current value
843                         of 'tabstop'.
844                         The current value of 'tabstop' is always used to
845                         compute the width of existing tabs.
846                         With !, Vim also replaces strings of only normal
847                         spaces with tabs where appropriate.
848                         With 'expandtab' on, Vim replaces all tabs with the
849                         appropriate number of spaces.
850                         This command sets 'tabstop' to the new value given,
851                         and if performed on the whole file, which is default,
852                         should not make any visible change.
853                         Careful: This command modifies any <Tab> characters
854                         inside of strings in a C program.  Use "\t" to avoid
855                         this (that's a good habit anyway).
856                         ":retab!" may also change a sequence of spaces by
857                         <Tab> characters, which can mess up a printf().
858                         {not in Vi}
859                         Not available when |+ex_extra| feature was disabled at
860                         compile time.
862                                                         *retab-example*
863 Example for using autocommands and ":retab" to edit a file which is stored
864 with tabstops at 8 but edited with tabstops set at 4.  Warning: white space
865 inside of strings can change!  Also see 'softtabstop' option. >
867   :auto BufReadPost     *.xx    retab! 4
868   :auto BufWritePre     *.xx    retab! 8
869   :auto BufWritePost    *.xx    retab! 4
870   :auto BufNewFile      *.xx    set ts=4
872 ==============================================================================
873 5. Copying and moving text                              *copy-move*
875                                                         *quote*
876 "{a-zA-Z0-9.%#:-"}      Use register {a-zA-Z0-9.%#:-"} for next delete, yank
877                         or put (use uppercase character to append with
878                         delete and yank) ({.%#:} only work with put).
880                                                         *:reg* *:registers*
881 :reg[isters]            Display the contents of all numbered and named
882                         registers.  If a register is written to for |:redir|
883                         it will not be listed.
884                         {not in Vi}
887 :reg[isters] {arg}      Display the contents of the numbered and named
888                         registers that are mentioned in {arg}.  For example: >
889                                 :dis 1a
890 <                       to display registers '1' and 'a'.  Spaces are allowed
891                         in {arg}.  {not in Vi}
893                                                         *:di* *:display*
894 :di[splay] [arg]        Same as :registers.  {not in Vi}
896                                                         *y* *yank*
897 ["x]y{motion}           Yank {motion} text [into register x].  When no
898                         characters are to be yanked (e.g., "y0" in column 1),
899                         this is an error when 'cpoptions' includes the 'E'
900                         flag.
902                                                         *yy*
903 ["x]yy                  Yank [count] lines [into register x] |linewise|.
905                                                         *Y*
906 ["x]Y                   yank [count] lines [into register x] (synonym for
907                         yy, |linewise|).  If you like "Y" to work from the
908                         cursor to the end of line (which is more logical,
909                         but not Vi-compatible) use ":map Y y$".
911                                                         *v_y*
912 {Visual}["x]y           Yank the highlighted text [into register x] (for
913                         {Visual} see |Visual-mode|).  {not in Vi}
915                                                         *v_Y*
916 {Visual}["x]Y           Yank the highlighted lines [into register x] (for
917                         {Visual} see |Visual-mode|).  {not in Vi}
919                                                         *:y* *:yank*
920 :[range]y[ank] [x]      Yank [range] lines [into register x].
922 :[range]y[ank] [x] {count}
923                         Yank {count} lines, starting with last line number
924                         in [range] (default: current line |cmdline-ranges|),
925                         [into register x].
927                                                         *p* *put* *E353*
928 ["x]p                   Put the text [from register x] after the cursor
929                         [count] times.  {Vi: no count}
931                                                         *P*
932 ["x]P                   Put the text [from register x] before the cursor
933                         [count] times.  {Vi: no count}
935                                                         *<MiddleMouse>*
936 ["x]<MiddleMouse>       Put the text from a register before the cursor [count]
937                         times.  Uses the "* register, unless another is
938                         specified.
939                         Leaves the cursor at the end of the new text.
940                         Using the mouse only works when 'mouse' contains 'n'
941                         or 'a'.
942                         {not in Vi}
943                         If you have a scrollwheel and often accidentally paste
944                         text, you can use these mappings to disable the
945                         pasting with the middle mouse button: >
946                                 :map <MiddleMouse> <Nop>
947                                 :imap <MiddleMouse> <Nop>
948 <                       You might want to disable the multi-click versions
949                         too, see |double-click|.
951                                                         *gp*
952 ["x]gp                  Just like "p", but leave the cursor just after the new
953                         text.  {not in Vi}
955                                                         *gP*
956 ["x]gP                  Just like "P", but leave the cursor just after the new
957                         text.  {not in Vi}
959                                                         *:pu* *:put*
960 :[line]pu[t] [x]        Put the text [from register x] after [line] (default
961                         current line).  This always works |linewise|, thus
962                         this command can be used to put a yanked block as new
963                         lines.
964                         The cursor is left on the first non-blank in the last
965                         new line.
966                         The register can also be '=' followed by an optional
967                         expression.  The expression continues until the end of
968                         the command.  You need to escape the '|' and '"'
969                         characters to prevent them from terminating the
970                         command.  Example: >
971                                 :put ='path' . \",/test\"
972 <                       If there is no expression after '=', Vim uses the
973                         previous expression.  You can see it with ":dis =".
975 :[line]pu[t]! [x]       Put the text [from register x] before [line] (default
976                         current line).
978 ["x]]p              or                                  *]p* *]<MiddleMouse>*
979 ["x]]<MiddleMouse>      Like "p", but adjust the indent to the current line.
980                         Using the mouse only works when 'mouse' contains 'n'
981                         or 'a'.  {not in Vi}
983 ["x][P              or                                  *[P*
984 ["x]]P              or                                  *]P*
985 ["x][p              or                                  *[p* *[<MiddleMouse>*
986 ["x][<MiddleMouse>      Like "P", but adjust the indent to the current line.
987                         Using the mouse only works when 'mouse' contains 'n'
988                         or 'a'.  {not in Vi}
990 You can use these commands to copy text from one place to another.  Do this
991 by first getting the text into a register with a yank, delete or change
992 command, then inserting the register contents with a put command.  You can
993 also use these commands to move text from one file to another, because Vim
994 preserves all registers when changing buffers (the CTRL-^ command is a quick
995 way to toggle between two files).
997                                 *linewise-register* *characterwise-register*
998 You can repeat the put commands with "." (except for :put) and undo them.  If
999 the command that was used to get the text into the register was |linewise|,
1000 Vim inserts the text below ("p") or above ("P") the line where the cursor is.
1001 Otherwise Vim inserts the text after ("p") or before ("P") the cursor.  With
1002 the ":put" command, Vim always inserts the text in the next line.  You can
1003 exchange two characters with the command sequence "xp".  You can exchange two
1004 lines with the command sequence "ddp".  You can exchange two words with the
1005 command sequence "deep" (start with the cursor in the blank space before the
1006 first word).  You can use the "']" or "`]" command after the put command to
1007 move the cursor to the end of the inserted text, or use "'[" or "`[" to move
1008 the cursor to the start.
1010                                                 *put-Visual-mode* *v_p* *v_P*
1011 When using a put command like |p| or |P| in Visual mode, Vim will try to
1012 replace the selected text with the contents of the register.  Whether this
1013 works well depends on the type of selection and the type of the text in the
1014 register.  With blockwise selection it also depends on the size of the block
1015 and whether the corners are on an existing character.  (Implementation detail:
1016 it actually works by first putting the register after the selection and then
1017 deleting the selection.)
1018 The previously selected text is put in the unnamed register.  If you want to
1019 put the same text into a Visual selection several times you need to use
1020 another register.  E.g., yank the text to copy, Visually select the text to
1021 replace and use "0p .  You can repeat this as many times as you like, the
1022 unnamed register will be changed each time.
1024                                                         *blockwise-register*
1025 If you use a blockwise Visual mode command to get the text into the register,
1026 the block of text will be inserted before ("P") or after ("p") the cursor
1027 column in the current and next lines.  Vim makes the whole block of text start
1028 in the same column.  Thus the inserted text looks the same as when it was
1029 yanked or deleted.  Vim may replace some <Tab> characters with spaces to make
1030 this happen.  However, if the width of the block is not a multiple of a <Tab>
1031 width and the text after the inserted block contains <Tab>s, that text may be
1032 misaligned.
1034 Note that after a characterwise yank command, Vim leaves the cursor on the
1035 first yanked character that is closest to the start of the buffer.  This means
1036 that "yl" doesn't move the cursor, but "yh" moves the cursor one character
1037 left.
1038 Rationale:      In Vi the "y" command followed by a backwards motion would
1039                 sometimes not move the cursor to the first yanked character,
1040                 because redisplaying was skipped.  In Vim it always moves to
1041                 the first character, as specified by Posix.
1042 With a linewise yank command the cursor is put in the first line, but the
1043 column is unmodified, thus it may not be on the first yanked character.
1045 There are nine types of registers:                      *registers* *E354*
1046 1. The unnamed register ""
1047 2. 10 numbered registers "0 to "9
1048 3. The small delete register "-
1049 4. 26 named registers "a to "z or "A to "Z
1050 5. four read-only registers ":, "., "% and "#
1051 6. the expression register "=
1052 7. The selection and drop registers "*, "+ and "~ 
1053 8. The black hole register "_
1054 9. Last search pattern register "/
1056 1. Unnamed register ""                          *quote_quote* *quotequote*
1057 Vim fills this register with text deleted with the "d", "c", "s", "x" commands
1058 or copied with the yank "y" command, regardless of whether or not a specific
1059 register was used (e.g.  "xdd).  This is like the unnamed register is pointing
1060 to the last used register.  Thus when appending using an uppercase register
1061 name, the unnamed register contains the same text as the named register.
1062 An exception is the '_' register: "_dd does not store the deleted text in any
1063 register.
1064 Vim uses the contents of the unnamed register for any put command (p or P)
1065 which does not specify a register.  Additionally you can access it with the
1066 name '"'.  This means you have to type two double quotes.  Writing to the ""
1067 register writes to register "0.
1068 {Vi: register contents are lost when changing files, no '"'}
1070 2. Numbered registers "0 to "9          *quote_number* *quote0* *quote1*
1071                                         *quote2* *quote3* *quote4* *quote9*
1072 Vim fills these registers with text from yank and delete commands.
1073    Numbered register 0 contains the text from the most recent yank command,
1074 unless the command specified another register with ["x].
1075    Numbered register 1 contains the text deleted by the most recent delete or
1076 change command, unless the command specified another register or the text is
1077 less than one line (the small delete register is used then).  An exception is
1078 made for the delete operator with these movement commands: |%|, |(|, |)|, |`|,
1079 |/|, |?|, |n|, |N|, |{| and |}|.  Register "1 is always used then (this is Vi
1080 compatible).  The "- register is used as well if the delete is within a line.
1081    With each successive deletion or change, Vim shifts the previous contents
1082 of register 1 into register 2, 2 into 3, and so forth, losing the previous
1083 contents of register 9.
1084 {Vi: numbered register contents are lost when changing files; register 0 does
1085 not exist}
1087 3. Small delete register "-                             *quote_-* *quote-*
1088 This register contains text from commands that delete less than one line,
1089 except when the command specifies a register with ["x].
1090 {not in Vi}
1092 4. Named registers "a to "z or "A to "Z                 *quote_alpha* *quotea*
1093 Vim fills these registers only when you say so.  Specify them as lowercase
1094 letters to replace their previous contents or as uppercase letters to append
1095 to their previous contents.  When the '>' flag is present in 'cpoptions' then
1096 a line break is inserted before the appended text.
1098 5. Read-only registers ":, "., "% and "#
1099 These are '%', '#', ':' and '.'.  You can use them only with the "p", "P",
1100 and ":put" commands and with CTRL-R.  {not in Vi}
1101                                                 *quote_.* *quote.* *E29*
1102         ".      Contains the last inserted text (the same as what is inserted
1103                 with the insert mode commands CTRL-A and CTRL-@).  Note: this
1104                 doesn't work with CTRL-R on the command-line.  It works a bit
1105                 differently, like inserting the text instead of putting it
1106                 ('textwidth' and other options affect what is inserted).
1107                                                         *quote_%* *quote%*
1108         "%      Contains the name of the current file.
1109                                                         *quote_#* *quote#*
1110         "#      Contains the name of the alternate file.
1111                                                 *quote_:* *quote:* *E30*
1112         ":      Contains the most recent executed command-line.  Example: Use
1113                 "@:" to repeat the previous command-line command.
1114                 The command-line is only stored in this register when at least
1115                 one character of it was typed.  Thus it remains unchanged if
1116                 the command was completely from a mapping.
1117                 {not available when compiled without the |+cmdline_hist|
1118                 feature}
1120 6. Expression register "=                       *quote_=* *quote=* *@=*
1121 This is not really a register that stores text, but is a way to use an
1122 expression in commands which use a register.  The expression register is
1123 read-only; you cannot put text into it.  After the '=', the cursor moves to
1124 the command-line, where you can enter any expression (see |expression|).  All
1125 normal command-line editing commands are available, including a special
1126 history for expressions.  When you end the command-line by typing <CR>, Vim
1127 computes the result of the expression.  If you end it with <Esc>, Vim abandons
1128 the expression.  If you do not enter an expression, Vim uses the previous
1129 expression (like with the "/" command).
1131 The expression must evaluate to a String.  A Number is always automatically
1132 converted to a String.  For the "p" and ":put" command, if the result is a
1133 Float it's converted into a String.  If the result is a List each element is
1134 turned into a String and used as a line.  A Dictionary or FuncRef results in
1135 an error message (use string() to convert).
1137 If the "= register is used for the "p" command, the String is split up at <NL>
1138 characters.  If the String ends in a <NL>, it is regarded as a linewise
1139 register.  {not in Vi}
1141 7. Selection and drop registers "*, "+ and "~ 
1142 Use these register for storing and retrieving the selected text for the GUI.
1143 See |quotestar| and |quoteplus|.  When the clipboard is not available or not
1144 working, the unnamed register is used instead.  For Unix systems the clipboard
1145 is only available when the |+xterm_clipboard| feature is present.  {not in Vi}
1147 Note that there is only a distinction between "* and "+ for X11 systems.  For
1148 an explanation of the difference, see |x11-selection|.  Under MS-Windows, use
1149 of "* and "+ is actually synonymous and refers to the |gui-clipboard|.
1151                                                 *quote_~* *quote~* *<Drop>*
1152 The read-only "~ register stores the dropped text from the last drag'n'drop
1153 operation.  When something has been dropped onto Vim, the "~ register is
1154 filled in and the <Drop> pseudo key is sent for notification.  You can remap
1155 this key if you want; the default action (for all modes) is to insert the
1156 contents of the "~ register at the cursor position.  {not in Vi}
1157 {only available when compiled with the |+dnd| feature, currently only with the
1158 GTK GUI}
1160 Note: The "~ register is only used when dropping plain text onto Vim.
1161 Drag'n'drop of URI lists is handled internally.
1163 8. Black hole register "_                               *quote_*
1164 When writing to this register, nothing happens.  This can be used to delete
1165 text without affecting the normal registers.  When reading from this register,
1166 nothing is returned.  {not in Vi}
1168 9. Last search pattern register "/                      *quote_/* *quote/*
1169 Contains the most recent search-pattern.  This is used for "n" and 'hlsearch'.
1170 It is writable with ":let", you can change it to have 'hlsearch' highlight
1171 other matches without actually searching.  You can't yank or delete into this
1172 register.  The search direction is available in |v:searchforward|.
1173 Note that the valued is restored when returning from a function
1174 |function-search-undo|.
1175 {not in Vi}
1177                                                         *@/*
1178 You can write to a register with a ":let" command |:let-@|.  Example: >
1179         :let @/ = "the"
1181 If you use a put command without specifying a register, Vim uses the register
1182 that was last filled (this is also the contents of the unnamed register).  If
1183 you are confused, use the ":dis" command to find out what Vim will put (this
1184 command displays all named and numbered registers; the unnamed register is
1185 labelled '"').
1187 The next three commands always work on whole lines.
1189 :[range]co[py] {address}                                *:co* *:copy*
1190                         Copy the lines given by [range] to below the line
1191                         given by {address}.
1193                                                         *:t*
1194 :t                      Synonym for copy.
1196 :[range]m[ove] {address}                        *:m* *:mo* *:move* *E134*
1197                         Move the lines given by [range] to below the line
1198                         given by {address}.
1200 ==============================================================================
1201 6. Formatting text                                      *formatting*
1203 :[range]ce[nter] [width]                                *:ce* *:center*
1204                         Center lines in [range] between [width] columns
1205                         (default 'textwidth' or 80 when 'textwidth' is 0).
1206                         {not in Vi}
1207                         Not available when |+ex_extra| feature was disabled at
1208                         compile time.
1210 :[range]ri[ght] [width]                                 *:ri* *:right*
1211                         Right-align lines in [range] at [width] columns
1212                         (default 'textwidth' or 80 when 'textwidth' is 0).
1213                         {not in Vi}
1214                         Not available when |+ex_extra| feature was disabled at
1215                         compile time.
1217                                                         *:le* *:left*
1218 :[range]le[ft] [indent]
1219                         Left-align lines in [range].  Sets the indent in the
1220                         lines to [indent] (default 0).  {not in Vi}
1221                         Not available when |+ex_extra| feature was disabled at
1222                         compile time.
1224                                                         *gq*
1225 gq{motion}              Format the lines that {motion} moves over.
1226                         Formatting is done with one of three methods:
1227                         1. If 'formatexpr' is not empty the expression is
1228                            evaluated.  This can differ for each buffer.
1229                         2. If 'formatprg' is not empty an external program
1230                            is used.
1231                         3. Otherwise formatting is done internally.
1233                         In the third case the 'textwidth' option controls the
1234                         length of each formatted line (see below).
1235                         If the 'textwidth' option is 0, the formatted line
1236                         length is the screen width (with a maximum width of
1237                         79).
1238                         The 'formatoptions' option controls the type of
1239                         formatting |fo-table|.
1240                         The cursor is left on the first non-blank of the last
1241                         formatted line.
1242                         NOTE: The "Q" command formerly performed this
1243                         function.  If you still want to use "Q" for
1244                         formatting, use this mapping: >
1245                                 :nnoremap Q gq
1247 gqgq                                                    *gqgq* *gqq*
1248 gqq                     Format the current line.  {not in Vi}
1250                                                         *v_gq*
1251 {Visual}gq              Format the highlighted text.  (for {Visual} see
1252                         |Visual-mode|).  {not in Vi}
1254                                                         *gw*
1255 gw{motion}              Format the lines that {motion} moves over.  Similar to
1256                         |gq| but puts the cursor back at the same position in
1257                         the text.  However, 'formatprg' and 'formatexpr' are
1258                         not used.  {not in Vi}
1260 gwgw                                                    *gwgw* *gww*
1261 gww                     Format the current line as with "gw".  {not in Vi}
1263                                                         *v_gw*
1264 {Visual}gw              Format the highlighted text as with "gw".  (for
1265                         {Visual} see |Visual-mode|).  {not in Vi}
1267 Example: To format the current paragraph use:                   *gqap*  >
1268         gqap
1270 The "gq" command leaves the cursor in the line where the motion command takes
1271 the cursor.  This allows you to repeat formatting repeated with ".".  This
1272 works well with "gqj" (format current and next line) and "gq}" (format until
1273 end of paragraph).  Note: When 'formatprg' is set, "gq" leaves the cursor on
1274 the first formatted line (as with using a filter command).
1276 If you want to format the current paragraph and continue where you were, use: >
1277         gwap
1278 If you always want to keep paragraphs formatted you may want to add the 'a'
1279 flag to 'formatoptions'.  See |auto-format|.
1281 If the 'autoindent' option is on, Vim uses the indent of the first line for
1282 the following lines.
1284 Formatting does not change empty lines (but it does change lines with only
1285 white space!).
1287 The 'joinspaces' option is used when lines are joined together.
1289 You can set the 'formatexpr' option to an expression or the 'formatprg' option
1290 to the name of an external program for Vim to use for text formatting.  The
1291 'textwidth' and other options have no effect on formatting by an external
1292 program.
1294                                                         *right-justify*
1295 There is no command in Vim to right justify text.  You can do it with
1296 an external command, like "par" (e.g.: "!}par" to format until the end of the
1297 paragraph) or set 'formatprg' to "par".
1299                                                         *format-comments*
1300 An overview of comment formatting is in section |30.6| of the user manual.
1302 Vim can automatically insert and format comments in a special way.  Vim
1303 recognizes a comment by a specific string at the start of the line (ignoring
1304 white space).  Three types of comments can be used:
1306 - A comment string that repeats at the start of each line.  An example is the
1307   type of comment used in shell scripts, starting with "#".
1308 - A comment string that occurs only in the first line, not in the following
1309   lines.  An example is this list with dashes.
1310 - Three-piece comments that have a start string, an end string, and optional
1311   lines in between.  The strings for the start, middle and end are different.
1312   An example is the C style comment:
1313         /*
1314          * this is a C comment
1315          */
1317 The 'comments' option is a comma-separated list of parts.  Each part defines a
1318 type of comment string.  A part consists of:
1319         {flags}:{string}
1321 {string} is the literal text that must appear.
1323 {flags}:
1324   n     Nested comment.  Nesting with mixed parts is allowed.  If 'comments'
1325         is "n:),n:>" a line starting with "> ) >" is a comment.
1327   b     Blank (<Space>, <Tab> or <EOL>) required after {string}.
1329   f     Only the first line has the comment string.  Do not repeat comment on
1330         the next line, but preserve indentation (e.g., a bullet-list).
1332   s     Start of three-piece comment
1334   m     Middle of a three-piece comment
1336   e     End of a three-piece comment
1338   l     Left align. Used together with 's' or 'e', the leftmost character of
1339         start or end will line up with the leftmost character from the middle.
1340         This is the default and can be omitted. See below for more details.
1342   r     Right align. Same as above but rightmost instead of leftmost. See
1343         below for more details.
1345   O     Don't consider this comment for the "O" command.
1347   x     Allows three-piece comments to be ended by just typing the last
1348         character of the end-comment string as the first action on a new
1349         line when the middle-comment string has been inserted automatically.
1350         See below for more details.
1352   {digits}
1353         When together with 's' or 'e': add {digit} amount of offset to an
1354         automatically inserted middle or end comment leader. The offset begins
1355         from a left alignment. See below for more details.
1357   -{digits}
1358         Like {digits} but reduce the indent.  This only works when there is
1359         some indent for the start or end part that can be removed.
1361 When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the
1362 comment string repeats at the start of each line.  The flags field may be
1363 empty.
1365 Any blank space in the text before and after the {string} is part of the
1366 {string}, so do not include leading or trailing blanks unless the blanks are a
1367 required part of the comment string.
1369 When one comment leader is part of another, specify the part after the whole.
1370 For example, to include both "-" and "->", use >
1371         :set comments=f:->,f:-
1373 A three-piece comment must always be given as start,middle,end, with no other
1374 parts in between.  An example of a three-piece comment is >
1375         sr:/*,mb:*,ex:*/
1376 for C-comments.  To avoid recognizing "*ptr" as a comment, the middle string
1377 includes the 'b' flag.  For three-piece comments, Vim checks the text after
1378 the start and middle strings for the end string.  If Vim finds the end string,
1379 the comment does not continue on the next line.  Three-piece comments must
1380 have a middle string because otherwise Vim can't recognize the middle lines.
1382 Notice the use of the "x" flag in the above three-piece comment definition.
1383 When you hit Return in a C-comment, Vim will insert the middle comment leader
1384 for the new line: " * ".  To close this comment you just have to type "/"
1385 before typing anything else on the new line.  This will replace the
1386 middle-comment leader with the end-comment leader and apply any specified
1387 alignment, leaving just " */".  There is no need to hit BackSpace first.
1390 Here is an example of alignment flags at work to make a comment stand out
1391 (kind of looks like a 1 too). Consider comment string >
1392         sr:/***,m:**,ex2:******/
1394                                    /***
1395                                      **<--right aligned from "r" flag
1396                                      **
1397 offset 2 spaces from the "2" flag--->**
1398                                    ******/
1399 In this case, the first comment was typed, then return was pressed 4 times,
1400 then "/" was pressed to end the comment.
1402 Here are some finer points of three part comments. There are three times when
1403 alignment and offset flags are taken into consideration: opening a new line
1404 after a start-comment, opening a new line before an end-comment, and
1405 automatically ending a three-piece comment.  The end alignment flag has a
1406 backwards perspective; the result is that the same alignment flag used with
1407 "s" and "e" will result in the same indent for the starting and ending pieces.
1408 Only one alignment per comment part is meant to be used, but an offset number
1409 will override the "r" and "l" flag.
1411 Enabling 'cindent' will override the alignment flags in many cases.
1412 Reindenting using a different method like |gq| or |=| will not consult
1413 alignment flags either. The same behaviour can be defined in those other
1414 formatting options. One consideration is that 'cindent' has additional options
1415 for context based indenting of comments but cannot replicate many three piece
1416 indent alignments.  However, 'indentexpr' is has the ability to work better
1417 with three piece comments.
1419 Other examples: >
1420    "b:*"        Includes lines starting with "*", but not if the "*" is
1421                 followed by a non-blank.  This avoids a pointer dereference
1422                 like "*str" to be recognized as a comment.
1423    "n:>"        Includes a line starting with ">", ">>", ">>>", etc.
1424    "fb:-"       Format a list that starts with "- ".
1426 By default, "b:#" is included.  This means that a line that starts with
1427 "#include" is not recognized as a comment line.  But a line that starts with
1428 "# define" is recognized.  This is a compromise.
1430 {not available when compiled without the |+comments| feature}
1432                                                         *fo-table*
1433 You can use the 'formatoptions' option  to influence how Vim formats text.
1434 'formatoptions' is a string that can contain any of the letters below.  The
1435 default setting is "tcq".  You can separate the option letters with commas for
1436 readability.
1438 letter   meaning when present in 'formatoptions'    ~
1440 t       Auto-wrap text using textwidth
1441 c       Auto-wrap comments using textwidth, inserting the current comment
1442         leader automatically.
1443 r       Automatically insert the current comment leader after hitting
1444         <Enter> in Insert mode.
1445 o       Automatically insert the current comment leader after hitting 'o' or
1446         'O' in Normal mode.
1447 q       Allow formatting of comments with "gq".
1448         Note that formatting will not change blank lines or lines containing
1449         only the comment leader.  A new paragraph starts after such a line,
1450         or when the comment leader changes.
1451 w       Trailing white space indicates a paragraph continues in the next line.
1452         A line that ends in a non-white character ends a paragraph.
1453 a       Automatic formatting of paragraphs.  Every time text is inserted or
1454         deleted the paragraph will be reformatted.  See |auto-format|.
1455         When the 'c' flag is present this only happens for recognized
1456         comments.
1457 n       When formatting text, recognize numbered lists.  This actually uses
1458         the 'formatlistpat' option, thus any kind of list can be used.  The
1459         indent of the text after the number is used for the next line.  The
1460         default is to find a number, optionally followed by '.', ':', ')',
1461         ']' or '}'.  Note that 'autoindent' must be set too.  Doesn't work
1462         well together with "2".
1463         Example: >
1464                 1. the first item
1465                    wraps
1466                 2. the second item
1467 2       When formatting text, use the indent of the second line of a paragraph
1468         for the rest of the paragraph, instead of the indent of the first
1469         line.  This supports paragraphs in which the first line has a
1470         different indent than the rest.  Note that 'autoindent' must be set
1471         too.  Example: >
1472                         first line of a paragraph
1473                 second line of the same paragraph
1474                 third line.
1475 v       Vi-compatible auto-wrapping in insert mode: Only break a line at a
1476         blank that you have entered during the current insert command.  (Note:
1477         this is not 100% Vi compatible.  Vi has some "unexpected features" or
1478         bugs in this area.  It uses the screen column instead of the line
1479         column.)
1480 b       Like 'v', but only auto-wrap if you enter a blank at or before
1481         the wrap margin.  If the line was longer than 'textwidth' when you
1482         started the insert, or you do not enter a blank in the insert before
1483         reaching 'textwidth', Vim does not perform auto-wrapping.
1484 l       Long lines are not broken in insert mode: When a line was longer than
1485         'textwidth' when the insert command started, Vim does not
1486         automatically format it.
1487 m       Also break at a multi-byte character above 255.  This is useful for
1488         Asian text where every character is a word on its own.
1489 M       When joining lines, don't insert a space before or after a multi-byte
1490         character.  Overrules the 'B' flag.
1491 B       When joining lines, don't insert a space between two multi-byte
1492         characters.  Overruled by the 'M' flag.
1493 1       Don't break a line after a one-letter word.  It's broken before it
1494         instead (if possible).
1497 With 't' and 'c' you can specify when Vim performs auto-wrapping:
1498 value   action  ~
1499 ""      no automatic formatting (you can use "gq" for manual formatting)
1500 "t"     automatic formatting of text, but not comments
1501 "c"     automatic formatting for comments, but not text (good for C code)
1502 "tc"    automatic formatting for text and comments
1504 Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but
1505 does insert comment leaders according to the 'comments' option).  An exception
1506 is when the 'a' flag is present. |auto-format|
1508 Note that when 'paste' is on, Vim does no formatting at all.
1510 Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping;
1511 'textwidth' is still useful for formatting with "gq".
1513 If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some
1514 built in stuff to treat these types of comments a bit more cleverly.
1515 Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in
1516 'formatoptions') gives the correct start of the line automatically.  The same
1517 happens with formatting and auto-wrapping.  Opening a line after a line
1518 starting with "/*" or "*" and containing "*/", will cause no comment leader to
1519 be inserted, and the indent of the new line is taken from the line containing
1520 the start of the comment.
1521 E.g.:
1522     /* ~
1523      * Your typical comment. ~
1524      */ ~
1525     The indent on this line is the same as the start of the above
1526     comment.
1528 All of this should be really cool, especially in conjunction with the new
1529 :autocmd command to prepare different settings for different types of file.
1531 Some examples:
1532   for C code (only format comments): >
1533         :set fo=croq
1534 < for Mail/news (format all, don't start comment with "o" command): >
1535         :set fo=tcrq
1538 Automatic formatting                                    *auto-format*
1540 When the 'a' flag is present in 'formatoptions' text is formatted
1541 automatically when inserting text or deleting text.  This works nice for
1542 editing text paragraphs.  A few hints on how to use this:
1544 - You need to properly define paragraphs.  The simplest is paragraphs that are
1545   separated by a blank line.  When there is no separating blank line, consider
1546   using the 'w' flag and adding a space at the end of each line in the
1547   paragraphs except the last one.
1549 - You can set the 'formatoptions' based on the type of file |filetype| or
1550   specifically for one file with a |modeline|.
1552 - Set 'formatoptions' to "aw2tq" to make text with indents like this:
1554             bla bla foobar bla 
1555         bla foobar bla foobar bla
1556             bla bla foobar bla 
1557         bla foobar bla bla foobar
1559 - Add the 'c' flag to only auto-format comments.  Useful in source code.
1561 - Set 'textwidth' to the desired width.  If it is zero then 79 is used, or the
1562   width of the screen if this is smaller.
1564 And a few warnings:
1566 - When part of the text is not properly separated in paragraphs, making
1567   changes in this text will cause it to be formatted anyway.  Consider doing >
1569         :set fo-=a
1571 - When using the 'w' flag (trailing space means paragraph continues) and
1572   deleting the last line of a paragraph with |dd|, the paragraph will be
1573   joined with the next one.
1575 - Changed text is saved for undo.  Formatting is also a change.  Thus each
1576   format action saves text for undo.  This may consume quite a lot of memory.
1578 - Formatting a long paragraph and/or with complicated indenting may be slow.
1580 ==============================================================================
1581 7. Sorting text                                         *sorting*
1583 Vim has a sorting function and a sorting command.  The sorting function can be
1584 found here: |sort()|.
1586                                                         *:sor* *:sort*
1587 :[range]sor[t][!] [i][u][r][n][x][o] [/{pattern}/]
1588                         Sort lines in [range].  When no range is given all
1589                         lines are sorted.
1591                         With [!] the order is reversed.
1593                         With [i] case is ignored.
1595                         With [n] sorting is done on the first decimal number
1596                         in the line (after or inside a {pattern} match).
1597                         One leading '-' is included in the number.
1599                         With [x] sorting is done on the first hexadecimal
1600                         number in the line (after or inside a {pattern}
1601                         match).  A leading "0x" or "0X" is ignored.
1602                         One leading '-' is included in the number.
1604                         With [o] sorting is done on the first octal number in
1605                         the line (after or inside a {pattern} match).
1607                         With [u] only keep the first of a sequence of
1608                         identical lines (ignoring case when [i] is used).
1609                         Without this flag, a sequence of identical lines
1610                         will be kept in their original order.
1611                         Note that leading and trailing white space may cause
1612                         lines to be different.
1614                         When /{pattern}/ is specified and there is no [r] flag
1615                         the text matched with {pattern} is skipped, so that
1616                         you sort on what comes after the match.
1617                         Instead of the slash any non-letter can be used.
1618                         For example, to sort on the second comma-separated
1619                         field: >
1620                                 :sort /[^,]*,/
1621 <                       To sort on the text at virtual column 10 (thus
1622                         ignoring the difference between tabs and spaces): >
1623                                 :sort /.*\%10v/
1624 <                       To sort on the first number in the line, no matter
1625                         what is in front of it: >
1626                                 :sort /.\{-}\ze\d/
1627 <                       (Explanation: ".\{-}" matches any text, "\ze" sets the
1628                         end of the match and \d matches a digit.)
1629                         With [r] sorting is done on the matching {pattern}
1630                         instead of skipping past it as described above.
1631                         For example, to sort on only the first three letters
1632                         of each line: >
1633                                 :sort /\a\a\a/ r
1635 <                       If a {pattern} is used, any lines which don't have a
1636                         match for {pattern} are kept in their current order,
1637                         but separate from the lines which do match {pattern}.
1638                         If you sorted in reverse, they will be in reverse
1639                         order after the sorted lines, otherwise they will be
1640                         in their original order, right before the sorted
1641                         lines.
1643                         If {pattern} is empty (e.g. // is specified), the
1644                         last search pattern is used.  This allows trying out
1645                         a pattern first.
1647 Note that using ":sort" with ":global" doesn't sort the matching lines, it's
1648 quite useless.
1650 The details about sorting depend on the library function used.  There is no
1651 guarantee that sorting is "stable" or obeys the current locale.  You will have
1652 to try it out.
1654 The sorting can be interrupted, but if you interrupt it too late in the
1655 process you may end up with duplicated lines.  This also depends on the system
1656 library function used.
1658  vim:tw=78:ts=8:ft=help:norl: