1*change.txt* For Vim version 7.0aa. Last change: 2004 Jun 16 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, currently 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 1141gwgw *gwgw* *gww* 1142gww Format the current line as with "gw". {not in Vi} 1143 1144 *v_gw* 1145{Visual}gw Format the highlighted text as with "gw". (for 1146 {Visual} see |Visual-mode|). {not in Vi} 1147 1148Example: To format the current paragraph use: *gqap* > 1149 gqap 1150 1151The "gq" command leaves the cursor in the line where the motion command takes 1152the cursor. This allows you to repeat formatting repeated with ".". This 1153works well with "gqj" (format current and next line) and "gq}" (format until 1154end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on 1155the first formatted line (as with using a filter command). 1156 1157If you want to format the current paragraph and continue where you were, use: > 1158 gwap 1159If you always want to keep paragraphs formatted you may want to add the 'a' 1160flag to 'formatoptions'. See |auto-format|. 1161 1162If the 'autoindent' option is on, Vim uses the indent of the first line for 1163the following lines. 1164 1165Formatting does not change empty lines (but it does change lines with only 1166white space!). 1167 1168The 'joinspaces' option is used when lines are joined together. 1169 1170You can set the 'formatprg' option to the name of an external program for Vim 1171to use for text formatting. The 'textwidth' and other options have no effect 1172on formatting by an external program. 1173 1174 *right-justify* 1175There is no command in Vim to right justify text. You can do it with 1176an external command, like "par" (e.g.: "!}par" to format until the end of the 1177paragraph) or set 'formatprg' to "par". 1178 1179 *format-comments* 1180Vim can format comments in a special way. Vim recognizes a comment by a 1181specific string at the start of the line (ignoring white space). Three types 1182of comments can be used: 1183 1184- A comment string that repeats at the start of each line. An example is the 1185 type of comment used in shell scripts, starting with "#". 1186- A comment string that occurs only in the first line, not in the following 1187 lines. An example is this list with dashes. 1188- Three-piece comments that have a start string, an end string, and optional 1189 lines in between. The strings for the start, middle and end are different. 1190 An example is the C-style comment: 1191 /* 1192 * this is a C comment 1193 */ 1194 1195The 'comments' option is a comma-separated list of parts. Each part defines a 1196type of comment string. A part consists of: 1197 {flags}:{string} 1198 1199{string} is the literal text that must appear. 1200 1201{flags}: 1202 n Nested comment. Nesting with mixed parts is allowed. If 'comments' 1203 is "n:),n:>" a line starting with "> ) >" is a comment. 1204 1205 b Blank (<Space>, <Tab> or <EOL>) required after {string}. 1206 1207 f Only the first line has the comment string. Do not repeat comment on 1208 the next line, but preserve indentation (e.g., a bullet-list). 1209 1210 s Start of three-piece comment 1211 1212 m Middle of a three-piece comment 1213 1214 e End of a three-piece comment 1215 1216 l Left adjust middle with start or end (default). Only recognized when 1217 used together with 's' or 'e'. 1218 1219 r Right adjust middle with start or end. Only recognized when used 1220 together with 's' or 'e'. 1221 1222 O Don't use this one for the "O" command. 1223 1224 x Allows three-piece comments to be ended by just typing the last 1225 character of the end-comment string as the first character on a new 1226 line, when the middle-comment string has already been inserted 1227 automatically. See below for more details. 1228 1229 {digits} 1230 When together with 's' or 'e': add extra indent for the middle part. 1231 This can be used to left-align the middle part with the start or end 1232 and then add an offset. 1233 1234 -{digits} 1235 Like {digits} but reduce the indent. This only works when there is 1236 some indent for the start or end part that can be removed. 1237 1238When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the 1239comment string repeats at the start of each line. The flags field may be 1240empty. 1241 1242Any blank space in the text before and after the {string} is part of the 1243{string}, so do not include leading or trailing blanks unless the blanks are a 1244required part of the comment string. 1245 1246When one comment leader is part of another, specify the part after the whole. 1247For example, to include both "-" and "->", use > 1248 :set comments=f:->,f:- 1249 1250A three-piece comment must always be given as start,middle,end, with no other 1251parts in between. An example of a three-piece comment is > 1252 sr:/*,mb:*,ex:*/ 1253for C-comments. To avoid recognizing "*ptr" as a comment, the middle string 1254includes the 'b' flag. For three-piece comments, Vim checks the text after 1255the start and middle strings for the end string. If Vim finds the end string, 1256the comment does not continue on the next line. Three-piece comments must 1257have a middle string because otherwise Vim can't recognize the middle lines. 1258 1259Notice the use of the "x" flag in the above three-piece comment definition. 1260When you hit Return in a C-comment, Vim will insert the middle comment leader 1261for the new line, e.g. " * ". To close this comment you just have to type "/" 1262before typing anything else on the new line. This will replace the 1263middle-comment leader with the end-comment leader, leaving just " */". There 1264is no need to hit BackSpace first. 1265 1266Examples: > 1267 "b:*" Includes lines starting with "*", but not if the "*" is 1268 followed by a non-blank. This avoids a pointer dereference 1269 like "*str" to be recognized as a comment. 1270 "n:>" Includes a line starting with ">", ">>", ">>>", etc. 1271 "fb:-" Format a list that starts with "- ". 1272 1273By default, "b:#" is included. This means that a line that starts with 1274"#include" is not recognized as a comment line. But a line that starts with 1275"# define" is recognized. This is a compromise. 1276 1277Often the alignment can be changed from right alignment to a left alignment 1278with an additional space. For example, for Javadoc comments, this can be 1279used (insert a backslash before the space when using ":set"): > 1280 s1:/*,mb:*,ex:*/ 1281Note that an offset is included with start, so that the middle part is left 1282aligned with the start and then an offset of one character added. This makes 1283it possible to left align the start and middle for this construction: > 1284 /** 1285 * comment 1286 */ 1287 1288{not available when compiled without the |+comments| feature} 1289 1290 *fo-table* 1291You can use the 'formatoptions' option to influence how Vim formats text. 1292'formatoptions' is a string that can contain any of the letters below. The 1293default setting is "tcq". You can separate the option letters with commas for 1294readability. 1295 1296letter meaning when present in 'formatoptions' ~ 1297 1298t Auto-wrap text using textwidth (does not apply to comments) 1299c Auto-wrap comments using textwidth, inserting the current comment 1300 leader automatically. 1301r Automatically insert the current comment leader after hitting 1302 <Enter> in Insert mode. 1303o Automatically insert the current comment leader after hitting 'o' or 1304 'O' in Normal mode. 1305q Allow formatting of comments with "gq". 1306 Note that formatting will not change blank lines or lines containing 1307 only the comment leader. A new paragraph starts after such a line, 1308 or when the comment leader changes. 1309w Trailing white space indicates a paragraph continues in the next line. 1310 A line that ends in a non-white character ends a paragraph. 1311a Automatic formatting of paragraphs. Every time text is inserted or 1312 deleted the paragraph will be reformatted. See |auto-format|. 1313 When the 'c' flag is present this only happens for recognized 1314 comments. 1315n When formatting text, recognize numbered lists. The indent of the 1316 text after the number is used for the next line. The number may 1317 optionally be followed by '.', ':', ')', ']' or '}'. Note that 1318 'autoindent' must be set too. Doesn't work well together with "2". 1319 Example: > 1320 1. the first item 1321 wraps 1322 2. the second item 13232 When formatting text, use the indent of the second line of a paragraph 1324 for the rest of the paragraph, instead of the indent of the first 1325 line. This supports paragraphs in which the first line has a 1326 different indent than the rest. Note that 'autoindent' must be set 1327 too. Example: > 1328 first line of a paragraph 1329 second line of the same paragraph 1330 third line. 1331v Vi-compatible auto-wrapping in insert mode: Only break a line at a 1332 blank that you have entered during the current insert command. (Note: 1333 this is not 100% Vi compatible. Vi has some "unexpected features" or 1334 bugs in this area. It uses the screen column instead of the line 1335 column.) 1336b Like 'v', but only auto-wrap if you enter a blank at or before 1337 the wrap margin. If the line was longer than 'textwidth' when you 1338 started the insert, or you do not enter a blank in the insert before 1339 reaching 'textwidth', Vim does not perform auto-wrapping. 1340l Long lines are not broken in insert mode: When a line was longer than 1341 'textwidth' when the insert command started, Vim does not 1342 automatically format it. 1343m Also break at a multi-byte character above 255. This is useful for 1344 Asian text where every character is a word on its own. 1345M When joining lines, don't insert a space before or after a multi-byte 1346 character. Overrules the 'B' flag. 1347B When joining lines, don't insert a space between two multi-byte 1348 characters. Overruled by the 'M' flag. 13491 Don't break a line after a one-letter word. It's broken before it 1350 instead (if possible). 1351 1352 1353With 't' and 'c' you can specify when Vim performs auto-wrapping: 1354value action ~ 1355"" no automatic formatting (you can use "gq" for manual formatting) 1356"t" automatic formatting of text, but not comments 1357"c" automatic formatting for comments, but not text (good for C code) 1358"tc" automatic formatting for text and comments 1359 1360Note that when 'textwidth' is 0, Vim does no formatting anyway (but does 1361insert comment leaders according to the 'comments' option). 1362 1363Note that when 'paste' is on, Vim does no formatting at all. 1364 1365Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping; 1366'textwidth' is still useful for formatting with "gq". 1367 1368If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some 1369built in stuff to treat these types of comments a bit more cleverly. 1370Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in 1371'formatoptions') gives the correct start of the line automatically. The same 1372happens with formatting and auto-wrapping. Opening a line after a line 1373starting with "/*" or "*" and containing "*/", will cause no comment leader to 1374be inserted, and the indent of the new line is taken from the line containing 1375the start of the comment. 1376E.g.: 1377 /* ~ 1378 * Your typical comment. ~ 1379 */ ~ 1380 The indent on this line is the same as the start of the above 1381 comment. 1382 1383All of this should be really cool, especially in conjunction with the new 1384:autocmd command to prepare different settings for different types of file. 1385 1386Some examples: 1387 for C code (only format comments): > 1388 :set fo=croq 1389< for Mail/news (format all, don't start comment with "o" command): > 1390 :set fo=tcrq 1391< 1392 1393Automatic formatting *auto-format* 1394 1395When the 'a' flag is present in 'formatoptions' text is formatted 1396automatically when inserting text or deleting text. This works nice for 1397editing text paragraphs. A few hints on how to use this: 1398 1399- You need to properly define paragraphs. The simplest is paragraphs that are 1400 separated by a blank line. When there is no separating blank line, consider 1401 using the 'w' flag and adding a space at the end of each line in the 1402 paragraphs except the last one. 1403 1404- You can set the 'formatoptions' based on the type of file |filetype| or 1405 specifically for one file with a |modeline|. 1406 1407- Set 'formatoptions' to "aw2tq" to make text with indents like this: 1408 1409 bla bla foobar bla 1410 bla foobar bla foobar bla 1411 bla bla foobar bla 1412 bla foobar bla bla foobar 1413 1414- Add the 'c' flag to only auto-format comments. Useful in source code. 1415 1416And a few warnings: 1417 1418- When part of the text is not properly separated in paragraphs, making 1419 changes in this text will cause it to be formatted anyway. Consider doing > 1420 1421 :set fo-=a 1422 1423- When using the 'w' flag (trailing space means paragraph continues) and 1424 deleting the last line of a paragraph with |dd|, the paragraph will be 1425 joined with the next one. 1426 1427- Changed text is saved for undo. Formatting is also a change. Thus each 1428 format action saves text for undo. This may consume quite a lot of memory. 1429 1430- Formatting a long paragraph and/or with complicated indenting may be slow. 1431 1432 1433 vim:tw=78:ts=8:ft=help:norl: 1434