runtime/doc/change.txt

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