change.txt (83721B)
1 *change.txt* For Vim version 9.2. Last change: 2026 Sep 25 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 This file describes commands that delete or change text. In this context, 8 changing text means deleting the text and replacing it with other text using 9 one command. You can undo all of these commands. You can repeat the non-Ex 10 commands with the "." command. 11 12 1. Deleting text |deleting| 13 2. Delete and insert |delete-insert| 14 3. Simple changes |simple-change| *changing* 15 4. Complex changes |complex-change| 16 4.1 Filter commands |filter| 17 4.2 Substitute |:substitute| 18 4.3 Search and replace |search-replace| 19 4.4 Changing tabs |change-tabs| 20 5. Copying and moving text |copy-move| 21 6. Formatting text |formatting| 22 7. Sorting text |sorting| 23 8. Deduplicating text |deduplicating| 24 25 For inserting text see |insert.txt|. 26 27 ============================================================================== 28 1. Deleting text *deleting* *E470* 29 30 ["x]<Del> or *<Del>* *x* *dl* 31 ["x]x Delete [count] characters under and after the cursor 32 [into register x] (not |linewise|). Does the same as 33 "dl". 34 The <Del> key does not take a [count]. Instead, it 35 deletes the last character of the count. 36 See |:fixdel| if the <Del> key does not do what you 37 want. See 'whichwrap' for deleting a line break 38 (join lines). 39 40 *X* *dh* 41 ["x]X Delete [count] characters before the cursor [into 42 register x] (not |linewise|). Does the same as "dh". 43 Also see 'whichwrap'. 44 45 *d* 46 ["x]d{motion} Delete text that {motion} moves over [into register 47 x]. See below for exceptions. 48 49 *dd* 50 ["x]dd Delete [count] lines [into register x] |linewise|. 51 52 *D* 53 ["x]D Delete the characters under the cursor until the end 54 of the line and [count]-1 more lines [into register 55 x]; synonym for "d$". 56 (not |linewise|) 57 When the '#' flag is in 'cpoptions' the count is 58 ignored. 59 60 {Visual}["x]x or *v_x* *v_d* *v_<Del>* 61 {Visual}["x]d or 62 {Visual}["x]<Del> Delete the highlighted text [into register x] (for 63 {Visual} see |Visual-mode|). 64 65 {Visual}["x]CTRL-H or *v_CTRL-H* *v_<BS>* 66 {Visual}["x]<BS> When in Select mode: Delete the highlighted text [into 67 register x]. 68 69 {Visual}["x]X or *v_X* *v_D* *v_b_D* 70 {Visual}["x]D Delete the highlighted lines [into register x] (for 71 {Visual} see |Visual-mode|). In Visual block mode, 72 "D" deletes the highlighted text plus all text until 73 the end of the line. 74 75 *:d* *:de* *:del* *:delete* *:dl* *:dp* 76 :[range]d[elete] [x] Delete [range] lines (default: current line) [into 77 register x]. 78 Note these weird abbreviations applicable only to 79 legacy Vim script: 80 :dl delete and list 81 :dell idem 82 :delel idem 83 :deletl idem 84 :deletel idem 85 :dp delete and print 86 :dep idem 87 :delp idem 88 :delep idem 89 :deletp idem 90 :deletep idem 91 Warning: These give |E492| in |Vim9| script and `:dl` 92 executes as `:dlist`. 93 94 :[range]d[elete] [x] {count} 95 Delete {count} lines, starting with [range] 96 (default: current line |cmdline-ranges|) [into 97 register x]. 98 99 These commands delete text. You can repeat them with the `.` command 100 (except `:d`) and undo them. Use Visual mode to delete blocks of text. See 101 |registers| for an explanation of registers. 102 *d-special* 103 An exception for the d{motion} command: If the motion is not linewise, the 104 start and end of the motion are not in the same line, and there are only 105 blanks before the start and there are no non-blanks after the end of the 106 motion, the delete becomes linewise. This means that the delete also removes 107 the line of blanks that you might expect to remain. Use the |o_v| operator to 108 force the motion to be characterwise or remove the "z" flag from 'cpoptions' 109 (see |cpo-z|) to disable this peculiarity. 110 111 Trying to delete an empty region of text (e.g., "d0" in the first column) 112 is an error when 'cpoptions' includes the 'E' flag. 113 114 *J* 115 J Join [count] lines, with a minimum of two lines. 116 Remove the indent and insert up to two spaces (see 117 below). Fails when on the last line of the buffer. 118 If [count] is too big it is reduced to the number of 119 lines available. 120 121 *v_J* 122 {Visual}J Join the highlighted lines, with a minimum of two 123 lines. Remove the indent and insert up to two spaces 124 (see below). 125 126 *gJ* 127 gJ Join [count] lines, with a minimum of two lines. 128 Don't insert or remove any spaces. 129 130 *v_gJ* 131 {Visual}gJ Join the highlighted lines, with a minimum of two 132 lines. Don't insert or remove any spaces. 133 134 *:j* *:join* 135 :[range]j[oin][!] [flags] 136 Join [range] lines. Same as "J", except with [!] 137 the join does not insert or delete any spaces. 138 If a [range] has equal start and end values, this 139 command does nothing. The default behavior is to 140 join the current line with the line below it. 141 See |ex-flags| for [flags]. 142 143 :[range]j[oin][!] {count} [flags] 144 Join {count} lines, starting with [range] (default: 145 current line |cmdline-ranges|). Same as "J", except 146 with [!] the join does not insert or delete any 147 spaces. 148 See |ex-flags| for [flags]. 149 150 These commands delete the <EOL> between lines. This has the effect of joining 151 multiple lines into one line. You can repeat these commands (except `:j`) and 152 undo them. 153 154 These commands, except "gJ", insert one space in place of the <EOL> unless 155 there is trailing white space or the next line starts with a ')'. These 156 commands, except "gJ", delete any leading white space on the next line. If 157 the 'joinspaces' option is on, these commands insert two spaces after a '.', 158 '!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces 159 only after a '.'). 160 The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting 161 spaces before and after a multibyte character |fo-table|. 162 163 The |'[| mark is set at the end of the first line that was joined, |']| at the 164 end of the resulting line. 165 166 167 ============================================================================== 168 2. Delete and insert *delete-insert* *replacing* 169 170 *R* 171 R Enter Replace mode: Each character you type replaces 172 an existing character, starting with the character 173 under the cursor. Repeat the entered text [count]-1 174 times. See |Replace-mode| for more details. 175 176 *gR* 177 gR Enter Virtual Replace mode: Each character you type 178 replaces existing characters in screen space. So a 179 <Tab> may replace several characters at once. 180 Repeat the entered text [count]-1 times. See 181 |Virtual-Replace-mode| for more details. 182 183 *c* 184 ["x]c{motion} Delete {motion} text [into register x] and start 185 insert. When 'cpoptions' includes the 'E' flag and 186 there is no text to delete (e.g., with "cTx" when the 187 cursor is just after an 'x'), an error occurs and 188 insert mode does not start (this is Vi compatible). 189 When 'cpoptions' does not include the 'E' flag, the 190 "c" command always starts insert mode, even if there 191 is no text to delete. 192 193 *cc* 194 ["x]cc Delete [count] lines [into register x] and start 195 insert |linewise|. If 'autoindent' is on, preserve 196 the indent of the first line. 197 198 *C* 199 ["x]C Delete from the cursor position to the end of the 200 line and [count]-1 more lines [into register x], and 201 start insert. Synonym for c$ (not |linewise|). 202 203 *s* 204 ["x]s Delete [count] characters [into register x] and start 205 insert (s stands for Substitute). Synonym for "cl" 206 (not |linewise|). 207 208 *S* 209 ["x]S Delete [count] lines [into register x] and start 210 insert. Synonym for "cc" |linewise|. 211 212 {Visual}["x]c or *v_c* *v_s* 213 {Visual}["x]s Delete the highlighted text [into register x] and 214 start insert (for {Visual} see |Visual-mode|). 215 216 *v_r* 217 {Visual}r{char} Replace all selected characters by {char}. 218 CTRL-C will be inserted literally. 219 220 *v_C* 221 {Visual}["x]C Delete the highlighted lines [into register x] and 222 start insert. In Visual block mode it works 223 differently |v_b_C|. 224 *v_S* 225 {Visual}["x]S Delete the highlighted lines [into register x] and 226 start insert (for {Visual} see |Visual-mode|). 227 *v_R* 228 {Visual}["x]R Currently just like {Visual}["x]S. In a next version 229 it might work differently. 230 231 Notes: 232 - You can end Insert and Replace mode with <Esc>. 233 - See the section "Insert and Replace mode" |mode-ins-repl| for the other 234 special characters in these modes. 235 - The effect of [count] takes place after Vim exits Insert or Replace mode. 236 - When the 'cpoptions' option contains '$' and the change is within one line, 237 Vim continues to show the text to be deleted and puts a '$' at the last 238 deleted character. 239 240 See |registers| for an explanation of registers. 241 242 Replace mode is just like Insert mode, except that every character you enter 243 deletes one character. If you reach the end of a line, Vim appends any 244 further characters (just like Insert mode). In Replace mode, the backspace 245 key restores the original text (if there was any). (See section "Insert and 246 Replace mode" |mode-ins-repl|). 247 248 *cw* *cW* 249 Special case: When the cursor is in a word, "cw" and "cW" do not include the 250 white space after a word, they only change up to the end of the word. This is 251 because Vim interprets "cw" as change-word, and a word does not include the 252 following white space. 253 {Vi: "cw" when on a blank followed by other blanks changes only the first 254 blank; this is probably a bug, because "dw" deletes all the blanks; use the 255 'w' flag in 'cpoptions' to make it work like Vi anyway} 256 257 If you prefer "cw" to include the space after a word, use this mapping: > 258 :map cw dwi 259 Alternatively use "caw" (see also |aw| and |cpo-z|). 260 261 *:c* *:ch* *:change* 262 :{range}c[hange][!] Replace lines of text with some different text. 263 Type a line containing only "." to stop replacing. 264 Without {range}, this command changes only the current 265 line. 266 Adding [!] toggles 'autoindent' for the time this 267 command is executed. 268 This command is not supported in |Vim9| script, 269 because it is too easily confused with a variable 270 name. 271 272 ============================================================================== 273 3. Simple changes *simple-change* 274 275 *r* 276 r{char} Replace the character under the cursor with {char}. 277 If {char} is a <CR> or <NL>, a line break replaces the 278 character. To replace with a real <CR>, use CTRL-V 279 <CR>. CTRL-V <NL> replaces with a <Nul>. 280 281 If {char} is CTRL-E or CTRL-Y the character from the 282 line below or above is used, just like with |i_CTRL-E| 283 and |i_CTRL-Y|. This also works with a count, thus 284 `10r<C-E>` copies 10 characters from the line below. 285 286 If you give a [count], Vim replaces [count] characters 287 with [count] {char}s. When {char} is a <CR> or <NL>, 288 however, Vim inserts only one <CR>: "5r<CR>" replaces 289 five characters with a single line break. 290 When {char} is a <CR> or <NL>, Vim performs 291 autoindenting. This works just like deleting the 292 characters that are replaced and then doing 293 "i<CR><Esc>". 294 {char} can be entered as a digraph |digraph-arg|. 295 |:lmap| mappings apply to {char}. The CTRL-^ command 296 in Insert mode can be used to switch this on/off 297 |i_CTRL-^|. See |utf-8-char-arg| about using 298 composing characters when 'encoding' is Unicode. 299 300 *gr* 301 gr{char} Replace the virtual characters under the cursor with 302 {char}. This replaces in screen space, not file 303 space. See |gR| and |Virtual-Replace-mode| for more 304 details. As with |r| a count may be given. 305 {char} can be entered like with |r|, but characters 306 that have a special meaning in Insert mode, such as 307 most CTRL-keys, cannot be used. 308 309 *digraph-arg* 310 The argument for Normal mode commands like |r| and |t| is a single character. 311 When 'cpo' doesn't contain the 'D' flag, this character can also be entered 312 like |digraphs|. First type CTRL-K and then the two digraph characters. 313 {not available when compiled without the |+digraphs| feature} 314 315 *case* 316 The following commands change the case of letters. The currently active 317 |locale| is used. See |:language|. The LC_CTYPE value matters here. 318 319 *~* 320 ~ 'notildeop' option: Switch case of the character 321 under the cursor and move the cursor to the right. 322 If a [count] is given, do that many characters. 323 324 ~{motion} 'tildeop' option: switch case of {motion} text. 325 326 *g~* 327 g~{motion} Switch case of {motion} text. 328 329 g~g~ *g~g~* *g~~* 330 g~~ Switch case of current line. 331 332 *v_~* 333 {Visual}~ Switch case of highlighted text (for {Visual} see 334 |Visual-mode|). 335 336 *v_U* 337 {Visual}U Make highlighted text uppercase (for {Visual} see 338 |Visual-mode|). 339 340 *gU* *uppercase* 341 gU{motion} Make {motion} text uppercase. 342 Example: > 343 :map! <C-F> <Esc>gUiw`]a 344 < This works in Insert mode: press CTRL-F to make the 345 word before the cursor uppercase. Handy to type 346 words in lowercase and then make them uppercase. 347 348 349 gUgU *gUgU* *gUU* 350 gUU Make current line uppercase. 351 352 *v_u* 353 {Visual}u Make highlighted text lowercase (for {Visual} see 354 |Visual-mode|). 355 356 *gu* *lowercase* 357 gu{motion} Make {motion} text lowercase. 358 359 gugu *gugu* *guu* 360 guu Make current line lowercase. 361 362 *g?* *rot13* 363 g?{motion} Rot13 encode {motion} text. 364 365 *v_g?* 366 {Visual}g? Rot13 encode the highlighted text (for {Visual} see 367 |Visual-mode|). 368 369 g?g? *g?g?* *g??* 370 g?? Rot13 encode current line. 371 372 To turn one line into title caps, make every first letter of a word 373 uppercase: > 374 :s/\v<(.)(\w*)/\u\1\L\2/g 375 376 377 Adding and subtracting ~ 378 *CTRL-A* 379 CTRL-A Add [count] to the number or alphabetic character at 380 or after the cursor. 381 382 *v_CTRL-A* 383 {Visual}CTRL-A Add [count] to the number or alphabetic character in 384 the highlighted text. 385 386 *v_g_CTRL-A* 387 {Visual}g CTRL-A Add [count] to the number or alphabetic character in 388 the highlighted text. If several lines are 389 highlighted, each one will be incremented by an 390 additional [count] (so effectively creating a 391 [count] incrementing sequence). 392 For Example, if you have this list of numbers: 393 1. ~ 394 1. ~ 395 1. ~ 396 1. ~ 397 Move to the second "1." and Visually select three 398 lines, pressing g CTRL-A results in: 399 1. ~ 400 2. ~ 401 3. ~ 402 4. ~ 403 404 *CTRL-X* 405 CTRL-X Subtract [count] from the number or alphabetic 406 character at or after the cursor. 407 408 *v_CTRL-X* 409 {Visual}CTRL-X Subtract [count] from the number or alphabetic 410 character in the highlighted text. 411 412 On MS-Windows, this is mapped to cut Visual text 413 |dos-standard-mappings|. If you want to disable the 414 mapping, use this: > 415 silent! vunmap <C-X> 416 < 417 *v_g_CTRL-X* 418 {Visual}g CTRL-X Subtract [count] from the number or alphabetic 419 character in the highlighted text. If several lines 420 are highlighted, each value will be decremented by an 421 additional [count] (so effectively creating a [count] 422 decrementing sequence). 423 424 The CTRL-A and CTRL-X commands can work for: 425 - signed and unsigned decimal numbers 426 - unsigned binary, octal and hexadecimal numbers 427 - alphabetic characters 428 429 This depends on the 'nrformats' option: 430 - When 'nrformats' includes "bin", Vim assumes numbers starting with '0b' or 431 '0B' are binary. 432 - When 'nrformats' includes "octal", Vim considers numbers starting with a '0' 433 to be octal, unless the number includes a '8' or '9'. Other numbers are 434 decimal and may have a preceding minus sign. 435 If the cursor is on a number, the commands apply to that number; otherwise 436 Vim uses the number to the right of the cursor. 437 - When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or 438 '0X' are hexadecimal. The case of the rightmost letter in the number 439 determines the case of the resulting hexadecimal number. If there is no 440 letter in the current number, Vim uses the previously detected case. 441 - When 'nrformats' includes "alpha", Vim will change the alphabetic character 442 under or after the cursor. This is useful to make lists with an alphabetic 443 index. 444 445 For decimals a leading negative sign is considered for incrementing/ 446 decrementing, for binary, octal and hex values, it won't be considered. To 447 ignore the sign Visually select the number before using CTRL-A or CTRL-X. 448 449 For numbers with leading zeros (including all octal and hexadecimal numbers), 450 Vim preserves the number of characters in the number when possible. CTRL-A on 451 "0077" results in "0100", CTRL-X on "0x100" results in "0x0ff". 452 There is one exception: When a number that starts with a zero is found not to 453 be octal (it contains a '8' or '9'), but 'nrformats' does include "octal", 454 leading zeros are removed to avoid that the result may be recognized as an 455 octal number. 456 457 Note that when 'nrformats' includes "octal", decimal numbers with leading 458 zeros cause mistakes, because they can be confused with octal numbers. 459 460 Note similarly, when 'nrformats' includes both "bin" and "hex", binary numbers 461 with a leading '0x' or '0X' can be interpreted as hexadecimal rather than 462 binary since '0b' are valid hexadecimal digits. CTRL-A on "0x0b11" results in 463 "0x0b12", not "0x0b100". 464 When 'nrformats' includes "bin" and doesn't include "hex", CTRL-A on "0b11" in 465 "0x0b11" results in "0x0b100". 466 467 When the number under the cursor is too big to fit into 32 or 64 bit 468 (depending on how Vim was build), it will be rounded off to the nearest number 469 that can be represented, and the addition/subtraction is skipped. E.g. with 470 64 bit support using CTRL-X on 18446744073709551616 results in 471 18446744073709551615. Same for larger numbers, such as 18446744073709551618. 472 473 The CTRL-A command is very useful in a macro. Example: Use the following 474 steps to make a numbered list. 475 476 1. Create the first list entry, make sure it starts with a number. 477 2. qa - start recording into register 'a' 478 3. Y - yank the entry 479 4. p - put a copy of the entry below the first one 480 5. CTRL-A - increment the number 481 6. q - stop recording 482 7. <count>@a - repeat the yank, put and increment <count> times 483 484 485 SHIFTING LINES LEFT OR RIGHT *shift-left-right* 486 487 *<* 488 <{motion} Shift {motion} lines one 'shiftwidth' leftwards. 489 490 If the 'vartabstop' feature is enabled, and the 491 'shiftwidth' option is set to zero, the amount of 492 indent is calculated at the first non-blank character 493 in the line. 494 *<<* 495 << Shift [count] lines one 'shiftwidth' leftwards. 496 497 *v_<* 498 {Visual}[count]< Shift the highlighted lines [count] 'shiftwidth' 499 leftwards (for {Visual} see |Visual-mode|). 500 501 *>* 502 >{motion} Shift {motion} lines one 'shiftwidth' rightwards. 503 504 If the 'vartabstop' feature is enabled, and the 505 'shiftwidth' option is set to zero, the amount of 506 indent is calculated at the first non-blank character 507 in the line. 508 *>>* 509 >> Shift [count] lines one 'shiftwidth' rightwards. 510 511 *v_>* 512 {Visual}[count]> Shift the highlighted lines [count] 'shiftwidth' 513 rightwards (for {Visual} see |Visual-mode|). 514 515 *:<* 516 :[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<' 517 for shifting multiple 'shiftwidth's. 518 519 :[range]< {count} Shift {count} lines one 'shiftwidth' left, starting 520 with [range] (default current line |cmdline-ranges|). 521 Repeat '<' for shifting multiple 'shiftwidth's. 522 523 :[range]le[ft] [indent] left align lines in [range]. Sets the indent in the 524 lines to [indent] (default 0). 525 526 *:>* 527 :[range]> [flags] Shift [range] lines one 'shiftwidth' right. 528 Repeat '>' for shifting multiple 'shiftwidth's. 529 See |ex-flags| for [flags]. 530 531 :[range]> {count} [flags] 532 Shift {count} lines one 'shiftwidth' right, starting 533 with [range] (default current line |cmdline-ranges|). 534 Repeat '>' for shifting multiple 'shiftwidth's. 535 See |ex-flags| for [flags]. 536 537 The ">" and "<" commands are handy for changing the indentation within 538 programs. Use the 'shiftwidth' option to set the size of the white space 539 which these commands insert or delete. Normally the 'shiftwidth' option is 8, 540 but you can set it to, say, 3 to make smaller indents. The shift leftwards 541 stops when there is no indent. The shift right does not affect empty lines. 542 543 If the 'shiftround' option is on, the indent is rounded to a multiple of 544 'shiftwidth'. 545 546 If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains 547 '#' with a zero value, shift right does not affect lines starting with '#' 548 (these are supposed to be C preprocessor lines that must stay in column 1). 549 This can be changed with the 'cino' option, see |cino-#|. 550 551 When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as 552 much as possible to make the indent. You can use ">><<" to replace an indent 553 made out of spaces with the same indent made out of <Tab>s (and a few spaces 554 if necessary). If the 'expandtab' option is on, Vim uses only spaces. Then 555 you can use ">><<" to replace <Tab>s in the indent by spaces (or use 556 `:retab!`). 557 558 To move a line several 'shiftwidth's, use Visual mode or the `:` commands. 559 For example: > 560 Vjj4> move three lines 4 indents to the right 561 :<<< move current line 3 indents to the left 562 :>> 5 move 5 lines 2 indents to the right 563 :5>> move line 5 2 indents to the right 564 565 ============================================================================== 566 4. Complex changes *complex-change* 567 568 4.1 Filter commands *filter* 569 570 A filter is a program that accepts text at standard input, changes it in some 571 way, and sends it to standard output. You can use the commands below to send 572 some text through a filter, so that it is replaced by the filter output. 573 Examples of filters are "sort", which sorts lines alphabetically, and 574 "indent", which formats C program files (you need a version of indent that 575 works like a filter; not all versions do). The 'shell' option specifies the 576 shell Vim uses to execute the filter command (See also the 'shelltype' 577 option). You can repeat filter commands with ".". Vim does not recognize a 578 comment (starting with '"') after the `:!` command. 579 580 *!* 581 !{motion}{filter} Filter {motion} text lines through the external 582 program {filter}. 583 584 *!!* 585 !!{filter} Filter [count] lines through the external program 586 {filter}. 587 588 *v_!* 589 {Visual}!{filter} Filter the highlighted lines through the external 590 program {filter} (for {Visual} see |Visual-mode|). 591 592 :{range}![!]{filter} [!][arg] *:range!* 593 For executing external commands see |:!| 594 595 Filter {range} lines through the external program 596 {filter}. Vim replaces the optional bangs with the 597 latest given command and appends the optional [arg]. 598 Vim saves the output of the filter command in a 599 temporary file and then reads the file into the buffer 600 |tempfile|. Vim uses the 'shellredir' option to 601 redirect the filter output to the temporary file. 602 However, if the 'shelltemp' option is off then pipes 603 are used when possible (on Unix). 604 When the 'R' flag is included in 'cpoptions' marks in 605 the filtered lines are deleted, unless the 606 |:keepmarks| command is used. Example: > 607 :keepmarks '<,'>!sort 608 < When the number of lines after filtering is less than 609 before, marks in the missing lines are deleted anyway. 610 611 *=* 612 ={motion} Filter {motion} lines through the external program 613 given with the 'equalprg' option. When the 'equalprg' 614 option is empty (this is the default), use the 615 internal formatting function |C-indenting| and 'lisp'. 616 But when 'indentexpr' is not empty, it will be used 617 instead |indent-expression|. When Vim was compiled 618 without internal formatting then the "indent" program 619 is used as a last resort. 620 621 *==* 622 == Filter [count] lines like with ={motion}. 623 624 *v_=* 625 {Visual}= Filter the highlighted lines like with ={motion}. 626 627 628 *tempfile* *setuid* 629 Vim uses temporary files for filtering, generating diffs and also for 630 tempname(). For Unix, the file will be in a private directory (only 631 accessible by the current user) to avoid security problems (e.g., a symlink 632 attack or other people reading your file). When Vim exits the directory and 633 all files in it are deleted (only on Unix, on other systems you will have to 634 clean up yourself). When Vim has the setuid bit set this may cause 635 problems, the temp file is owned by the setuid user but the filter command 636 probably runs as the original user. 637 Directory for temporary files is created in the first of these directories 638 that works: 639 Unix: $TMPDIR, /tmp, current-dir, $HOME. 640 Windows: $TMP, $TEMP, c:\TMP, c:\TEMP 641 For MS-Windows the GetTempFileName() system function is used. 642 For other systems the tmpnam() library function is used. 643 644 645 646 4.2 Substitute *:substitute* 647 *:s* *:su* 648 :[range]s[ubstitute]/{pattern}/{string}/[flags] [count] 649 For each line in [range] replace a match of {pattern} 650 with {string}. 651 For the {pattern} see |pattern|. 652 {string} can be a literal string, or something 653 special; see |sub-replace-special|. 654 When [range] and [count] are omitted, replace in the 655 current line only. When [count] is given, replace in 656 [count] lines, starting with the last line in [range]. 657 When [range] is omitted start in the current line. 658 *E939* *E1510* 659 [count] must be a positive number (max 2147483647) 660 Also see |cmdline-ranges|. 661 662 See |:s_flags| for [flags]. 663 The delimiter doesn't need to be /, see 664 |pattern-delimiter|. 665 666 :[range]s[ubstitute] [flags] [count] 667 :[range]&[&][flags] [count] *:&* 668 Repeat last :substitute with same search pattern and 669 substitute string, but without the same flags. You 670 may add [flags], see |:s_flags|. 671 Note that after `:substitute` the '&' and '#' flags 672 can't be used, they're recognized as a pattern 673 separator. 674 The space between `:substitute` and the 'c', 'g', 675 'i', 'I' and 'r' flags isn't required, but in scripts 676 it's a good idea to keep it to avoid confusion. 677 Also see the two and three letter commands to repeat 678 :substitute below |:substitute-repeat|. 679 680 :[range]~[&][flags] [count] *:~* 681 Repeat last substitute with same substitute string 682 but with last used search pattern. This is like 683 `:&r`. See |:s_flags| for [flags]. 684 685 *&* 686 & Synonym for `:s` (repeat last substitute). Note 687 that the flags are not remembered, thus it might 688 actually work differently. You can use `:&&` to keep 689 the flags. 690 691 *g&* 692 g& Synonym for `:%s//~/&` (repeat last substitute with 693 last search pattern on all lines with the same flags). 694 For example, when you first do a substitution with 695 `:s/pattern/repl/flags` and then `/search` for 696 something else, `g&` will do `:%s/search/repl/flags`. 697 Mnemonic: global substitute. 698 699 *:snomagic* *:sno* 700 :[range]sno[magic] ... Same as `:substitute`, but always use 'nomagic'. 701 702 *:smagic* *:sm* 703 :[range]sm[agic] ... Same as `:substitute`, but always use 'magic'. 704 705 *:s_flags* 706 The flags that you can use for the substitute commands: 707 708 *:&&* 709 [&] Must be the first one: Keep the flags from the previous substitute 710 command. Examples: > 711 :&& 712 :s/this/that/& 713 < Note that `:s` and `:&` don't keep the flags. 714 715 [c] Confirm each substitution. Vim highlights the matching string (with 716 |hl-IncSearch|). You can type: *:s_c* 717 'y' to substitute this match 718 'l' to substitute this match and then quit ("last") 719 'n' to skip this match 720 <Esc> to quit substituting 721 'a' to substitute this and all remaining matches 722 'q' to quit substituting 723 CTRL-E to scroll the screen up 724 CTRL-Y to scroll the screen down 725 If the 'edcompatible' option is on, Vim remembers the [c] flag and 726 toggles it each time you use it, but resets it when you give a new 727 search pattern. 728 729 *:s_e* 730 [e] When the search pattern fails, do not issue an error message and, in 731 particular, continue in maps as if no error occurred. This is most 732 useful to prevent the "No match" error from breaking a mapping. Vim 733 does not suppress the following error messages, however: 734 Regular expressions can't be delimited by letters 735 \ should be followed by /, ? or & 736 No previous substitute regular expression 737 Trailing characters 738 Interrupted 739 740 *:s_g* 741 [g] Replace all occurrences in the line. Without this argument, 742 replacement occurs only for the first occurrence in each line. If 743 the 'edcompatible' option is on, Vim remembers this flag and toggles 744 it each time you use it, but resets it when you give a new search 745 pattern. If the 'gdefault' option is on, this flag is on by default 746 and the [g] argument switches it off. 747 748 *:s_i* 749 [i] Ignore case for the pattern. The 'ignorecase' and 'smartcase' options 750 are not used. 751 752 *:s_I* 753 [I] Don't ignore case for the pattern. The 'ignorecase' and 'smartcase' 754 options are not used. 755 756 *:s_n* 757 [n] Report the number of matches, do not actually substitute. The [c] 758 flag is ignored. The matches are reported as if 'report' is zero. 759 Useful to |count-items|. 760 If \= |sub-replace-expression| is used, the expression will be 761 evaluated in the |sandbox| at every match. 762 763 [p] Print the line containing the last substitute. *:s_p* 764 765 [#] Like [p] and prepend the line number. *:s_#* 766 767 [l] Like [p] but print the text like |:list|. *:s_l* 768 769 *:s_r* 770 [r] Only useful in combination with `:&` or `:s` without arguments. `:&r` 771 works the same way as `:~`: When the search pattern is empty, use the 772 previously used search pattern instead of the search pattern from the 773 last substitute or `:global`. If the last command that did a search 774 was a substitute or `:global`, there is no effect. If the last 775 command was a search command such as "/", use the pattern from that 776 command. 777 For `:s` with an argument this already happens: > 778 :s/blue/red/ 779 /green 780 :s//red/ or :~ or :&r 781 < The last commands will replace "green" with "red". > 782 :s/blue/red/ 783 /green 784 :& 785 < The last command will replace "blue" with "red". 786 787 Note that there is no flag to change the "magicness" of the pattern. A 788 different command is used instead, or you can use |/\v| and friends. The 789 reason is that the flags can only be found by skipping the pattern, and in 790 order to skip the pattern the "magicness" must be known. Catch 22! 791 792 If the {pattern} for the substitute command is empty, the command uses the 793 pattern from the last substitute or `:global` command. If there is none, but 794 there is a previous search pattern, that one is used. With the [r] flag, the 795 command uses the pattern from the last substitute, `:global`, or search 796 command. 797 798 If the {string} is omitted the substitute is done as if it's empty. Thus the 799 matched pattern is deleted. The separator after {pattern} can also be left 800 out then. Example: > 801 :%s/TESTING 802 This deletes "TESTING" from all lines, but only one per line. 803 804 If [flags] are omitted the separator after {string} may also be left out. 805 806 *E1270* 807 For compatibility with Vi these two exceptions are allowed in legacy Vim 808 script: 809 "\/{string}/" and "\?{string}?" do the same as "//{string}/r". 810 "\&{string}&" does the same as "//{string}/". 811 *pattern-delimiter* *E146* *E1241* *E1242* 812 Instead of the '/' which surrounds the pattern and replacement string, you can 813 use another single-byte character. This is useful if you want to include a 814 '/' in the search pattern or replacement string. Example: > 815 :s+/+//+ 816 817 You can use most characters, but not an alphanumeric character, '\', '"' or 818 '|'. In Vim9 script you should not use '#' because it may be recognized as 819 the start of a comment. 820 821 The closing delimiter is optional for both the pattern and the replacement 822 string, if nothing follows. These then terminate at <EOL>. 823 824 For the definition of a pattern, see |pattern|. In Visual block mode, use 825 |/\%V| in the pattern to have the substitute work in the block only. 826 Otherwise it works on whole lines anyway. 827 828 *sub-replace-special* *:s\=* 829 When the {string} starts with "\=" it is evaluated as an expression, see 830 |sub-replace-expression|. You can use that for complex replacement or special 831 characters. 832 833 The substitution is limited in recursion to 4 levels. *E1290* 834 835 Otherwise these characters in {string} have a special meaning: 836 *:s%* 837 When {string} is equal to "%" and '/' is included with the 'cpoptions' option, 838 then the {string} of the previous substitute command is used, see |cpo-/| 839 840 magic nomagic action ~ 841 & \& replaced with the whole matched pattern *s/\&* 842 \& & replaced with & 843 \0 replaced with the whole matched pattern *\0* *s/\0* 844 \1 replaced with the matched pattern in the first 845 pair of () *s/\1* 846 \2 replaced with the matched pattern in the second 847 pair of () *s/\2* 848 .. .. *s/\3* 849 \9 replaced with the matched pattern in the ninth 850 pair of () *s/\9* 851 ~ \~ replaced with the {string} of the previous 852 substitute *s~* 853 \~ ~ replaced with ~ *s/\~* 854 \u next character made uppercase *s/\u* 855 \U following characters made uppercase, until \E *s/\U* 856 \l next character made lowercase *s/\l* 857 \L following characters made lowercase, until \E *s/\L* 858 \e end of \u, \U, \l and \L (NOTE: not <Esc>!) *s/\e* 859 \E end of \u, \U, \l and \L *s/\E* 860 <CR> split line in two at this point 861 (Type the <CR> as CTRL-V <Enter>) *s<CR>* 862 \r idem *s/\r* 863 \<CR> insert a carriage-return (CTRL-M) 864 (Type the <CR> as CTRL-V <Enter>) *s/\<CR>* 865 \n insert a <NL> (<NUL> in the file) 866 (does NOT break the line) *s/\n* 867 \b insert a <BS> *s/\b* 868 \t insert a <Tab> *s/\t* 869 \\ insert a single backslash *s/\\* 870 \x where x is any character not mentioned above: 871 Reserved for future expansion 872 873 The special meaning is also used inside the third argument {sub} of 874 the |substitute()| function with the following exceptions: 875 - A % inserts a percent literally without regard to 'cpoptions'. 876 - magic is always set without regard to 'magic'. 877 - A ~ inserts a tilde literally. 878 - <CR> and \r inserts a carriage-return (CTRL-M). 879 - \<CR> does not have a special meaning. It's just one of \x. 880 881 Examples: > 882 :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx" 883 :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb" 884 :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines) 885 :s/$/\^M/ modifies "abcde" to "abcde^M" 886 :s/\w\+/\u\0/g modifies "bla bla" to "Bla Bla" 887 :s/\w\+/\L\u\0/g modifies "BLA bla" to "Bla Bla" 888 889 Note: "\L\u" can be used to capitalize the first letter of a word. This is 890 not compatible with Vi and older versions of Vim, where the "\u" would cancel 891 out the "\L". Same for "\U\l". 892 893 Note: In previous versions CTRL-V was handled in a special way. Since this is 894 not Vi compatible, this was removed. Use a backslash instead. 895 896 command text result ~ 897 :s/aa/a^Ma/ aa a<line-break>a 898 :s/aa/a\^Ma/ aa a^Ma 899 :s/aa/a\\^Ma/ aa a\<line-break>a 900 901 (you need to type CTRL-V <CR> to get a ^M here) 902 903 The numbering of "\1", "\2" etc. is done based on which "\(" comes first in 904 the pattern (going left to right). When a parentheses group matches several 905 times, the last one will be used for "\1", "\2", etc. Example: > 906 :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x" 907 The "\2" is for "\(a[a-d] \)". At first it matches "aa ", secondly "ab ". 908 909 When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\), 910 either the first or second pattern in parentheses did not match, so either 911 \1 or \2 is empty. Example: > 912 :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x" 913 < 914 915 *:sc* *:sce* *:scg* *:sci* *:scI* *:scl* *:scp* *:sg* *:sgc* 916 *:sge* *:sgi* *:sgI* *:sgl* *:sgn* *:sgp* *:sgr* *:sI* *:si* 917 *:sic* *:sIc* *:sie* *:sIe* *:sIg* *:sIl* *:sin* *:sIn* *:sIp* 918 *:sip* *:sIr* *:sir* *:sr* *:src* *:srg* *:sri* *:srI* *:srl* 919 *:srn* *:srp* *:substitute-repeat* 920 2-letter and 3-letter :substitute commands ~ 921 922 These commands repeat the previous `:substitute` command with the given flags. 923 The first letter is always "s", followed by one or two of the possible flag 924 characters. For example ":sce" works like ":s ce". The table lists the 925 possible combinations, not all flags are possible, because the command is 926 short for another command. 927 928 List of :substitute commands 929 | c e g i I n p l r 930 | c :sc :sce :scg :sci :scI :scn :scp :scl 931 | e 932 | g :sgc :sge :sg :sgi :sgI :sgn :sgp :sgl :sgr 933 | i :sic :sie :si :siI :sin :sip :sir 934 | I :sIc :sIe :sIg :sIi :sI :sIn :sIp :sIl :sIr 935 | n 936 | p 937 | l 938 | r :src :srg :sri :srI :srn :srp :srl :sr 939 940 Exceptions: 941 :scr is `:scriptnames` 942 :se is `:set` 943 :sig is `:sign` 944 :sil is `:silent` 945 :sn is `:snext` 946 :sp is `:split` 947 :sl is `:sleep` 948 :sre is `:srewind` 949 950 951 Substitute with an expression *sub-replace-expression* 952 *sub-replace-\=* *s/\=* 953 When the substitute string starts with "\=" the remainder is interpreted as an 954 expression. 955 956 The special meaning for characters as mentioned at |sub-replace-special| does 957 not apply except for "<CR>". A <NL> character is used as a line break, you 958 can get one with a double-quote string: "\n". Prepend a backslash to get a 959 real <NL> character (which will be a NUL in the file). 960 961 The "\=" notation can also be used inside the third argument {sub} of 962 |substitute()| function. In this case, the special meaning for characters as 963 mentioned at |sub-replace-special| does not apply at all. Especially, <CR> and 964 <NL> are interpreted not as a line break but as a carriage-return and a 965 new-line respectively. 966 967 When the result is a |List| then the items are joined with separating line 968 breaks. Thus each item becomes a line, except that they can contain line 969 breaks themselves. 970 971 The |submatch()| function can be used to obtain matched text. The whole 972 matched text can be accessed with "submatch(0)". The text matched with the 973 first pair of () with "submatch(1)". Likewise for further sub-matches in (). 974 975 Be careful: The separation character must not appear in the expression! 976 Consider using a character like "@" or ":". There is no problem if the result 977 of the expression contains the separation character. 978 979 Examples: > 980 :s@\n@\="\r" .. expand("$HOME") .. "\r"@ 981 This replaces an end-of-line with a new line containing the value of $HOME. > 982 983 s/E/\="\<Char-0x20ac>"/g 984 This replaces each 'E' character with a euro sign. Read more in |<Char->|. 985 986 987 4.3 Search and replace *search-replace* 988 989 *:pro* *:promptfind* 990 :promptf[ind] [string] 991 Put up a Search dialog. When [string] is given, it is 992 used as the initial search string. 993 {only for Win32, Motif and GTK GUI} 994 995 *:promptr* *:promptrepl* 996 :promptr[epl] [string] 997 Put up a Search/Replace dialog. When [string] is 998 given, it is used as the initial search string. 999 {only for Win32, Motif and GTK GUI} 1000 1001 1002 4.4 Changing tabs *change-tabs* 1003 *:ret* *:retab* *:retab!* 1004 :[range]ret[ab][!] [-indentonly] [{new-tabstop}] 1005 Replace all sequences of white-space containing a 1006 <Tab> with new strings of white-space using 1007 {new-tabstop}. If you do not specify {new-tabstop} or 1008 it is zero, Vim uses the current value of 'tabstop'. 1009 The current value of 'tabstop' is always used to 1010 compute the width of existing tabs. 1011 With !, Vim also replaces strings of only normal 1012 spaces with tabs where appropriate. 1013 With 'expandtab' on, Vim replaces all tabs with the 1014 appropriate number of spaces. 1015 This command sets 'tabstop' to {new-tabstop} and if 1016 performed on the whole file, which is default, should 1017 not make any visible change. 1018 1019 When [-indentonly] is specified, only the leading 1020 white-space will be targeted. Any other consecutive 1021 white-space will not be changed. 1022 1023 Warning: This command modifies any <Tab> characters 1024 inside of strings in a C program. Use "\t" to avoid 1025 this (that's a good habit anyway). 1026 `:retab!` may also change a sequence of spaces by 1027 <Tab> characters, which can mess up a printf(). 1028 If the |+vartabs| feature is enabled then a list of 1029 tab widths separated by commas may be used in place of 1030 a single tabstop. Each value in the list represents 1031 the width of one tabstop, except the final value which 1032 applies to all following tabstops. 1033 1034 *retab-example* 1035 Example for using autocommands and ":retab" to edit a file which is stored 1036 with tabstops at 8 but edited with tabstops set at 4. Warning: white space 1037 inside of strings can change! Also see 'softtabstop' option. > 1038 1039 :auto BufReadPost *.xx retab! 4 1040 :auto BufWritePre *.xx retab! 8 1041 :auto BufWritePost *.xx retab! 4 1042 :auto BufNewFile *.xx set ts=4 1043 1044 ============================================================================== 1045 5. Copying and moving text *copy-move* 1046 1047 *quote* 1048 "{register} Use {register} for next delete, yank or put. Use 1049 an uppercase character to append with delete and yank. 1050 Registers ".", "%", "#" and ":" only work with put. 1051 1052 *:reg* *:registers* 1053 :reg[isters] Display the type and contents of all numbered and 1054 named registers. If a register is written to for 1055 |:redir| it will not be listed. 1056 Type can be one of: 1057 "c" for |characterwise| text 1058 "l" for |linewise| text 1059 "b" for |blockwise-visual| text 1060 1061 1062 :reg[isters] {arg} Display the contents of the numbered and named 1063 registers that are mentioned in {arg}. For example: > 1064 :reg 1a 1065 < to display registers '1' and 'a'. Spaces are allowed 1066 in {arg}. 1067 1068 *:di* *:dis* *:display* 1069 :di[splay] [arg] Same as :registers. 1070 1071 *y* *yank* 1072 ["x]y{motion} Yank {motion} text [into register x]. When no 1073 characters are to be yanked (e.g., "y0" in column 1), 1074 this is an error when 'cpoptions' includes the 'E' 1075 flag. 1076 1077 *yy* 1078 ["x]yy Yank [count] lines [into register x] |linewise|. 1079 1080 *Y* 1081 ["x]Y yank [count] lines [into register x] (synonym for 1082 yy, |linewise|). If you like "Y" to work from the 1083 cursor to the end of line (which is more logical, 1084 but not Vi-compatible) use ":map Y y$". 1085 1086 *zy* 1087 ["x]zy{motion} Yank {motion} text [into register x]. Only differs 1088 from `y` when selecting a block of text, see |v_zy|. 1089 1090 *v_y* 1091 {Visual}["x]y Yank the highlighted text [into register x] (for 1092 {Visual} see |Visual-mode|). 1093 1094 *v_Y* 1095 {Visual}["x]Y Yank the highlighted lines [into register x] (for 1096 {Visual} see |Visual-mode|). 1097 1098 *v_zy* 1099 {Visual}["x]zy Yank the highlighted text [into register x]. Trailing 1100 whitespace at the end of each line of a selected block 1101 won't be yanked. Especially useful in combination 1102 with `zp`. (for {Visual} see |Visual-mode|) 1103 1104 *:y* *:yank* *E850* 1105 :[range]y[ank] [x] Yank [range] lines [into register x]. Yanking to the 1106 "* or "+ registers is possible only when the 1107 |+clipboard| or |+clipboard_provider| features are 1108 included. 1109 1110 :[range]y[ank] [x] {count} 1111 Yank {count} lines, starting with last line number 1112 in [range] (default: current line |cmdline-ranges|), 1113 [into register x]. 1114 1115 *p* *put* *E353* *E1240* 1116 ["x]p Put the text [from register x] after the cursor 1117 [count] times. 1118 1119 *P* 1120 ["x]P Put the text [from register x] before the cursor 1121 [count] times. 1122 1123 *<MiddleMouse>* 1124 ["x]<MiddleMouse> Put the text from a register before the cursor [count] 1125 times. Uses the "* register, unless another is 1126 specified. 1127 Leaves the cursor at the end of the new text. 1128 Using the mouse only works when 'mouse' contains 'n' 1129 or 'a'. 1130 If you have a scrollwheel and often accidentally paste 1131 text, you can use these mappings to disable the 1132 pasting with the middle mouse button: > 1133 :map <MiddleMouse> <Nop> 1134 :imap <MiddleMouse> <Nop> 1135 < You might want to disable the multi-click versions 1136 too, see |double-click|. 1137 1138 *gp* 1139 ["x]gp Just like "p", but leave the cursor just after the new 1140 text. 1141 1142 *gP* 1143 ["x]gP Just like "P", but leave the cursor just after the new 1144 text. 1145 1146 *:pu* *:put* 1147 :[line]pu[t] [x] Put the text [from register x] after [line] (default 1148 current line). This always works |linewise|, thus 1149 this command can be used to put a yanked block as new 1150 lines. 1151 If no register is specified, it depends on the 1152 'clipboard' option: If 'clipboard' contains 1153 "unnamedplus", paste from the + register |quoteplus|. 1154 Otherwise, if 'clipboard' contains "unnamed", paste 1155 from the * register |quotestar|. Otherwise, paste from 1156 the unnamed register |quote_quote|. 1157 The register can also be '=' followed by an optional 1158 expression. The expression continues until the end of 1159 the command. You need to escape the '|' and '"' 1160 characters to prevent them from terminating the 1161 command. Example: > 1162 :put ='path' .. \",/test\" 1163 < If there is no expression after '=', Vim uses the 1164 previous expression. You can see it with ":dis =". 1165 1166 :[line]pu[t]! [x] Put the text [from register x] before [line] (default 1167 current line). 1168 1169 *:ip* *:iput* 1170 :[line]ip[ut] [x] Like |:put|, but adjust indent to the current line. 1171 1172 :[line]ip[ut]! [x] Like |:put|!, but adjust indent to the current line. 1173 1174 ["x]]p or *]p* *]<MiddleMouse>* 1175 ["x]]<MiddleMouse> Like "p", but adjust the indent to the current line. 1176 Using the mouse only works when 'mouse' contains 'n' 1177 or 'a'. 1178 1179 ["x][P or *[P* 1180 ["x]]P or *]P* 1181 ["x][p or *[p* *[<MiddleMouse>* 1182 ["x][<MiddleMouse> Like "P", but adjust the indent to the current line. 1183 Using the mouse only works when 'mouse' contains 'n' 1184 or 'a'. 1185 1186 ["x]zp or *zp* *zP* 1187 ["x]zP Like "p" and "P", except without adding trailing 1188 spaces when pasting a block. Thus the inserted text 1189 will not always be a rectangle. Especially useful in 1190 combination with |v_zy|. 1191 1192 You can use these commands to copy text from one place to another. Do this 1193 by first getting the text into a register with a yank, delete or change 1194 command, then inserting the register contents with a put command. You can 1195 also use these commands to move text from one file to another, because Vim 1196 preserves all registers when changing buffers (the CTRL-^ command is a quick 1197 way to toggle between two files). 1198 1199 *linewise-register* *characterwise-register* 1200 You can repeat the put commands with "." (except for :put) and undo them. If 1201 the command that was used to get the text into the register was |linewise|, 1202 Vim inserts the text below ("p") or above ("P") the line where the cursor is. 1203 Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With 1204 the ":put" command, Vim always inserts the text in the next line. You can 1205 exchange two characters with the command sequence "xp". You can exchange two 1206 lines with the command sequence "ddp". You can exchange two words with the 1207 command sequence "deep" (start with the cursor in the blank space before the 1208 first word). You can use the |']| or |`]| command after the put command to 1209 move the cursor to the end of the inserted text, or use |'[| or |`[| to move 1210 the cursor to the start. 1211 1212 *put-Visual-mode* *v_p* *v_P* 1213 When using a put command like |p| or |P| in Visual mode, Vim will try to 1214 replace the selected text with the contents of the register. Whether this 1215 works well depends on the type of selection and the type of the text in the 1216 register. With blockwise selection it also depends on the size of the block 1217 and whether the corners are on an existing character. (Implementation detail: 1218 it actually works by first putting the register after the selection and then 1219 deleting the selection.) 1220 With |p| the previously selected text is put in the unnamed register (and 1221 possibly the selection and/or clipboard). This is useful if you want to put 1222 that text somewhere else. But you cannot repeat the same change. 1223 With |P| the unnamed register is not changed (and neither the selection or 1224 clipboard), you can repeat the same change. But the deleted text cannot be 1225 used. If you do need it you can use |p| with another register. E.g., yank 1226 the text to copy, Visually select the text to replace and use "0p . You can 1227 repeat this as many times as you like, and the unnamed register will be 1228 changed each time. 1229 *blockwise-put* 1230 When a register contains text from one line (characterwise), using a 1231 blockwise Visual selection, putting that register will paste that text 1232 repeatedly in each of the selected lines, thus replacing the blockwise 1233 selected region by multiple copies of the register text. For example: 1234 - yank the word "TEXT" into a register with `yw` 1235 - select a visual block, marked with "v" in this text: 1236 aaavvaaa 1237 bbbvvbbb 1238 cccvvccc 1239 - press `p`, results in: 1240 aaaTEXTaaa 1241 bbbTEXTbbb 1242 cccTEXTccc 1243 1244 *blockwise-register* 1245 If you use a blockwise Visual mode command to get the text into the register, 1246 the block of text will be inserted before ("P") or after ("p") the cursor 1247 column in the current and next lines. Vim makes the whole block of text start 1248 in the same column. Thus the inserted text looks the same as when it was 1249 yanked or deleted. Vim may replace some <Tab> characters with spaces to make 1250 this happen. However, if the width of the block is not a multiple of a <Tab> 1251 width and the text after the inserted block contains <Tab>s, that text may be 1252 misaligned. 1253 1254 Use |zP|/|zp| to paste a blockwise yanked register without appending trailing 1255 spaces. 1256 1257 Note that after a characterwise yank command, Vim leaves the cursor on the 1258 first yanked character that is closest to the start of the buffer. This means 1259 that "yl" doesn't move the cursor, but "yh" moves the cursor one character 1260 left. 1261 Rationale: In Vi the "y" command followed by a backwards motion would 1262 sometimes not move the cursor to the first yanked character, 1263 because redisplaying was skipped. In Vim it always moves to 1264 the first character, as specified by Posix. 1265 With a linewise yank command the cursor is put in the first line, but the 1266 column is unmodified, thus it may not be on the first yanked character. 1267 1268 There are ten types of registers: *registers* *{register}* *E354* 1269 1. The unnamed register "" 1270 2. 10 numbered registers "0 to "9 1271 3. The small delete register "- 1272 4. 26 named registers "a to "z or "A to "Z 1273 5. Three read-only registers ":, "., "% 1274 6. Alternate buffer register "# 1275 7. The expression register "= 1276 8. The selection and drop registers "*, "+ and "~ 1277 9. The black hole register "_ 1278 10. Last search pattern register "/ 1279 1280 1. Unnamed register "" *quote_quote* *quotequote* 1281 Vim fills this register with text deleted with the "d", "c", "s", "x" commands 1282 or copied with the yank "y" command, regardless of whether or not a specific 1283 register was used (e.g. "xdd). This is like the unnamed register is pointing 1284 to the last used register. Thus when appending using an uppercase register 1285 name, the unnamed register contains the same text as the named register. 1286 An exception is the '_' register: "_dd does not store the deleted text in any 1287 register. 1288 Vim uses the contents of the unnamed register for any put command (p or P) 1289 which does not specify a register. Additionally you can access it with the 1290 name '"'. This means you have to type two double quotes. Writing to the "" 1291 register writes to register "0. 1292 {Vi: register contents are lost when changing files, no '"'} 1293 1294 2. Numbered registers "0 to "9 *quote_number* *quote0* *quote1* 1295 *quote2* *quote3* *quote4* *quote9* 1296 Vim fills these registers with text from yank and delete commands. 1297 Numbered register 0 contains the text from the most recent yank command, 1298 unless the command specified another register with ["x]. 1299 Numbered register 1 contains the text deleted by the most recent delete or 1300 change command (even when the command specified another register), unless the 1301 text is less than one line (the small delete register is used then). An 1302 exception is made for the delete operator with these movement commands: |%|, 1303 |(|, |)|, |`|, |/|, |?|, |n|, |N|, |{| and |}|. 1304 Register "1 is always used then (this is Vi compatible). The "- register is 1305 used as well if the delete is within a line. Note that these characters may 1306 be mapped. E.g. |%| is mapped by the matchit plugin. 1307 With each successive deletion or change, Vim shifts the previous contents 1308 of register 1 into register 2, 2 into 3, and so forth, losing the previous 1309 contents of register 9. 1310 {Vi: register 0 does not exist} 1311 1312 3. Small delete register "- *quote_-* *quote-* 1313 This register contains text from commands that delete less than one line, 1314 except when the command specifies a register with ["x]. 1315 1316 4. Named registers "a to "z or "A to "Z *quote_alpha* *quotea* 1317 Vim fills these registers only when you say so. Specify them as lowercase 1318 letters to replace their previous contents or as uppercase letters to append 1319 to their previous contents. When the '>' flag is present in 'cpoptions' then 1320 a line break is inserted before the appended text. 1321 1322 5. Read-only registers ":, ". and "% 1323 These are '%', ':' and '.'. You can use them only with the "p", "P", 1324 and ":put" commands and with CTRL-R. 1325 *quote_.* *quote.* *E29* 1326 ". Contains the last inserted text (the same as what is inserted 1327 with the insert mode commands CTRL-A and CTRL-@). Note: this 1328 doesn't work with CTRL-R on the command-line. It works a bit 1329 differently, like inserting the text instead of putting it 1330 ('textwidth' and other options affect what is inserted). 1331 *quote_%* *quote%* 1332 "% Contains the name of the current file. 1333 *quote_:* *quote:* *E30* 1334 ": Contains the most recent executed command-line. Example: Use 1335 "@:" to repeat the previous command-line command. 1336 The command-line is only stored in this register when at least 1337 one character of it was typed. Thus it remains unchanged if 1338 the command was executed completely from a mapping. 1339 {not available when compiled without the |+cmdline_hist| 1340 feature} 1341 1342 6. Alternate file register "# *quote_#* *quote#* *@#* 1343 Contains the |alternate-file| name for current window. 1344 This register is writable with `:let` and |setreg()|. This changes which 1345 buffer CTRL-^ enters. You can't yank or delete into this register. 1346 A String is matched against existing buffer names, like |:buffer|: > 1347 let @# = 'buffer_name' 1348 Also supports using buffer number and |file-pattern|. 1349 1350 Throws 1351 |E86| when the buffer number does not exist 1352 |E93| when more than one buffer matches 1353 |E94| when none match 1354 1355 Clear the register with empty String: > 1356 let @# = '' 1357 1358 7. Expression register "= *quote_=* *quote=* *@=* 1359 This is not really a register that stores text, but is a way to use an 1360 expression in commands which use a register. The expression register is 1361 read-write. 1362 1363 When typing the '=' after " or CTRL-R the cursor moves to the command-line, 1364 where you can enter any expression (see |expression|). All normal 1365 command-line editing commands are available, including a special history for 1366 expressions. When you end the command-line by typing <CR>, Vim computes the 1367 result of the expression. If you end it with <Esc>, Vim abandons the 1368 expression. If you do not enter an expression, Vim uses the previous 1369 expression (like with the "/" command). 1370 1371 The expression must evaluate to a String. A Number is always automatically 1372 converted to a String. For the "p" and ":put" command, if the result is a 1373 Float it's converted into a String. If the result is a List each element is 1374 turned into a String and used as a line. A Dictionary is converted into a 1375 String. A Funcref results in an error message (use string() to convert). 1376 1377 If the "= register is used for the "p" command, the String is split up at <NL> 1378 characters. If the String ends in a <NL>, it is regarded as a linewise 1379 register. 1380 1381 8. Selection and drop registers "*, "+ and "~ 1382 Use these registers for storing and retrieving the selected text for the GUI. 1383 See |quotestar| and |quoteplus|. When the clipboard is not available or not 1384 working, the unnamed register is used instead. For Unix systems the clipboard 1385 is only available when the |+xterm_clipboard| feature is present. 1386 1387 Note that there is only a distinction between "* and "+ for X11 systems. For 1388 an explanation of the difference, see |x11-selection|. Under MS-Windows, use 1389 of "* and "+ is actually synonymous and refers to the |gui-clipboard|. 1390 1391 *quote_~* *quote~* *<Drop>* 1392 The read-only "~ register stores the dropped text from the last drag'n'drop 1393 operation. When something has been dropped onto Vim, the "~ register is 1394 filled in and the <Drop> pseudo key is sent for notification. You can remap 1395 this key if you want; the default action (for all modes) is to insert the 1396 contents of the "~ register at the cursor position. 1397 {only available when compiled with the |+dnd| feature, currently only with the 1398 GTK GUI} 1399 1400 Note: The "~ register is only used when dropping plain text onto Vim. 1401 Drag'n'drop of URI lists is handled internally. 1402 1403 9. Black hole register "_ *quote_* 1404 When writing to this register, nothing happens. This can be used to delete 1405 text without affecting the normal registers. When reading from this register, 1406 nothing is returned. 1407 1408 10. Last search pattern register "/ *quote_/* *quote/* 1409 Contains the most recent search-pattern. This is used for "n" and 'hlsearch'. 1410 This register is writable with `:let` and |setreg()|. You can change it to have 1411 'hlsearch' highlight other matches without actually searching. You can't yank 1412 or delete into this register. The search direction is available in 1413 |v:searchforward|. 1414 Note that the value is restored when returning from a function 1415 |function-search-undo|. 1416 1417 *@/* 1418 You can write to a register with a `:let` command |:let-@|. Example: > 1419 :let @/ = "the" 1420 1421 If you use a put command without specifying a register, Vim uses the register 1422 that was last filled (this is also the contents of the unnamed register). If 1423 you are confused, use the `:dis` command to find out what Vim will put (this 1424 command displays all named and numbered registers; the unnamed register is 1425 labelled '"'). 1426 1427 The next three commands always work on whole lines. 1428 1429 :[range]co[py] {address} *:co* *:copy* 1430 Copy the lines given by [range] to below the line 1431 given by {address}. 1432 1433 *:t* 1434 :t Synonym for copy. 1435 This command is not supported in |Vim9| script, 1436 because it is too easily confused with a variable 1437 name. 1438 1439 :[range]m[ove] {address} *:m* *:mo* *:move* *E134* 1440 Move the lines given by [range] to below the line 1441 given by {address}. 1442 Any text properties in [range] are cleared. See 1443 |text-prop-cleared|. 1444 1445 ============================================================================== 1446 6. Formatting text *formatting* 1447 1448 :[range]ce[nter] [width] *:ce* *:center* 1449 Center lines in [range] between [width] columns 1450 (default 'textwidth' or 80 when 'textwidth' is 0). 1451 1452 :[range]ri[ght] [width] *:ri* *:right* 1453 Right-align lines in [range] at [width] columns 1454 (default 'textwidth' or 80 when 'textwidth' is 0). 1455 1456 *:le* *:left* 1457 :[range]le[ft] [indent] 1458 Left-align lines in [range]. Sets the indent in the 1459 lines to [indent] (default 0). 1460 1461 *gq* 1462 gq{motion} Format the lines that {motion} moves over. 1463 Formatting is done with one of three methods: 1464 1. If 'formatexpr' is not empty the expression is 1465 evaluated. This can differ for each buffer. 1466 2. If 'formatprg' is not empty an external program 1467 is used. 1468 3. Otherwise formatting is done internally. 1469 1470 In the third case the 'textwidth' option controls the 1471 length of each formatted line (see below). 1472 If the 'textwidth' option is 0, the formatted line 1473 length is the screen width (with a maximum width of 1474 79). 1475 The 'formatoptions' option controls the type of 1476 formatting |fo-table|. 1477 The cursor is left on the first non-blank of the last 1478 formatted line. 1479 NOTE: The "Q" command formerly performed this 1480 function. If you still want to use "Q" for 1481 formatting, use this mapping: > 1482 :nnoremap Q gq 1483 1484 gqgq *gqgq* *gqq* 1485 gqq Format the current line. With a count format that 1486 many lines. 1487 1488 *v_gq* 1489 {Visual}gq Format the highlighted text. (for {Visual} see 1490 |Visual-mode|). 1491 1492 *gw* 1493 gw{motion} Format the lines that {motion} moves over. Similar to 1494 |gq| but puts the cursor back at the same position in 1495 the text. However, 'formatprg' and 'formatexpr' are 1496 not used. 1497 1498 gwgw *gwgw* *gww* 1499 gww Format the current line as with "gw". 1500 1501 *v_gw* 1502 {Visual}gw Format the highlighted text as with "gw". (for 1503 {Visual} see |Visual-mode|). 1504 1505 Example: To format the current paragraph use: *gqap* > 1506 gqap 1507 1508 The "gq" command leaves the cursor in the line where the motion command takes 1509 the cursor. This allows you to repeat formatting repeated with ".". This 1510 works well with "gqj" (format current and next line) and "gq}" (format until 1511 end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on 1512 the first formatted line (as with using a filter command). 1513 1514 If you want to format the current paragraph and continue where you were, use: > 1515 gwap 1516 If you always want to keep paragraphs formatted you may want to add the 'a' 1517 flag to 'formatoptions'. See |auto-format|. 1518 1519 If the 'autoindent' option is on, Vim uses the indent of the first line for 1520 the following lines. 1521 1522 Formatting does not change empty lines (but it does change lines with only 1523 white space!). 1524 1525 The 'joinspaces' option is used when lines are joined together. 1526 1527 You can set the 'formatexpr' option to an expression or the 'formatprg' option 1528 to the name of an external program for Vim to use for text formatting. The 1529 'textwidth' and other options have no effect on formatting by an external 1530 program. 1531 1532 *format-formatexpr* 1533 The 'formatexpr' option can be set to a Vim script function that performs 1534 reformatting of the buffer. This should usually happen in an |ftplugin|, 1535 since formatting is highly dependent on the type of file. It makes 1536 sense to use an |autoload| script, so the corresponding script is only loaded 1537 when actually needed and the script should be called <filetype>format.vim. 1538 1539 For example, the XML filetype plugin distributed with Vim in the 1540 $VIMRUNTIME/ftplugin directory, sets the 'formatexpr' option to: > 1541 1542 setlocal formatexpr=xmlformat#Format() 1543 1544 That means, you will find the corresponding script, defining the 1545 xmlformat#Format() function, in the file `$VIMRUNTIME/autoload/xmlformat.vim` 1546 1547 Here is an example script that removes trailing whitespace from the selected 1548 text. Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim: 1549 >vim 1550 func! format#Format() 1551 " only reformat on explicit gq command 1552 if mode() != 'n' 1553 " fall back to Vim's internal reformatting 1554 return 1 1555 endif 1556 let lines = getline(v:lnum, v:lnum + v:count - 1) 1557 call map(lines, {key, val -> substitute(val, '\s\+$', '', 'g')}) 1558 call setline('.', lines) 1559 1560 " do not run internal formatter! 1561 return 0 1562 endfunc 1563 1564 You can then enable the formatting by executing: > 1565 setlocal formatexpr=format#Format() 1566 1567 Note: this function explicitly returns non-zero when called from insert mode 1568 (which basically means, text is inserted beyond the 'textwidth' limit). This 1569 causes Vim to fall back to reformat the text by using the internal formatter. 1570 1571 However, if the |gq| command is used to reformat the text, the function 1572 will receive the selected lines, trim trailing whitespace from those lines and 1573 put them back in place. If you are going to split single lines into multiple 1574 lines, be careful not to overwrite anything. 1575 1576 If you want to allow reformatting of text from insert or replace mode, one has 1577 to be very careful, because the function might be called recursively. For 1578 debugging it helps to set the 'debug' option. 1579 1580 *right-justify* 1581 There is no command in Vim to right justify text. You can do it with 1582 an external command, like "par" (e.g.: `:.,}!par` to format until the end of the 1583 paragraph) or set 'formatprg' to "par". 1584 1585 *format-comments* 1586 An overview of comment formatting is in section |30.6| of the user manual. 1587 1588 Vim can automatically insert and format comments in a special way. Vim 1589 recognizes a comment by a specific string at the start of the line (ignoring 1590 white space). Three types of comments can be used: 1591 1592 - A comment string that repeats at the start of each line. An example is the 1593 type of comment used in shell scripts, starting with "#". 1594 - A comment string that occurs only in the first line, not in the following 1595 lines. An example is this list with dashes. 1596 - Three-piece comments that have a start string, an end string, and optional 1597 lines in between. The strings for the start, middle and end are different. 1598 An example is the C style comment: 1599 /* 1600 * this is a C comment 1601 */ 1602 1603 The 'comments' option is a comma-separated list of parts. Each part defines a 1604 type of comment string. A part consists of: 1605 {flags}:{string} 1606 1607 {string} is the literal text that must appear. 1608 1609 {flags}: 1610 n Nested comment. Nesting with mixed parts is allowed. If 'comments' 1611 is "n:),n:>" a line starting with "> ) >" is a comment. 1612 1613 b Blank (<Space>, <Tab> or <EOL>) required after {string}. 1614 1615 f Only the first line has the comment string. Do not repeat comment on 1616 the next line, but preserve indentation (e.g., a bullet-list). 1617 1618 s Start of three-piece comment 1619 1620 m Middle of a three-piece comment 1621 1622 e End of a three-piece comment 1623 1624 l Left align. Used together with 's' or 'e', the leftmost character of 1625 start or end will line up with the leftmost character from the middle. 1626 This is the default and can be omitted. See below for more details. 1627 1628 r Right align. Same as above but rightmost instead of leftmost. See 1629 below for more details. 1630 1631 O Don't consider this comment for the "O" command. 1632 1633 x Allows three-piece comments to be ended by just typing the last 1634 character of the end-comment string as the first action on a new 1635 line when the middle-comment string has been inserted automatically. 1636 See below for more details. 1637 1638 {digits} 1639 When together with 's' or 'e': add {digit} amount of offset to an 1640 automatically inserted middle or end comment leader. The offset 1641 begins from a left alignment. See below for more details. 1642 1643 -{digits} 1644 Like {digits} but reduce the indent. This only works when there is 1645 some indent for the start or end part that can be removed. 1646 1647 When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the 1648 comment string repeats at the start of each line. The {flags} field may be 1649 empty. 1650 1651 Any blank space in the text before and after the {string} is part of the 1652 {string}, so do not include leading or trailing blanks unless the blanks are a 1653 required part of the comment string. 1654 1655 When one comment leader is part of another, specify the part after the whole. 1656 For example, to include both "-" and "->", use > 1657 :set comments=f:->,f:- 1658 1659 A three-piece comment must always be given as start,middle,end, with no other 1660 parts in between. An example of a three-piece comment is > 1661 sr:/*,mb:*,ex:*/ 1662 for C-comments. To avoid recognizing "*ptr" as a comment, the middle string 1663 includes the 'b' flag. For three-piece comments, Vim checks the text after 1664 the start and middle strings for the end string. If Vim finds the end string, 1665 the comment does not continue on the next line. Three-piece comments must 1666 have a middle string because otherwise Vim can't recognize the middle lines. 1667 1668 Notice the use of the "x" flag in the above three-piece comment definition. 1669 When you hit Return in a C-comment, Vim will insert the middle comment leader 1670 for the new line: " * ". To close this comment you just have to type "/" 1671 before typing anything else on the new line. This will replace the 1672 middle-comment leader with the end-comment leader and apply any specified 1673 alignment, leaving just " */". There is no need to hit Backspace first. 1674 1675 When there is a match with a middle part, but there also is a matching end 1676 part which is longer, the end part is used. This makes a C style comment work 1677 without requiring the middle part to end with a space. 1678 1679 Here is an example of alignment flags at work to make a comment stand out 1680 (kind of looks like a 1 too). Consider comment string: > 1681 :set comments=sr:/***,m:**,ex-2:******/ 1682 < 1683 /*** ~ 1684 **<--right aligned from "r" flag ~ 1685 ** ~ 1686 offset 2 spaces for the "-2" flag--->** ~ 1687 ******/ ~ 1688 In this case, the first comment was typed, then return was pressed 4 times, 1689 then "/" was pressed to end the comment. 1690 1691 Here are some finer points of three part comments. There are three times when 1692 alignment and offset flags are taken into consideration: opening a new line 1693 after a start-comment, opening a new line before an end-comment, and 1694 automatically ending a three-piece comment. The end alignment flag has a 1695 backwards perspective; the result is that the same alignment flag used with 1696 "s" and "e" will result in the same indent for the starting and ending pieces. 1697 Only one alignment per comment part is meant to be used, but an offset number 1698 will override the "r" and "l" flag. 1699 1700 Enabling 'cindent' will override the alignment flags in many cases. 1701 Reindenting using a different method like |gq| or |=| will not consult 1702 alignment flags either. The same behaviour can be defined in those other 1703 formatting options. One consideration is that 'cindent' has additional 1704 options for context based indenting of comments but cannot replicate many 1705 three piece indent alignments. However, 'indentexpr' has the ability to work 1706 better with three piece comments. 1707 1708 Other examples: > 1709 "b:*" Includes lines starting with "*", but not if the "*" is 1710 followed by a non-blank. This avoids a pointer dereference 1711 like "*str" to be recognized as a comment. 1712 "n:>" Includes a line starting with ">", ">>", ">>>", etc. 1713 "fb:-" Format a list that starts with "- ". 1714 1715 By default, "b:#" is included. This means that a line that starts with 1716 "#include" is not recognized as a comment line. But a line that starts with 1717 "# define" is recognized. This is a compromise. 1718 1719 *fo-table* 1720 You can use the 'formatoptions' option to influence how Vim formats text. 1721 'formatoptions' is a string that can contain any of the letters below. The 1722 default setting is "tcq". You can separate the option letters with commas for 1723 readability. 1724 1725 letter meaning when present in 'formatoptions' ~ 1726 *fo-t* 1727 t Auto-wrap text using 'textwidth' 1728 *fo-c* 1729 c Auto-wrap comments using 'textwidth', inserting the current comment 1730 leader automatically. 1731 *fo-r* 1732 r Automatically insert the current comment leader after hitting 1733 <Enter> in Insert mode. 1734 *fo-o* 1735 o Automatically insert the current comment leader after hitting 'o' or 1736 'O' in Normal mode. In case comment is unwanted in a specific place 1737 use CTRL-U to quickly delete it. |i_CTRL-U| 1738 *fo-/* 1739 / When 'o' is included: do not insert the comment leader for a // 1740 comment after a statement, only when // is at the start of the line. 1741 *fo-q* 1742 q Allow formatting of comments with "gq". 1743 Note that formatting will not change blank lines or lines containing 1744 only the comment leader. A new paragraph starts after such a line, 1745 or when the comment leader changes. 1746 *fo-w* 1747 w Trailing white space indicates a paragraph continues in the next line. 1748 A line that ends in a non-white character ends a paragraph. 1749 *fo-a* 1750 a Automatic formatting of paragraphs. Every time text is inserted or 1751 deleted the paragraph will be reformatted. See |auto-format|. 1752 When the 'c' flag is present this only happens for recognized 1753 comments. 1754 *fo-n* 1755 n When formatting text, recognize numbered lists. This actually uses 1756 the 'formatlistpat' option, thus any kind of list can be used. The 1757 indent of the text after the number is used for the next line. The 1758 default is to find a number, optionally followed by '.', ':', ')', 1759 ']' or '}'. Note that 'autoindent' must be set too. Doesn't work 1760 well together with "2". 1761 Example: > 1762 1. the first item 1763 wraps 1764 2. the second item 1765 < *fo-2* 1766 2 When formatting text, use the indent of the second line of a paragraph 1767 for the rest of the paragraph, instead of the indent of the first 1768 line. This supports paragraphs in which the first line has a 1769 different indent than the rest. Note that 'autoindent' must be set 1770 too. Example: > 1771 first line of a paragraph 1772 second line of the same paragraph 1773 third line. 1774 < This also works inside comments, ignoring the comment leader. 1775 *fo-v* 1776 v Vi-compatible auto-wrapping in insert mode: Only break a line at a 1777 blank that you have entered during the current insert command. (Note: 1778 this is not 100% Vi compatible. Vi has some "unexpected features" or 1779 bugs in this area. It uses the screen column instead of the line 1780 column.) 1781 *fo-b* 1782 b Like 'v', but only auto-wrap if you enter a blank at or before 1783 the wrap margin. If the line was longer than 'textwidth' when you 1784 started the insert, or you do not enter a blank in the insert before 1785 reaching 'textwidth', Vim does not perform auto-wrapping. 1786 *fo-l* 1787 l Long lines are not broken in insert mode: When a line was longer than 1788 'textwidth' when the insert command started, Vim does not 1789 automatically format it. 1790 *fo-m* 1791 m Also break at a multibyte character above 255. This is useful for 1792 Asian text where every character is a word on its own. Note that 1793 line breaks may also be added after punctuation characters such as 1794 colons to match the CJK linebreaking rules. 1795 *fo-M* 1796 M When joining lines, don't insert a space before or after a multibyte 1797 character. Overrules the 'B' flag. 1798 *fo-B* 1799 B When joining lines, don't insert a space between two multibyte 1800 characters. Overruled by the 'M' flag. 1801 *fo-1* 1802 1 Don't break a line after a one-letter word. It's broken before it 1803 instead (if possible). 1804 *fo-]* 1805 ] Respect 'textwidth' rigorously. With this flag set, no line can be 1806 longer than 'textwidth', unless line-break-prohibition rules make this 1807 impossible. Mainly for CJK scripts and works only if 'encoding' is 1808 "utf-8". 1809 *fo-j* 1810 j Where it makes sense, remove a comment leader when joining lines. For 1811 example, joining: 1812 int i; // the index ~ 1813 // in the list ~ 1814 Becomes: 1815 int i; // the index in the list ~ 1816 *fo-p* 1817 p Don't break lines at single spaces that follow periods. This is 1818 intended to complement 'joinspaces' and |cpo-J|, for prose with 1819 sentences separated by two spaces. For example, with 'textwidth' set 1820 to 28: > 1821 Surely you're joking, Mr. Feynman! 1822 < Becomes: > 1823 Surely you're joking, 1824 Mr. Feynman! 1825 < Instead of: > 1826 Surely you're joking, Mr. 1827 Feynman! 1828 1829 1830 With 't' and 'c' you can specify when Vim performs auto-wrapping: 1831 value action ~ 1832 "" no automatic formatting (you can use "gq" for manual formatting) 1833 "t" automatic formatting of text, but not comments 1834 "c" automatic formatting for comments, but not text (good for C code) 1835 "tc" automatic formatting for text and comments 1836 1837 Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but 1838 does insert comment leaders according to the 'comments' option). An exception 1839 is when the 'a' flag is present. |auto-format| 1840 1841 Note that when 'paste' is on, Vim does no formatting at all. 1842 1843 Note that 'textwidth' can be non-zero even if Vim never performs 1844 auto-wrapping; 'textwidth' is still useful for formatting with "gq". 1845 1846 If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some 1847 built in stuff to treat these types of comments a bit more cleverly. 1848 Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in 1849 'formatoptions') gives the correct start of the line automatically. The same 1850 happens with formatting and auto-wrapping. Opening a line after a line 1851 starting with "/*" or "*" and containing "*/", will cause no comment leader to 1852 be inserted, and the indent of the new line is taken from the line containing 1853 the start of the comment. 1854 E.g.: 1855 /* ~ 1856 * Your typical comment. ~ 1857 */ ~ 1858 The indent on this line is the same as the start of the above 1859 comment. 1860 1861 All of this should be really cool, especially in conjunction with the new 1862 :autocmd command to prepare different settings for different types of file. 1863 1864 Some examples: 1865 for C code (only format comments): > 1866 :set fo=croq 1867 < for Mail/news (format all, don't start comment with "o" command): > 1868 :set fo=tcrq 1869 < 1870 1871 Automatic formatting *auto-format* *autoformat* 1872 1873 When the 'a' flag is present in 'formatoptions' text is formatted 1874 automatically when inserting text or deleting text. This works nicely for 1875 editing text paragraphs. A few hints on how to use this: 1876 1877 - You need to properly define paragraphs. The simplest is paragraphs that are 1878 separated by a blank line. When there is no separating blank line, consider 1879 using the 'w' flag and adding a space at the end of each line in the 1880 paragraphs except the last one. 1881 1882 - You can set the 'formatoptions' based on the type of file |filetype| or 1883 specifically for one file with a |modeline|. 1884 1885 - Set 'formatoptions' to "aw2tq" to make text with indents like this: 1886 1887 bla bla foobar bla 1888 bla foobar bla foobar bla 1889 bla bla foobar bla 1890 bla foobar bla bla foobar 1891 1892 - Add the 'c' flag to only auto-format comments. Useful in source code. 1893 1894 - Set 'textwidth' to the desired width. If it is zero then 79 is used, or the 1895 width of the screen if this is smaller. 1896 1897 And a few warnings: 1898 1899 - When part of the text is not properly separated in paragraphs, making 1900 changes in this text will cause it to be formatted anyway. Consider doing > 1901 1902 :set fo-=a 1903 1904 - When using the 'w' flag (trailing space means paragraph continues) and 1905 deleting the last line of a paragraph with |dd|, the paragraph will be 1906 joined with the next one. 1907 1908 - Changed text is saved for undo. Formatting is also a change. Thus each 1909 format action saves text for undo. This may consume quite a lot of memory. 1910 1911 - Formatting a long paragraph and/or with complicated indenting may be slow. 1912 1913 ============================================================================== 1914 7. Sorting text *sorting* 1915 1916 Vim has a sorting function and a sorting command. The sorting function can be 1917 found here: |sort()|, |uniq()|. 1918 Also see |:uniq|. 1919 1920 *:sor* *:sort* 1921 :[range]sor[t][!] [b][f][i][l][n][o][r][u][x] [/{pattern}/] 1922 Sort lines in [range]. When no range is given all 1923 lines are sorted. 1924 1925 With [!] the order is reversed. 1926 1927 With [i] case is ignored. 1928 *:sort-l* 1929 With [l] sort uses the current collation locale. 1930 Implementation details: strcoll() is used to compare 1931 strings. See |:language| to check or set the collation 1932 locale. Example: > 1933 :language collate en_US.UTF-8 1934 :%sort l 1935 < |v:collate| can also used to check the current locale. 1936 Sorting using the locale typically ignores case. 1937 This does not work properly on Mac. 1938 1939 Options [n][f][x][o][b] are mutually exclusive. 1940 1941 With [n] sorting is done on the first decimal number 1942 in the line (after or inside a {pattern} match). 1943 One leading '-' is included in the number. 1944 1945 With [f] sorting is done on the Float in the line. 1946 The value of Float is determined similar to passing 1947 the text (after or inside a {pattern} match) to 1948 str2float() function. This option is available only 1949 if Vim was compiled with Floating point support. 1950 1951 With [x] sorting is done on the first hexadecimal 1952 number in the line (after or inside a {pattern} 1953 match). A leading "0x" or "0X" is ignored. 1954 One leading '-' is included in the number. 1955 1956 With [o] sorting is done on the first octal number in 1957 the line (after or inside a {pattern} match). 1958 1959 With [b] sorting is done on the first binary number in 1960 the line (after or inside a {pattern} match). 1961 *:sort-u* *:sort-uniq* 1962 With [u] (u stands for unique) only keep the first of 1963 a sequence of identical lines (ignoring case when [i] 1964 is used). Without this flag, a sequence of identical 1965 lines will be kept in their original order. 1966 Note that leading and trailing white space may cause 1967 lines to be different. 1968 When you just want to make things unique, use |:uniq|. 1969 1970 When /{pattern}/ is specified and there is no [r] flag 1971 the text matched with {pattern} is skipped, so that 1972 you sort on what comes after the match. 1973 'ignorecase' applies to the pattern, but 'smartcase' 1974 is not used. 1975 Instead of the slash any non-letter can be used. 1976 For example, to sort on the second comma-separated 1977 field: > 1978 :sort /[^,]*,/ 1979 < To sort on the text at virtual column 10 (thus 1980 ignoring the difference between tabs and spaces): > 1981 :sort /.*\%10v/ 1982 < To sort on the first number in the line, no matter 1983 what is in front of it: > 1984 :sort /.\{-}\ze\d/ 1985 < (Explanation: ".\{-}" matches any text, "\ze" sets the 1986 end of the match and \d matches a digit.) 1987 With [r] sorting is done on the matching {pattern} 1988 instead of skipping past it as described above. 1989 For example, to sort on only the first three letters 1990 of each line: > 1991 :sort /\a\a\a/ r 1992 1993 < If a {pattern} is used, any lines which don't have a 1994 match for {pattern} are kept in their current order, 1995 but separate from the lines which do match {pattern}. 1996 If you sorted in reverse, they will be in reverse 1997 order after the sorted lines, otherwise they will be 1998 in their original order, right before the sorted 1999 lines. 2000 2001 If {pattern} is empty (e.g. // is specified), the 2002 last search pattern is used. This allows trying out 2003 a pattern first. 2004 2005 Note that using `:sort` with `:global` doesn't sort the matching lines, it's 2006 quite useless. 2007 2008 `:sort` does not use the current locale unless the l flag is used. 2009 Vim does do a "stable" sort. 2010 2011 The sorting can be interrupted, but if you interrupt it too late in the 2012 process you may end up with duplicated lines. This also depends on the system 2013 library function used. 2014 2015 ============================================================================== 2016 8. Deduplicating text *deduplicating* *unique* 2017 2018 Vim has a deduplicating function and a deduplicating command. The 2019 deduplicating function can be found here: |uniq()|. 2020 Also see |:sort-uniq|. 2021 2022 *:uni* *:uniq* 2023 :[range]uni[q][!] [i][l][r][u] [/{pattern}/] 2024 Remove duplicate lines that are adjacent to each other 2025 in [range]. When no range is given, all lines are 2026 processed. 2027 2028 With [i] case is ignored when comparing lines. 2029 2030 With [l] comparison uses the current collation locale. 2031 See |:sort-l| for more details. 2032 2033 With [r] comparison is done on the text that matches 2034 /{pattern}/ instead of the full line. 2035 2036 With [u] only keep lines that do not repeat (i.e., are 2037 not immediately followed by the same line). 2038 2039 With [!] only keep lines that are immediately followed 2040 by a duplicate. 2041 2042 If both [!] and [u] are given, [u] is ignored and [!] 2043 takes effect. 2044 2045 When /{pattern}/ is specified and [r] is not used, the 2046 text matched with {pattern} is skipped and comparison 2047 is done on what comes after the match. 2048 'ignorecase' applies to the pattern, but 'smartcase' 2049 is not used. 2050 Instead of the slash any non-letter can be used. 2051 2052 For example, to remove adjacent duplicate lines based 2053 on the second comma-separated field: > 2054 :uniq /[^,]*,/ 2055 < Or to keep only unique lines ignoring the first 5 2056 characters: > 2057 :uniq u /.\{5}/ 2058 < If {pattern} is empty (e.g. // is used), the last 2059 search pattern is used. 2060 2061 Note that leading and trailing white space may cause 2062 lines to be considered different. 2063 To remove all duplicates regardless of position, use 2064 |:sort-u| or external tools. 2065 2066 vim:tw=78:ts=8:noet:ft=help:norl: