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