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