change.txt ForVim version 9.1. Last change: 2025 Mar 18VIM REFERENCE MANUAL by Bram MoolenaarThis file describes commands that delete or change text. In this context,changing text meansdeleting the text andreplacingit with other text usingone command. You canundo all of these commands. You can repeat the non-Excommands with the "." command.1. Deleting textdeleting2. Delete andinsertdelete-insert3. Simple changessimple-changechanging4. Complex changescomplex-change 4.1 Filter commandsfilter 4.2 Substitute:substitute 4.3 Search and replacesearch-replace 4.4 Changing tabschange-tabs5. Copying and moving textcopy-move6. Formatting textformatting7. Sorting textsortingForinserting text seeinsert.txt.==============================================================================1. Deleting textdeletingE470["x]<Del>or<Del>xdl["x]xDelete[count] characters under and after the cursor[intoregister x] (notlinewise). Does the sameas"dl".The<Del> key does not takea[count]. Instead,itdeletes the last character of the count.See:fixdel if the<Del> key does notdo what youwant. See'whichwrap' fordeletinga line break(join lines).Xdh["x]XDelete[count] characters before the cursor [intoregister x] (notlinewise). Does the sameas "dh".Also see'whichwrap'.d["x]d{motion}Delete text that{motion} moves over [intoregisterx]. See below for exceptions.dd["x]ddDelete[count] lines [intoregister x]linewise.D["x]DDelete the characters under the cursor until theendof the line and[count]-1 more lines [intoregisterx]; synonym for "d$".(notlinewise)When the '#' flagis in'cpoptions' thecountisignored.{Visual}["x]xorv_xv_dv_<Del>{Visual}["x]d or{Visual}["x]<Del>Delete the highlighted text [intoregister x] (for{Visual} seeVisual-mode).{Visual}["x]CTRL-H orv_CTRL-Hv_<BS>{Visual}["x]<BS>When inSelect mode: Delete the highlighted text [intoregister x].{Visual}["x]Xorv_Xv_Dv_b_D{Visual}["x]DDelete the highlighted lines [intoregister x] (for{Visual} seeVisual-mode). InVisual block mode,"D" deletes the highlighted text plus all text untiltheend of the line.:d:de:del:delete:dl:dp:[range]d[elete] [x]Delete[range] lines (default: current line) [intoregister x].Note these weird abbreviations::dldelete andlist :dellidem :delelidem :deletlidem :deletelidem:dpdelete and print :depidem :delpidem :delepidem :deletpidem :deletepidem:[range]d[elete] [x]{count}Delete{count} lines,starting with[range](default: current linecmdline-ranges) [intoregister x].These commands delete text. You can repeat them with the. command(except:d) andundo them. UseVisual mode to delete blocks of text. Seeregisters for an explanation of registers.d-specialAn exception for the d{motion} command: If the motionis not linewise, thestart andend of the motion are not in the same line, and there are onlyblanks before the start and there are no non-blanks after theend of themotion, the delete becomes linewise. This means that the delete also removesthe line of blanks that you might expect to remain. Use theo_voperator toforce the motion to becharacterwise or remove the "z" flag from'cpoptions'(seecpo-z) to disable this peculiarity.Trying to delete an empty region of text (e.g., "d0" in the first column)is an error when'cpoptions' includes the 'E' flag.JJJoin[count] lines, witha minimum of two lines.Remove the indent andinsert up to two spaces (seebelow). Fails when on the last line of the buffer.If[count]is too bigitis reduced to the number oflines available.v_J{Visual}JJoin the highlighted lines, witha minimum of twolines. Remove the indent andinsert up to two spaces(see below).gJgJJoin[count] lines, witha minimum of two lines.Don'tinsert or remove any spaces.v_gJ{Visual}gJJoin the highlighted lines, witha minimum of twolines. Don'tinsert or remove any spaces.:j:join:[range]j[oin][!][flags]Join[range] lines. Sameas "J", except with [!]the join does notinsert or delete any spaces.Ifa[range] has equal start andend values, thiscommand does nothing. The default behavioris tojoin the current line with the line below it.Seeex-flags for[flags].:[range]j[oin][!]{count}[flags]Join{count} lines,starting with[range] (default:current linecmdline-ranges). Sameas "J", exceptwith [!] the join does notinsert or delete anyspaces.Seeex-flags for[flags].These commands delete the<EOL> between lines. This has the effect of joiningmultiple lines into one line. You can repeat these commands (except:j) andundo them.These commands, except "gJ",insert onespace in place of the<EOL> unlessthereis trailing whitespace or the next line starts witha ')'. Thesecommands, except "gJ", delete any leading whitespace on the next line. Ifthe'joinspaces' optionis on, these commandsinsert two spaces aftera '.','!' or '?' (but if'cpoptions' includes the 'j' flag, theyinsert two spacesonly aftera '.').The 'B' and 'M' flags in'formatoptions' change the behavior forinsertingspaces before and afteramultibyte characterfo-table.The'[markis setat theend of the first line that was joined,']at theendof the resulting line.==============================================================================2. Delete andinsertdelete-insertreplacingRREnterReplace mode: Each character you type replacesan existing character,starting with the characterunder the cursor. Repeat the entered text[count]-1times. SeeReplace-mode for more details.gRgREnter VirtualReplace mode: Each character you typereplaces existing characters in screen space. Soa<Tab> may replace several charactersat once.Repeat the entered text[count]-1 times. SeeVirtual-Replace-mode for more details.c["x]c{motion}Delete{motion} text [intoregister x] and startinsert. When'cpoptions' includes the 'E' flag andthereis no text to delete (e.g., with "cTx" when thecursoris just after an 'x'), an error occurs andinsert mode does not start (thisisVi compatible).When'cpoptions' does not include the 'E' flag, the"c" command always startsinsert mode, even if thereis no text to delete.cc["x]ccDelete[count] lines [intoregister x] and startinsertlinewise. If'autoindent'is on, preservethe indent of the first line.C["x]CDelete from the cursor position to theend of theline and[count]-1 more lines [intoregister x], andstart insert. Synonym for c$ (notlinewise).s["x]sDelete[count] characters [intoregister x] and startinsert (s stands for Substitute). Synonym for "cl"(notlinewise).S["x]SDelete[count] lines [intoregister x] and startinsert. Synonym for "cc"linewise.{Visual}["x]corv_cv_s{Visual}["x]sDelete the highlighted text [intoregister x] andstartinsert (for{Visual} seeVisual-mode).v_r{Visual}r{char}Replace all selected characters by{char}.CTRL-C will be inserted literally.v_C{Visual}["x]CDelete the highlighted lines [intoregister x] andstart insert. InVisual block modeit worksdifferentlyv_b_C.v_S{Visual}["x]SDelete the highlighted lines [intoregister x] andstartinsert (for{Visual} seeVisual-mode).v_R{Visual}["x]RCurrently just like{Visual}["x]S. Ina next versionit might work differently.Notes:- You canendInsert andReplace mode with<Esc>.- See thesection "Insert andReplace mode"mode-ins-repl for the other special characters in these modes.- The effect of[count] takes place after Vim exitsInsert orReplace mode.- When the'cpoptions' option contains '$' and the changeis within one line, Vim continues to show the text to be deleted and putsa '$'at the last deleted character.Seeregisters for an explanation of registers.Replace modeis just likeInsert mode, except that every character you enterdeletes one character. If you reach theend ofa line, Vim appends anyfurther characters (just likeInsert mode). InReplace mode, thebackspacekey restores the original text (if there was any). (Seesection "Insert andReplace mode"mode-ins-repl).cwcWSpecial case: When the cursoris ina word, "cw" and "cW"do not include thewhitespace aftera word, they only change up to theend of the word. Thisisbecause Vim interprets "cw"as change-word, andaword does not include thefollowing white space.{Vi: "cw" when ona blank followed by other blanks changes only the firstblank; thisis probablya bug, because "dw" deletes all the blanks; use the'w' flag in'cpoptions' to makeit work likeVi anyway}If you prefer "cw" to include thespace aftera word, use this mapping::map cw dwiAlternatively use "caw" (see alsoaw andcpo-z).:c:ch:change:{range}c[hange][!]Replace lines of text with some different text.Typea line containing only "." to stop replacing.Without{range}, this command changes only the currentline.Adding [!] toggles'autoindent' for the time thiscommandis executed.This commandis not supported inVim9 script,becauseitis too easily confused witha variablename.==============================================================================3. Simple changessimple-changerr{char}Replace the character under the cursor with{char}.If{char}isa<CR> or<NL>,a line break replaces thecharacter. To replace witha real<CR>, useCTRL-V<CR>.CTRL-V<NL> replaces witha<Nul>.If{char}isCTRL-E orCTRL-Y the character from theline below or aboveis used, just like withi_CTRL-Eandi_CTRL-Y. This also works witha count, thus10r<C-E> copies 10 characters from the line below.If you givea[count], Vim replaces[count] characterswith[count]{char}s. When{char}isa<CR> or<NL>,however, Vim inserts only one<CR>: "5r<CR>" replacesfive characters witha single line break.When{char}isa<CR> or<NL>, Vim performsautoindenting. This works just likedeleting thecharacters that are replaced and then doing"i<CR><Esc>".{char} can be enteredasadigraphdigraph-arg.:lmap mappings apply to{char}. TheCTRL-^ commandinInsert mode can be used to switch this on/offi_CTRL-^. Seeutf-8-char-arg about usingcomposing characters when'encoding'is Unicode.grgr{char}Replace the virtual characters under the cursor with{char}. This replaces in screen space, not filespace. SeegR andVirtual-Replace-mode for moredetails. As withracount may be given.{char} can be entered like withr, but charactersthat havea special meaning inInsert mode, suchasmostCTRL-keys, cannot be used.digraph-argThe argument forNormal mode commands liker andtisa single character.When'cpo' doesn't contain the 'D' flag, this character can also be enteredlikedigraphs. First typeCTRL-K and then the twodigraph characters.{not available when compiled without the |+digraphs| feature}caseThe following commands change thecase of letters. The currently activelocaleis used. See:language. The LC_CTYPE value matters here.~~'notildeop' option: Switchcase of the characterunder the cursor and move the cursor to the right.Ifa[count]is given,do that many characters.~{motion}'tildeop' option: switchcase of{motion} text.g~g~{motion}Switchcase of{motion} text.g~g~g~g~g~~g~~Switchcase of current line.v_~{Visual}~Switchcase of highlighted text (for{Visual} seeVisual-mode).v_U{Visual}UMake highlighted textuppercase (for{Visual} seeVisual-mode).gUuppercasegU{motion}Make{motion} text uppercase.Example::map! <C-F> <Esc>gUiw`]aThis works inInsert mode: pressCTRL-F to make theword before the cursor uppercase. Handy to typewords inlowercase and then make them uppercase.gUgUgUgUgUUgUUMake current line uppercase.v_u{Visual}uMake highlighted textlowercase (for{Visual} seeVisual-mode).gulowercasegu{motion}Make{motion} text lowercase.guguguguguuguuMake current line lowercase.g?rot13g?{motion}Rot13 encode{motion} text.v_g?{Visual}g?Rot13 encode the highlighted text (for{Visual} seeVisual-mode).g?g?g?g?g??g??Rot13 encode current line.To turn one line into title caps, make every firstletter ofaworduppercase::s/\v<(.)(\w*)/\u\1\L\2/gAdding and subtractingCTRL-ACTRL-AAdd[count] to the number or alphabetic characterator after the cursor.v_CTRL-A{Visual}CTRL-AAdd[count] to the number or alphabetic character inthe highlighted text.v_g_CTRL-A{Visual}gCTRL-AAdd[count] to the number or alphabetic character inthe highlighted text. If several lines are highlighted, each one will be incremented by anadditional[count] (so effectively creatinga[count] incrementing sequence).For Example, if you have thislist of numbers:1.1.1.1.Move to the second "1." and Visually select threelines, pressinggCTRL-A results in:1.2.3.4.CTRL-XCTRL-XSubtract[count] from the number or alphabeticcharacterat or after the cursor.v_CTRL-X{Visual}CTRL-XSubtract[count] from the number or alphabeticcharacter in the highlighted text.On MS-Windows, thisis mapped to cutVisual textdos-standard-mappings. If you want to disable themapping, use this:silent! vunmap <C-X>v_g_CTRL-X{Visual}gCTRL-XSubtract[count] from the number or alphabeticcharacter in the highlighted text. If several linesare highlighted, each value will be decremented by anadditional[count] (so effectively creatinga[count]decrementing sequence).TheCTRL-A andCTRL-X commands can work for:- signed and unsigned decimal numbers- unsigned binary,octal and hexadecimal numbers- alphabetic charactersThis depends on the'nrformats' option:- When'nrformats' includes "bin", Vim assumes numbersstarting with '0b' or '0B' are binary.- When'nrformats' includes "octal", Vim considers numbersstarting witha '0' to be octal, unless the number includesa '8' or '9'. Other numbers are decimal and may havea preceding minus sign. If the cursoris ona number, the commands apply to that number; otherwise Vim uses the number to the right of the cursor.- When'nrformats' includes "hex", Vim assumes numbersstarting with '0x' or '0X' are hexadecimal. Thecase of the rightmostletter in the number determines thecase of the resulting hexadecimal number. If thereis noletter in the current number, Vim uses the previously detected case.- When'nrformats' includes "alpha", Vim will change the alphabetic character under or after the cursor. Thisis useful to make lists with an alphabetic index.For decimalsa leading negative signis considered for incrementing/decrementing, for binary,octal and hex values,it won't be considered. Toignore the sign Visually select the number before usingCTRL-A orCTRL-X.For numbers with leading zeros (including alloctal and hexadecimal numbers),Vim preserves the number of characters in the number when possible.CTRL-A on"0077" results in "0100",CTRL-X on "0x100" results in "0x0ff".Thereis one exception: Whena number that starts witha zerois found not tobeoctal (it containsa '8' or '9'), but'nrformats' does include "octal",leading zeros are removed to avoid that the result may be recognizedas anoctal number.Note that when'nrformats' includes "octal", decimal numbers with leadingzeros cause mistakes, because they can be confused withoctal numbers.Note similarly, when'nrformats' includes both "bin" and "hex", binary numberswitha leading '0x' or '0X' can be interpretedas hexadecimal rather thanbinary since '0b' are valid hexadecimal digits.CTRL-A on "0x0b11" results in"0x0b12", not "0x0b100".When'nrformats' includes "bin" and doesn't include "hex",CTRL-A on "0b11" in"0x0b11" results in "0x0b100".When the number under the cursoris too big to fit into 32 or 64 bit(depending on how Vim was build),it will be rounded off to the nearest numberthat can be represented, and the addition/subtractionis skipped. E.g. with64 bit support usingCTRL-X on 18446744073709551616 results in18446744073709551615. Same for larger numbers, suchas 18446744073709551618.TheCTRL-A commandis very useful ina macro. Example: Use the followingsteps to makea numbered list.1. Create the firstlist entry, make sureit starts witha number.2. qa- startrecording intoregister 'a'3.Y-yank the entry4.p-puta copy of the entry below the first one5.CTRL-A- increment the number6.q- stoprecording7.<count>@a- repeat the yank,put and increment<count> timesSHIFTING LINES LEFT OR RIGHTshift-left-right<<{motion}Shift{motion} lines one'shiftwidth' leftwards.If the'vartabstop' featureis enabled, and the'shiftwidth' optionis set to zero, the amount ofindentis calculatedat the first non-blank characterin the line.<<<<Shift[count] lines one'shiftwidth' leftwards.v_<{Visual}[count]<Shift the highlighted lines[count]'shiftwidth'leftwards (for{Visual} seeVisual-mode).> >{motion}Shift{motion} lines one'shiftwidth' rightwards.If the'vartabstop' featureis enabled, and the'shiftwidth' optionis set to zero, the amount ofindentis calculatedat the first non-blank characterin the line.>>>>Shift[count] lines one'shiftwidth' rightwards.v_>{Visual}[count]>Shift the highlighted lines[count]'shiftwidth'rightwards (for{Visual} seeVisual-mode).:<:[range]<Shift[range] lines one'shiftwidth' left. Repeat '<'for shifting multiple'shiftwidth's.:[range]<{count}Shift{count} lines one'shiftwidth' left,startingwith[range] (default current linecmdline-ranges).Repeat '<' for shifting multiple'shiftwidth's.:[range]le[ft][indent]left align lines in[range]. Sets the indent in thelines to[indent] (default 0).:>:[range]>[flags]Shift[range] lines one'shiftwidth' right.Repeat '>' for shifting multiple'shiftwidth's.Seeex-flags for[flags].:[range]>{count}[flags]Shift{count} lines one'shiftwidth' right,startingwith[range] (default current linecmdline-ranges).Repeat '>' for shifting multiple'shiftwidth's.Seeex-flags for[flags].The ">" and "<" commands are handy forchanging the indentation withinprograms. Use the'shiftwidth' option to set the size of the whitespacewhich these commandsinsert or delete. Normally the'shiftwidth' optionis 8,but you can setit to, say, 3 to make smaller indents. Theshift leftwardsstops when thereis no indent. Theshift right does not affect empty lines.If the'shiftround' optionis on, the indentis rounded toa multiple of'shiftwidth'.If the'smartindent' optionis on, or'cindent'is on and'cinkeys' contains'#' witha zero value,shift right does not affect linesstarting with '#'(these are supposed to beC preprocessor lines thatmust stay in column 1).This can be changed with the'cino' option, seecino-#.When the'expandtab' optionis off (thisis the default) Vim uses<Tab>sasmuchas possible to make the indent. You can use ">><<" to replace an indentmade out of spaces with the same indent made out of<Tab>s (anda few spacesif necessary). If the'expandtab' optionis on, Vim uses only spaces. Thenyou can use ">><<" to replace<Tab>s in the indent by spaces (or use:retab!).To movea line several'shiftwidth's, useVisual mode or the: commands.For example:Vjj4>move three lines 4 indents to the right:<<<move current line 3 indents to the left:>> 5move 5 lines 2 indents to the right:5>>move line 5 2 indents to the right==============================================================================4. Complex changescomplex-change4.1 Filter commandsfilterAfilterisa program that accepts textat standard input, changesit in someway, and sendsit to standard output. You can use the commands below to sendsome text througha filter, so thatitis replaced by thefilter output.Examples of filters are "sort", which sorts lines alphabetically, and"indent", which formatsC program files (you needa version of indent thatworks likea filter; not all versions do). The'shell' optionspecifies theshell Vim uses to execute thefilter command (See also the'shelltype'option). You can repeatfilter commands with ".". Vim does not recognizeacomment (starting with'"') after the:! command.!!{motion}{filter}Filter{motion} text lines through the externalprogram{filter}.!!!!{filter}Filter[count] lines through the external program{filter}.v_!{Visual}!{filter}Filter the highlighted lines through the externalprogram{filter} (for{Visual} seeVisual-mode).:{range}![!]{filter} [!][arg]:range!For executing external commands see:!Filter{range} lines through the external program{filter}. Vim replaces the optional bangs with thelatest given command and appends the optional[arg].Vim saves the output of thefilter command inatemporary file and then reads the file into the buffertempfile. Vim uses the'shellredir' option toredirect thefilter output to the temporary file.However, if the'shelltemp' optionis off then pipesare used when possible (on Unix).When the 'R' flagis included in'cpoptions' marks inthe filtered lines are deleted, unless the:keepmarks commandis used. Example::keepmarks '<,'>!sortWhen the number of lines after filteringisless thanbefore, marks in the missing lines are deleted anyway.=={motion}Filter{motion} lines through the external programgiven with the'equalprg' option. When the'equalprg'optionis empty (thisis the default), use theinternalformatting functionC-indenting and'lisp'. But when'indentexpr'is not empty,it willbe used insteadindent-expression. When Vim wascompiled without internalformatting then the "indent"programis usedasa last resort.====Filter[count] lines like with ={motion}.v_={Visual}=Filter the highlighted lines like with ={motion}.tempfilesetuidVim uses temporary files for filtering, generating diffs and also fortempname(). For Unix, the file will be ina private directory (onlyaccessible by the current user) to avoid security problems (e.g.,a symlinkattack or other people reading your file). When Vim exits the directory andall files init are deleted (only on Unix, on other systems you will have toclean up yourself). When Vim has thesetuid bit set this may causeproblems, the temp fileis owned by thesetuid user but thefilter commandprobably runsas the original user.Directory for temporary filesis created in the first of these directoriesthat works:Unix: $TMPDIR, /tmp, current-dir, $HOME.Windows: $TMP, $TEMP, c:\TMP, c:\TEMPForMS-Windows the GetTempFileName() system functionis used.For other systems the tmpnam() library functionis used.4.2 Substitute:substitute:s:su:[range]s[ubstitute]/{pattern}/{string}/[flags][count]For each line in[range] replacea match of{pattern}with{string}.For the{pattern} seepattern.{string} can bea literal string, or somethingspecial; seesub-replace-special.When[range] and[count] are omitted, replace in thecurrent line only. When[count]is given, replace in[count] lines,starting with the last line in[range].When[range]is omitted start in the current line.E939E1510[count]must bea positive number (max 2147483647)Also seecmdline-ranges.See:s_flags for[flags].The delimiter doesn't need to be /, seepattern-delimiter.:[range]s[ubstitute][flags][count]:[range]&[&][flags][count]:&Repeat last:substitute with same searchpattern andsubstitute string, but without the same flags. Youmay add[flags], see:s_flags.Note that after:substitute the '&' flag can't beused, it's recognizedasapattern separator.Thespace between:substitute and the 'c', 'g','i', 'I' and 'r' flags isn't required, but in scriptsit'sa good idea to keepit to avoid confusion.Also see the two and threeletter commands to repeat:substitute below:substitute-repeat.:[range]~[&][flags][count]:~Repeat last substitute with same substitutestringbut with last used search pattern. Thisis like:&r. See:s_flags for[flags].&&Synonym for:s (repeat last substitute).Notethat the flags are not remembered, thusit mightactually work differently. You can use:&& to keepthe flags.g&g&Synonym for:%s//~/& (repeat last substitute withlast searchpattern on all lines with the same flags).For example, when you firstdoa substitution with:s/pattern/repl/flags and then/search forsomething else,g& willdo:%s/search/repl/flags.Mnemonic: global substitute.:snomagic:sno:[range]sno[magic]...Sameas:substitute, but always use'nomagic'.:smagic:sm:[range]sm[agic]...Sameas:substitute, but always use'magic'.:s_flagsThe flags that you can use for the substitute commands::&&[&]Must be the first one: Keep the flags from the previous substitutecommand. Examples::&&:s/this/that/&Note that:s and:& don't keep the flags.[c]Confirm each substitution. Vim highlights the matchingstring (withhl-IncSearch). You can type::s_c 'y' to substitute this match 'l' to substitute this match and then quit("last") 'n' to skip this match<Esc> to quit substituting 'a' to substitute this and all remaining matches 'q' to quit substitutingCTRL-E to scroll the screen upCTRL-Y to scroll the screen downIf the'edcompatible' optionis on, Vim remembers the [c] flag andtogglesit each time you use it, but resetsit when you givea newsearch pattern.:s_e[e] When the searchpattern fails,do not issue an error message and, inparticular, continue in mapsas if no error occurred. Thisis mostuseful to prevent the "No match" error from breakinga mapping. Vimdoes not suppress the following error messages, however:Regular expressions can't be delimited by letters\ should be followed by /,? or&No previous substitute regularexpressionTrailing charactersInterrupted:s_g[g]Replace all occurrences in the line. Without this argument,replacement occurs only for the first occurrence in each line. Ifthe'edcompatible' optionis on, Vim remembers this flag and togglesit each time you use it, but resetsit when you givea new searchpattern. If the'gdefault' optionis on, this flagis on by defaultand the [g] argument switchesit off.:s_i[i]Ignorecase for the pattern. The'ignorecase' and'smartcase'optionsare not used.:s_I[I]Don't ignorecase for the pattern. The'ignorecase' and'smartcase'options are not used.:s_n[n]Report the number of matches,do not actually substitute. The [c]flagis ignored. The matches are reportedas if'report'is zero.Useful tocount-items.If \=sub-replace-expressionis used, theexpression will beevaluated in thesandboxat every match.[p]Print the line containing the last substitute.:s_p[#]Like [p] and prepend the line number.:s_#[l]Like [p] but print the text like:list.:s_l:s_r[r]Only useful in combination with:& or:s without arguments.:&rworks the same wayas:~: When the searchpatternis empty, use thepreviously used searchpattern instead of the searchpattern from thelast substitute or:global. If the last command that dida searchwasa substitute or:global, thereis no effect. If the lastcommand wasa search command suchas "/", use thepattern from thatcommand.For:s with an argument this already happens::s/blue/red//green:s//red/ or :~ or :&rThe last commands will replace "green" with "red".:s/blue/red//green:&The last command will replace "blue" with "red".Note that thereis no flag to change the "magicness" of the pattern.Adifferent commandis used instead, or you can use/\v and friends. Thereasonis that the flags can only be found by skipping the pattern, and inorder to skip thepattern the "magicness"must be known. Catch 22!If the{pattern} for the substitute commandis empty, the command uses thepattern from the last substitute or:global command. If thereis none, butthereisa previous search pattern, that oneis used. With the [r] flag, thecommand uses thepattern from the last substitute,:global, or searchcommand.If the{string}is omitted the substituteis doneas if it's empty. Thus thematchedpatternis deleted. The separator after{pattern} can also be leftout then. Example::%s/TESTINGThis deletes "TESTING" from all lines, but only one per line.E1270For compatibility withVi these two exceptions are allowed in legacy script:"\/{string}/" and "\?{string}?"do the sameas "//{string}/r"."\&{string}&" does the sameas "//{string}/".pattern-delimiterE146E1241E1242Instead of the '/' which surrounds thepattern and replacement string, you canuse another single-byte character. Thisis useful if you want to includea'/' in the searchpattern or replacement string. Example::s+/+//+You can use most characters, but not an alphanumeric character, '\','"' or'|'. InVim9script you should not use '#' becauseit may be recognizedasthe start ofa comment.For the definition ofa pattern, seepattern. InVisual block mode, use/\%V in thepattern to have the substitute work in the block only.Otherwiseit works on whole lines anyway.sub-replace-special:s\=When the{string} starts with "\="itis evaluatedas an expression, seesub-replace-expression. You can use that for complex replacement or specialcharacters.The substitutionis limited in recursion to 4 levels.E1290Otherwise these characters in{string} havea special meaning::s%When{string}is equal to "%" and '/'is included with the'cpoptions' option,then the{string} of the previous substitute commandis used, seecpo-/magicnomagic action& \& replaced with the whole matchedpatterns/\& \&& replaced with&\0 replaced with the whole matchedpattern\0s/\0 \1 replaced with the matchedpattern in the first pair of ()s/\1 \2 replaced with the matchedpattern in the second pair of ()s/\2 .. ..s/\3 \9 replaced with the matchedpattern in the ninth pair of ()s/\9~ \~ replaced with the{string} of the previous substitutes~ \~~ replaced with~s/\~ \u next character madeuppercases/\u \U following characters made uppercase, until \Es/\U \l next character madelowercases/\l \L following characters made lowercase, until \Es/\L \eend of \u, \U, \l and \L (NOTE: not<Esc>!)s/\e \Eend of \u, \U, \l and \Ls/\E<CR> split line in twoat this point (Type the<CR>asCTRL-V<Enter>)s<CR> \r idems/\r \<CR>insertacarriage-return (CTRL-M) (Type the<CR>asCTRL-V<Enter>)s/\<CR> \ninserta<NL> (<NUL> in the file) (does NOT break the line)s/\n \binserta<BS>s/\b \tinserta<Tab>s/\t \\inserta singlebackslashs/\\ \x wherexis any character not mentioned above: Reserved for future expansionThe special meaningis also used inside the third argument{sub} ofthesubstitute() function with the following exceptions:-A% insertsa percent literally without regard to'cpoptions'.- magicis always set without regard to'magic'.-A~ insertsa tilde literally.-<CR> and \r insertsacarriage-return (CTRL-M).- \<CR> does not havea special meaning. It's just one of \x.Examples: :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx" :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb" :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines) :s/$/\^M/ modifies "abcde" to "abcde^M" :s/\w\+/\u\0/g modifies "bla bla" to "Bla Bla" :s/\w\+/\L\u\0/g modifies "BLA bla" to "Bla Bla"Note: "\L\u" can be used to capitalize the firstletter ofa word. Thisisnot compatible withVi and older versions of Vim, where the "\u" would cancelout the "\L". Same for "\U\l".Note: In previous versionsCTRL-V was handled ina special way. Since thisisnotVi compatible, this was removed. Useabackslash instead.commandtextresult:s/aa/a^Ma/aaa<line-break>a:s/aa/a\^Ma/aaa^Ma:s/aa/a\\^Ma/aaa\<line-break>a(you need to typeCTRL-V<CR> to geta ^M here)The numbering of "\1", "\2" etc.is done based on which "\(" comes first inthepattern (going left to right). Whena parentheses group matches severaltimes, the last one will be used for "\1", "\2", etc. Example: :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x"The "\2"is for "\(a[a-d] \)". At firstit matches "aa ", secondly "ab ".When using parentheses in combination with'|', like in \([ab]\)\|\([cd]\),either the first or secondpattern in parentheses did not match, so either\1 or \2is empty. Example: :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x":sc:sce:scg:sci:scI:scl:scp:sg:sgc:sge:sgi:sgI:sgl:sgn:sgp:sgr:sI:si:sic:sIc:sie:sIe:sIg:sIl:sin:sIn:sIp:sip:sIr:sir:sr:src:srg:sri:srI:srl:srn:srp:substitute-repeat2-letter and 3-letter :substitute commandsThese commands repeat the previous:substitute command with the given flags.The firstletteris always "s", followed by one or two of the possible flagcharacters. For example:sce works like:s///ce. The table lists thepossible combinations, not all flags are possible, because the commandisshort for another command.List of:substitute commands |cegiInplr |c:sc:sce:scg:sci:scI :scn:scp:scl |e |g:sgc:sge:sg:sgi:sgI:sgn:sgp:sgl:sgr |i:sic:sie:si :siI:sin:sip:sir |I:sIc:sIe:sIg :sIi:sI:sIn:sIp:sIl:sIr |n |p |l |r:src:srg:sri:srI:srn:srp:srl:srExceptions::scris:scriptnames:seis:set:sigis:sign:silis:silent:snis:snext:spis:split:slis:sleep:sreis:srewindSubstitute with anexpressionsub-replace-expressionsub-replace-\=s/\=When the substitutestring starts with "\=" the remainderis interpretedas anexpression.The special meaning for charactersas mentionedatsub-replace-special doesnot apply except for "<CR>".A<NL> characteris usedasa line break, youcan get one witha double-quote string: "\n". Prependabackslash to getareal<NL> character (which will bea NUL in the file).The "\="notation can also be used inside the third argument{sub} ofsubstitute() function. In this case, the special meaning for charactersasmentionedatsub-replace-special does not applyat all. Especially,<CR> and<NL> are interpreted notasa line break butasacarriage-return andanew-line respectively.When the resultisaList then the items are joined with separating linebreaks. Thus each item becomesa line, except that they can contain linebreaks themselves.Thesubmatch() function can be used to obtain matched text. The wholematched text can be accessed with "submatch(0)". The text matched with thefirst pair of () with "submatch(1)". Likewise for further sub-matches in ().Be careful: The separation charactermust not appear in the expression!Consider usinga character like "@" or ":". Thereis no problem if the resultof theexpression contains the separation character.Examples::s@\n@\="\r" .. expand("$HOME") .. "\r"@This replaces an end-of-line witha new line containing the value of $HOME.s/E/\="\<Char-0x20ac>"/gThis replaces each 'E' character withaeuro sign. Read more in<Char->.4.3 Search and replacesearch-replace:pro:promptfind:promptf[ind][string]Put upa Search dialog. When[string]is given,itisusedas the initial search string.{only for Win32, Motif and GTK GUI}:promptr:promptrepl:promptr[epl][string]Put upa Search/Replace dialog. When[string]isgiven,itis usedas the initial search string.{only for Win32, Motif and GTK GUI}4.4 Changing tabschange-tabs:ret:retab:retab!:[range]ret[ab][!][new_tabstop]Replace all sequences ofwhite-space containinga<Tab> with new strings ofwhite-space using the newtabstop value given. If youdo not specifya newtabstop size oritis zero, Vim uses the current valueof'tabstop'.The current value of'tabstop'is always used tocompute the width of existing tabs.With !, Vim also replaces strings of only normalspaces with tabs where appropriate.With'expandtab' on, Vim replaces all tabs with theappropriate number of spaces.This command sets'tabstop' to the new value given,and if performed on the whole file, whichis default,should not make any visible change.Careful: This command modifies any<Tab> charactersinside of strings inaC program. Use "\t" to avoidthis (that'sa good habit anyway).:retab! may also changea sequence of spaces by<Tab> characters, which can mess upa printf().If the+vartabs featureis enabled thenalist oftab widths separated by commas may be used in place ofa single tabstop. Each value in thelist representsthe width of one tabstop, except the final value whichapplies to all following tabstops.retab-exampleExample for usingautocommands and ":retab" to edita file whichis storedwith tabstopsat 8 but edited with tabstops setat 4. Warning: whitespaceinside of strings can change! Also see'softtabstop' option. :auto BufReadPost*.xxretab! 4 :auto BufWritePre*.xxretab! 8 :auto BufWritePost*.xxretab! 4 :auto BufNewFile*.xxset ts=4==============================================================================5. Copying and moving textcopy-movequote"{register}Use{register} for next delete,yank or put. Useanuppercase character to append with delete and yank.Registers ".", "%", "#" and ":" only work with put.:reg:registers:reg[isters]Display the type and contents of all numbered andnamed registers. Ifaregisteris written to for:redirit will not be listed.Type can be one of:"c"forcharacterwise text"l"forlinewise text"b"forblockwise-visual text:reg[isters]{arg}Display the contents of the numbered and namedregisters that are mentioned in{arg}. For example::reg 1ato displayregisters '1' and 'a'. Spaces are allowedin{arg}.:di:dis:display:di[splay][arg]Sameas :registers.yyank["x]y{motion}Yank{motion} text [intoregister x]. When nocharacters are to be yanked (e.g., "y0" in column 1),thisis an error when'cpoptions' includes the 'E'flag.yy["x]yyYank[count] lines [intoregister x]linewise.Y["x]Yyank[count] lines [intoregister x] (synonym foryy,linewise). If you like "Y" to work from thecursor to theend of line (whichis more logical,but not Vi-compatible) use ":mapY y$".zy["x]zy{motion}Yank{motion} text [intoregister x]. Only differsfromy when selectinga block of text, seev_zy.v_y{Visual}["x]yYank the highlighted text [intoregister x] (for{Visual} seeVisual-mode).v_Y{Visual}["x]YYank the highlighted lines [intoregister x] (for{Visual} seeVisual-mode).v_zy{Visual}["x]zyYank the highlighted text [intoregister x]. Trailingwhitespaceat theend of each line ofa selected blockwon't be yanked. Especially useful in combinationwithzp. (for{Visual} seeVisual-mode):y:yankE850:[range]y[ank] [x]Yank[range] lines [intoregister x]. Yanking to the"* or "+registersis possible only when the+clipboard featureis included.:[range]y[ank] [x]{count}Yank{count} lines,starting with last line numberin[range] (default: current linecmdline-ranges),[intoregister x].pputE353E1240["x]pPut the text [fromregister x] after the cursor[count] times.P["x]PPut the text [fromregister x] before the cursor[count] times.<MiddleMouse>["x]<MiddleMouse>Put the text fromaregister before the cursor[count]times. Uses the "* register, unless anotherisspecified.Leaves the cursorat theend of the new text.Using the mouse only works when'mouse' contains 'n'or 'a'.If you havea scrollwheel and often accidentally pastetext, you can use these mappings to disable thepasting with the middle mouse button::map <MiddleMouse> <Nop>:imap <MiddleMouse> <Nop>You might want to disable the multi-click versionstoo, seedouble-click.gp["x]gpJust like "p", but leave the cursor just after the newtext.gP["x]gPJust like "P", but leave the cursor just after the newtext.:pu:put:[line]pu[t] [x]Put the text [fromregister x] after[line] (defaultcurrent line). This always workslinewise, thusthis command can be used toputa yanked blockas newlines.If noregisteris specified,it depends on the'cb'option: If'cb' contains "unnamedplus", paste from the+registerquoteplus. Otherwise, if'cb' contains"unnamed", paste from the *registerquotestar.Otherwise, paste from the unnamedregisterquote_quote.Theregister can also be '=' followed by an optionalexpression. Theexpression continues until theend ofthe command. You need toescape the'|' and'"'characters to prevent them from terminating thecommand. Example::put ='path' .. \",/test\"If thereis noexpression after '=', Vim uses theprevious expression. You can seeit with ":dis=".:[line]pu[t]! [x]Put the text [fromregister x] before[line] (defaultcurrent line).:ip:iput:[line]ip[ut] [x]like:put, but adjust indent to the current line:[line]ip[ut]! [x]like:put!, but adjust indent to the current line["x]]p or]p]<MiddleMouse>["x]]<MiddleMouse>Like "p", but adjust the indent to the current line.Using the mouse only works when'mouse' contains 'n'or 'a'.["x][P or[P["x]]P or]P["x][p or[p[<MiddleMouse>["x][<MiddleMouse>Like "P", but adjust the indent to the current line.Using the mouse only works when'mouse' contains 'n'or 'a'.["x]zp orzpzP["x]zPLike "p" and "P", except without adding trailing spaceswhen pastinga block. Thus the inserted text will notalways bea rectangle. Especially useful incombination withv_zy.You can use these commands to copy text from one place to another. Do thisby first getting the text intoaregister witha yank, delete or changecommand, theninserting theregister contents withaput command. You canalso use these commands to move text from one file to another, because Vimpreserves allregisters whenchangingbuffers (theCTRL-^ commandisa quickway totoggle between two files).linewise-registercharacterwise-registerYou can repeat theput commands with "." (except for :put) andundo them. Ifthe command that was used to get the text into theregister waslinewise,Vim inserts the text below("p") or above("P") the line where the cursor is.Otherwise Vim inserts the text after("p") or before("P") the cursor. Withthe ":put" command, Vim always inserts the text in the next line. You canexchange two characters with the command sequence "xp". You can exchange twolines with the command sequence "ddp". You can exchange two words with thecommand sequence "deep" (start with the cursor in the blankspace before thefirst word). You can use the "']" or "`]" command after theput command tomove the cursor to theend of the inserted text, or use "'[" or "`[" to movethe cursor to the start.put-Visual-modev_pv_PWhen usingaput command likep orP inVisual mode, Vim will try toreplace the selected text with the contents of the register. Whether thisworks well depends on the type of selection and the type of the text in theregister. With blockwise selectionit also depends on the size of the blockand whether the corners are on an existing character. (Implementation detail:it actually works by first putting theregister after the selection and thendeleting the selection.)Withp the previously selected textisput in the unnamedregister (andpossibly the selection and/or clipboard). Thisis useful if you want toputthat text somewhere else. But you cannot repeat the same change.WithP the unnamedregisteris not changed (and neither the selection orclipboard), you can repeat the same change. But the deleted text cannot beused. If youdo needit you can usep with another register. E.g.,yankthe text to copy, Visually select the text to replace and use "0p. You canrepeat thisas many timesas you like, and the unnamedregister will bechanged each time.blockwise-putWhenaregister contains text from one line (characterwise), usingablockwiseVisual selection, putting thatregister will paste that textrepeatedly in each of the selected lines, thusreplacing the blockwiseselected region by multiple copies of theregister text. For example:-yank theword "TEXT" intoaregister withyw- selecta visual block, marked with "v" in this text: aaavvaaa bbbvvbbb cccvvccc- pressp, results in: aaaTEXTaaa bbbTEXTbbb cccTEXTcccblockwise-registerIf you usea blockwiseVisual mode command to get the text into the register,the block of text will be inserted before("P") or after("p") the cursorcolumn in the current and next lines. Vim makes the whole block of text startin the same column. Thus the inserted text looks the sameas whenit wasyanked or deleted. Vim may replace some<Tab> characters with spaces to makethis happen. However, if the width of the blockis nota multiple ofa<Tab>width and the text after the inserted block contains<Tab>s, that text may bemisaligned.UsezP/zp to pastea blockwise yankedregister without appending trailingspaces.Note that afteracharacterwiseyank command, Vim leaves the cursor on thefirst yanked character thatis closest to the start of the buffer. This meansthat "yl" doesn't move the cursor, but "yh" moves the cursor one characterleft.Rationale:InVi the "y" command followed bya backwards motion wouldsometimes not move the cursor to the first yanked character,because redisplaying was skipped. In Vimit always moves tothe first character,as specified by Posix.Withalinewiseyank command the cursorisput in the first line, but thecolumnis unmodified, thusit may not be on the first yanked character.There are ten types of registers:registers{register}E3541. The unnamedregister ""2. 10 numberedregisters "0 to "93. The small deleteregister "-4. 26 namedregisters "a to "z or "A to "Z5. Three read-onlyregisters ":, "., "%6. Alternate bufferregister "#7. Theexpressionregister "=8. The selection and dropregisters "*, "+ and "~ 9. The black holeregister "_10. Last searchpatternregister "/1. Unnamedregister ""quote_quotequotequoteVim fills thisregister with text deleted with the "d", "c", "s", "x" commandsor copied with theyank "y" command, regardless of whether or nota specificregister was used (e.g. "xdd). Thisis like the unnamedregisteris pointingto the last used register. Thus when appending using anuppercaseregistername, the unnamedregister contains the same textas the named register.An exceptionis the '_' register: "_dd does not store the deleted text in anyregister.Vim uses the contents of the unnamedregister for anyput command (p or P)which does not specifya register. Additionally you can accessit with thename'"'. This means you have to type two double quotes. Writing to the ""register writes toregister "0.{Vi: register contents are lost when changing files, no '"'}2. Numberedregisters "0 to "9quote_numberquote0quote1quote2quote3quote4quote9Vim fills theseregisters with text fromyank and delete commands. Numberedregister0 contains the text from the most recentyank command,unless the command specified anotherregister with["x]. Numberedregister 1 contains the text deleted by the most recent delete orchange command (even when the command specified another register), unless thetextisless than one line (the small deleteregisteris used then). Anexceptionis made for the deleteoperator with thesemovement commands:%,(,),`,/,?,n,N,{ and}.Register "1is always used then (thisisVi compatible). The "-registerisusedas well if the deleteis withina line.Note that these characters may bemapped. E.g.%is mapped by thematchit plugin. With each successive deletion or change, Vim shifts the previous contentsofregister 1 intoregister 2, 2 into 3, and so forth, losing the previouscontents ofregister 9.{Vi: register 0 does not exist}3. Small deleteregister "-quote_-quote-Thisregister contains text from commands that deleteless than one line,except when the commandspecifiesaregister with["x].4. Namedregisters "a to "z or "A to "Zquote_alphaquoteaVim fills theseregisters only when you say so. Specify themaslowercaseletters to replace their previous contents orasuppercase letters to appendto their previous contents. When the '>' flagis present in'cpoptions' thena line breakis inserted before the appended text.5. Read-onlyregisters ":, ". and "%These are '%', ':' and '.'. You can use them only with the "p", "P",and ":put" commands and withCTRL-R.quote_.quote.E29".Contains the last inserted text (the sameas whatis insertedwith theinsert mode commandsCTRL-A andCTRL-@).Note: thisdoesn't work withCTRL-R on the command-line. It worksa bitdifferently, likeinserting the text instead of puttingit('textwidth' and otheroptions affect whatis inserted).quote_%quote%"%Contains the name of the current file.quote_:quote:E30":Contains the most recent executed command-line. Example: Use"@:" to repeat the previous command-line command.The command-lineis only stored in thisregister whenat leastone character ofit was typed. Thusit remains unchanged ifthe command was completely froma mapping.{not available when compiled without the+cmdline_histfeature}quote_#quote#6. Alternate fileregister "#Contains the name of the alternate file for the current window. It willchange how theCTRL-^ command works.Thisregisteris writable, mainly to allow for restoringit afteraplugin haschanged it. It accepts buffer number: let altbuf = bufnr(@#) ... let @# = altbufIt will give errorE86 if you pass buffer number and this buffer does notexist.It can also accepta match with an existing buffer name: let @# = 'buffer_name'ErrorE93 if thereis more than one buffer matching the given name orE94if none ofbuffers matches the given name.7. Expressionregister "=quote_=quote=@=Thisis not reallyaregister that stores text, butisa way to use anexpression in commands which usea register. Theexpressionregisterisread-write.When typing the '=' after " orCTRL-R the cursor moves to the command-line,where you can enter anyexpression (seeexpression). All normalcommand-line editing commands are available, includinga specialhistory forexpressions. When youend the command-line by typing<CR>, Vim computes theresult of the expression. If youendit with<Esc>, Vim abandons theexpression. If youdo not enter an expression, Vim uses the previousexpression (like with the "/" command).Theexpressionmust evaluate toa String.ANumberis always automaticallyconverted toa String. For the "p" and ":put" command, if the resultisaFloat it's converted intoa String. If the resultisaList each elementisturned intoaString and usedasa line.ADictionaryis converted intoaString.AFuncref results in an error message (usestring() to convert).If the "=registeris used for the "p" command, theStringis split upat<NL>characters. If theString ends ina<NL>,itis regardedasalinewiseregister.8. Selection and dropregisters "*, "+ and "~ Use theseregisters for storing and retrieving the selected text for the GUI.Seequotestar andquoteplus. When theclipboardis not available or notworking, the unnamedregisteris used instead. ForUnix systems theclipboardis only available when the+xterm_clipboard featureis present.Note that thereis onlya distinction between "* and "+ forX11 systems. Foran explanation of the difference, seex11-selection. Under MS-Windows, useof "* and "+is actually synonymous and refers to thegui-clipboard.quote_~quote~<Drop>The read-only "~register stores the dropped text from the last drag'n'dropoperation. When something has been dropped onto Vim, the "~registerisfilled in and the<Drop> pseudo keyis sent for notification. You can remapthis key if you want; the default action (for all modes)is toinsert thecontents of the "~registerat the cursor position.{only available when compiled with the+dnd feature, currently only with theGTK GUI}Note: The "~registeris only used when dropping plain text onto Vim.Drag'n'drop of URI listsis handled internally.9. Black holeregister "_quote_Whenwriting to this register, nothing happens. This can be used to deletetext without affecting the normal registers. When reading from this register,nothingis returned.10. Last searchpatternregister"/quote_/quote/Contains the most recent search-pattern. Thisis used for "n" and'hlsearch'.Itis writable with:let, you can changeit to have'hlsearch' highlightother matches without actually searching. You can'tyank or delete into thisregister. The search directionis available inv:searchforward.Note that the valueis restored when returning froma functionfunction-search-undo.@/You can write toaregister witha:let command:let-@. Example::let @/ = "the"If you useaput command without specifyinga register, Vim uses theregisterthat was last filled (thisis also the contents of the unnamed register). Ifyou are confused, use the:dis command to find out what Vim willput (thiscommand displays all named and numbered registers; the unnamedregisterislabelled'"').The next three commands always work on whole lines.:[range]co[py]{address}:co:copyCopy the lines given by[range] to below the linegiven by{address}.:t:tSynonym for copy.This commandis not supported inVim9 script,becauseitis too easily confused witha variablename.:[range]m[ove]{address}:m:mo:moveE134Move the lines given by[range] to below the linegiven by{address}.Any text properties in[range] are cleared. Seetext-prop-cleared.==============================================================================6. Formatting textformatting:[range]ce[nter][width]:ce:centerCenter lines in[range] between[width] columns(default'textwidth' or 80 when'textwidth'is 0).:[range]ri[ght][width]:ri:rightRight-align lines in[range]at[width] columns(default'textwidth' or 80 when'textwidth'is 0).:le:left:[range]le[ft][indent]Left-align lines in[range]. Sets the indent in thelines to[indent] (default 0).gqgq{motion}Format the lines that{motion} moves over.Formattingis done with one of three methods:1. If'formatexpr'is not empty theexpressionis evaluated. This can differ for each buffer.2. If'formatprg'is not empty an external programis used.3. Otherwiseformattingis done internally.In the thirdcase the'textwidth' option controls thelength of each formatted line (see below).If the'textwidth' optionis 0, the formatted linelengthis the screen width (witha maximum width of79).The'formatoptions' option controls the type offormattingfo-table.The cursoris left on the first non-blank of the lastformatted line.NOTE: The "Q" command formerly performed thisfunction. If you still want to use "Q" forformatting, use this mapping::nnoremap Q gqgqgqgqgqgqqgqqFormat the current line. Withacount format thatmany lines.v_gq{Visual}gqFormat the highlighted text. (for{Visual} seeVisual-mode).gwgw{motion}Format the lines that{motion} moves over. Similar togq but puts the cursor backat the same position inthe text. However,'formatprg' and'formatexpr' arenot used.gwgwgwgwgwwgwwFormat the current lineas with "gw".v_gw{Visual}gwFormat the highlighted textas with "gw". (for{Visual} seeVisual-mode).Example: To format the currentparagraph use:gqapgqapThe "gq" command leaves the cursor in the line where the motion command takesthe cursor. This allows you to repeatformatting repeated with ".". Thisworks well with "gqj" (format current and next line) and "gq}" (format untilend of paragraph).Note: When'formatprg'is set, "gq" leaves the cursor onthe first formatted line (as with usingafilter command).If you want to format the currentparagraph and continue where you were, use:gwapIf you always want to keep paragraphs formatted you may want to add the 'a'flag to'formatoptions'. Seeauto-format.If the'autoindent' optionis on, Vim uses the indent of the first line forthe following lines.Formatting does not change empty lines (butit does change lines with onlywhite space!).The'joinspaces' optionis used when lines are joined together.You can set the'formatexpr' option to anexpression or the'formatprg' optionto the name of an external program for Vim to use for text formatting. The'textwidth' and otheroptions have no effect onformatting by an externalprogram.format-formatexprThe'formatexpr' option can be set toa Vimscript function that performsreformatting of the buffer. This should usually happen in anftplugin,sinceformattingis highly dependent on the type of file. It makessense to use anautoload script, so the correspondingscriptis only loadedwhen actually needed and thescript should be called<filetype>format.vim.For example, the XMLfiletypeplugin distributed with Vim in the$VIMRUNTIME/ftplugin directory, sets the'formatexpr' option to: setlocal formatexpr=xmlformat#Format()That means, you will find the corresponding script, defining thexmlformat#Format() function, in the file$VIMRUNTIME/autoload/xmlformat.vimHereis an examplescript that removes trailingwhitespace from the selectedtext. Putit in yourautoload directory, e.g. ~/.vim/autoload/format.vim: func! format#Format() " only reformat on explicit gq command if mode() != 'n' " fall back to Vim's internal reformatting return 1 endif let lines = getline(v:lnum, v:lnum + v:count - 1) call map(lines, {key, val -> substitute(val, '\s\+$', '', 'g')}) call setline('.', lines) " do not run internal formatter! return 0 endfuncYou can then enable theformatting by executing: setlocal formatexpr=format#Format()Note: this function explicitly returns non-zero when called frominsert mode(which basically means, textis inserted beyond the'textwidth' limit). Thiscauses Vim to fall back to reformat the text by using the internal formatter.However, if thegq commandis used to reformat the text, the functionwill receive the selected lines, trim trailingwhitespace from those lines andput them back in place. If you are going to split single lines into multiplelines, be careful not to overwrite anything.If you want to allow reformatting of text frominsert or replace mode, one hasto be very careful, because the function might be called recursively. Fordebuggingit helps to set the'debug' option.right-justifyThereis no command in Vim to rightjustify text. You candoit withan external command, like "par" (e.g.::.,}!par to format until theend of theparagraph) or set'formatprg' to "par".format-commentsAn overview of commentformattingis insection30.6 of the user manual.Vim can automaticallyinsert and format comments ina special way. Vimrecognizesa comment bya specificstringat the start of the line (ignoringwhite space). Three types of comments can be used:-A commentstring that repeatsat the start of each line. An exampleis the type of comment used in shell scripts,starting with "#".-A commentstring that occurs only in the first line, not in the following lines. An exampleis thislist with dashes.- Three-piece comments that havea start string, anend string, and optional lines in between. The strings for the start, middle andend are different. An exampleis theC style comment:/* * thisisaC comment */The'comments' optionisa comma-separatedlist of parts. Each part definesatype of comment string.A part consists of:{flags}:{string}{string}is the literal text thatmust appear.{flags}:nNested comment. Nesting with mixed partsis allowed. If'comments'is "n:),n:>"a linestarting with ">)>"isa comment.bBlank (<Space>,<Tab> or<EOL>) required after{string}.fOnly the first line has the comment string. Do not repeat comment onthe next line, but preserve indentation (e.g.,a bullet-list).sStart of three-piece commentmMiddle ofa three-piece commenteEnd ofa three-piece commentlLeft align. Used together with 's' or 'e', the leftmost character ofstart orend will line up with the leftmost character from the middle.Thisis the default and can be omitted. See below for more details.rRight align. Sameas above but rightmost instead of leftmost. Seebelow for more details.ODon't consider this comment for the "O" command.xAllows three-piece comments to be ended by just typing the lastcharacter of the end-commentstringas the first action ona newline when the middle-commentstring has been inserted automatically.See below for more details.{digits}When together with 's' or 'e': add{digit} amount of offset to anautomatically inserted middle orend comment leader. The offset beginsfroma left alignment. See below for more details. -{digits}Like{digits} but reduce the indent. This only works when thereissome indent for the start orend part that can be removed.Whenastring has none of the 'f', 's', 'm' or 'e' flags, Vim assumes thecommentstring repeatsat the start of each line. The{flags} field may beempty.Any blankspace in the text before and after the{string}is part of the{string}, sodo not include leading or trailing blanks unless the blanks arearequired part of the comment string.When one comment leaderis part of another, specify the part after the whole.For example, to include both "-" and "->", use:set comments=f:->,f:-A three-piece commentmust always be givenas start,middle,end, with no otherparts in between. An example ofa three-piece commentissr:/*,mb:*,ex:*/for C-comments. To avoid recognizing "*ptr"asa comment, the middlestringincludes the 'b' flag. For three-piece comments, Vim checks the text afterthe start and middle strings for theend string. If Vim finds theend string,the comment does not continue on the next line. Three-piece commentsmusthavea middlestring because otherwise Vim can't recognize the middle lines.Notice the use of the "x" flag in the above three-piece comment definition.When you hit Return ina C-comment, Vim willinsert the middle comment leaderfor the new line: " * ". To close this comment you just have to type "/"before typing anything else on the new line. This will replace themiddle-comment leader with the end-comment leader and apply any specifiedalignment, leaving just " */". Thereis no need to hit Backspace first.When thereisa match witha middle part, but there alsoisa matchingendpart whichis longer, theend partis used. This makesaC style comment workwithout requiring the middle part toend witha space.Hereis an example of alignment flagsat work to makea comment stand out(kind of looks likea 1 too). Consider comment string::set comments=sr:/***,m:**,ex-2:******/ /*** **<--right aligned from "r" flag **offset 2 spaces for the "-2" flag--->** ******/In this case, the first comment was typed, then return was pressed 4 times,then "/" was pressed toend the comment.Here are some finer points of three part comments. There are three times whenalignment and offset flags are taken into consideration: openinga new lineaftera start-comment, openinga new line before an end-comment, andautomatically endinga three-piece comment. Theend alignment flag hasabackwards perspective; the resultis that the same alignment flag used with"s" and "e" will result in the same indent for thestarting and ending pieces.Only one alignment per comment partis meant to be used, but an offset numberwill override the "r" and "l" flag.Enabling'cindent' will override the alignment flags in many cases.Reindenting usinga differentmethod likegq or= will not consultalignment flags either. The same behaviour can be defined in those otherformatting options. One considerationis that'cindent' has additionaloptionsfor context based indenting of comments but cannot replicate many three pieceindent alignments. However,'indentexpr' has the ability to work better withthree piece comments.Other examples: "b:*"Includes lines starting with "*", but not if the "*" isfollowed by a non-blank. This avoids a pointer dereferencelike "*str" to be recognized as a comment. "n:>"Includes a line starting with ">", ">>", ">>>", etc. "fb:-"Format a list that starts with "- ".By default, "b:#"is included. This means thata line that starts with"#include"is not recognizedasa comment line. Buta line that starts with"# define"is recognized. Thisisa compromise.fo-tableYou can use the'formatoptions' option to influence how Vim formats text.'formatoptions'isastring that can contain any of the letters below. Thedefault settingis "tcq". You can separate the option letters with commas forreadability.letter meaning when present in 'formatoptions'fo-ttAuto-wrap text using'textwidth'fo-ccAuto-wrap comments using'textwidth',inserting the current commentleader automatically.fo-rrAutomaticallyinsert the current comment leader after hitting<Enter> inInsert mode.fo-ooAutomaticallyinsert the current comment leader after hitting 'o' or'O' inNormal mode. Incase commentis unwanted ina specific placeuseCTRL-U to quickly delete it.i_CTRL-Ufo-//When 'o'is included:do notinsert the comment leader fora//comment aftera statement, only when//isat the start of the line.fo-qqAllowformatting of comments with "gq".Note thatformatting will not change blank lines or lines containingonly the comment leader.A newparagraph starts after sucha line,or when the comment leader changes.fo-wwTrailing whitespace indicatesaparagraph continues in the next line.A line that ends ina non-white character endsa paragraph.fo-aaAutomaticformatting of paragraphs. Every time textis inserted ordeleted theparagraph will be reformatted. Seeauto-format.When the 'c' flagis present this only happens for recognizedcomments.fo-nnWhenformatting text, recognize numbered lists. This actually usesthe'formatlistpat' option, thus any kind oflist can be used. Theindent of the text after the numberis used for the next line. Thedefaultis to finda number, optionally followed by '.', ':', ')',']' or '}'.Note that'autoindent'must be set too. Doesn't workwell together with "2".Example:1. the first item wraps2. the second itemfo-22Whenformatting text, use the indent of the second line ofaparagraphfor the rest of the paragraph, instead of the indent of the firstline. This supports paragraphs in which the first line hasadifferent indent than the rest.Note that'autoindent'must be settoo. Example:first line of a paragraphsecond line of the same paragraphthird line.This also works inside comments, ignoring the comment leader.fo-vvVi-compatible auto-wrapping ininsert mode: Only breaka lineatablank that you have entered during the currentinsert command. (Note:thisis not 100%Vi compatible.Vi has some "unexpected features" orbugs in this area. It uses the screen column instead of the linecolumn.)fo-bbLike 'v', but only auto-wrap if you entera blankat or beforethe wrap margin. If the line was longer than'textwidth' when youstarted the insert, or youdo not entera blank in theinsert beforereaching'textwidth', Vim does not perform auto-wrapping.fo-llLong lines are not broken ininsert mode: Whena line was longer than'textwidth' when theinsert command started, Vim does notautomatically format it.fo-mmAlso breakatamultibyte character above 255. Thisis useful forAsian text where every characterisaword on its own.fo-MMWhen joining lines, don'tinsertaspace before or afteramultibytecharacter. Overrules the 'B' flag.fo-BBWhen joining lines, don'tinsertaspace between twomultibytecharacters. Overruled by the 'M' flag.fo-11Don't breaka line aftera one-letter word. It's broken beforeitinstead (if possible).fo-]]Respect'textwidth' rigorously. With this flag set, no line can belonger than'textwidth', unless line-break-prohibition rules make thisimpossible. Mainly for CJK scripts and works only if'encoding'is"utf-8".fo-jjWhereit makes sense, removea comment leader when joining lines. Forexample, joining:int i; // the index // in the listBecomes:int i; // the index in the listfo-ppDon't break linesat single spaces that follow periods. Thisisintended to complement'joinspaces' andcpo-J, for prose withsentences separated by two spaces. For example, with'textwidth' setto 28:Surely you're joking, Mr. Feynman!Becomes:Surely you're joking,Mr. Feynman!Instead of:Surely you're joking, Mr.Feynman!With 't' and 'c' you can specify when Vim performs auto-wrapping:valueaction""no automaticformatting (you can use "gq" for manual formatting)"t"automaticformatting of text, but not comments"c"automaticformatting for comments, but not text (good forC code)"tc"automaticformatting for text and commentsNote that when'textwidth'is 0, Vim does no automaticformatting anyway (butdoesinsert comment leaders according to the'comments' option). An exceptionis when the 'a' flagis present.auto-formatNote that when'paste'is on, Vim does noformattingat all.Note that'textwidth' can be non-zero even if Vim never performs auto-wrapping;'textwidth'is still useful forformatting with "gq".If the'comments' option includes "/*", "*" and/or "*/", then Vim has somebuilt in stuff to treat these types of commentsa bit more cleverly.Openinga new line before or after "/*" or "*/" (with 'r' or 'o' present in'formatoptions') gives the correct start of the line automatically. The samehappens withformatting and auto-wrapping. Openinga line aftera linestarting with "/*" or "*" and containing "*/", will cause no comment leader tobe inserted, and the indent of the new lineis taken from the line containingthe start of the comment.E.g.: /* * Your typical comment. */ The indent on this lineis the sameas the start of the above comment.All of this should be really cool, especially in conjunction with the new:autocmd command to prepare different settings for different types of file.Some examples: forC code (only format comments)::set fo=croq for Mail/news(format all, don't start comment with "o" command)::set fo=tcrqAutomaticformattingauto-formatautoformatWhen the 'a' flagis present in'formatoptions' textis formattedautomatically wheninserting text ordeleting text. This works nicely forediting text paragraphs.A few hints on how to use this:- You need to properly define paragraphs. The simplestis paragraphs that are separated bya blank line. When thereis no separating blank line, consider using the 'w' flag and addingaspaceat theend of each line in the paragraphs except the last one.- You can set the'formatoptions' based on the type of filefiletype or specifically for one file withamodeline.- Set'formatoptions' to "aw2tq" to make text with indents like this: bla bla foobar bla bla foobar bla foobar bla bla bla foobar bla bla foobar bla bla foobar- Add the 'c' flag to onlyauto-format comments. Useful in source code.- Set'textwidth' to the desired width. Ifitis zero then 79is used, or the width of the screen if thisis smaller.Anda few warnings:- When part of the textis not properly separated in paragraphs, making changes in this text will causeit to be formatted anyway. Consider doing:set fo-=a- When using the 'w' flag (trailingspace meansparagraph continues) anddeleting the last line ofaparagraph withdd, theparagraph will be joined with the next one.- Changed textis saved for undo. Formattingis alsoa change. Thus each format action saves text for undo. This may consume quitea lot of memory.- Formattinga longparagraph and/or with complicated indenting may be slow.==============================================================================7. Sorting textsortingVim hasasorting function andasorting command. Thesorting function can befound here:sort(),uniq().:sor:sort:[range]sor[t][!] [b][f][i][l][n][o][r][u][x] [/{pattern}/]Sort lines in[range]. When no rangeis given alllines are sorted.With [!] the orderis reversed.With [i]caseis ignored.With [l] sort uses the current collation locale.Implementation details: strcoll()is used to comparestrings. See:language to check or set the collationlocale. Example::language collate en_US.UTF-8:%sort lv:collate can also used to check the current locale.Sorting using thelocale typically ignores case.This does not work properly on Mac.Options [n][f][x][o][b] are mutually exclusive.With [n]sortingis done on the first decimal numberin the line (after or insidea{pattern} match).One leading '-'is included in the number.With [f]sortingis done on theFloat in the line.The value ofFloatis determined similar to passingthe text (after or insidea{pattern} match) tostr2float() function. This optionis available onlyif Vim was compiled with Floating point support.With [x]sortingis done on the first hexadecimalnumber in the line (after or insidea{pattern}match).A leading "0x" or "0X"is ignored.One leading '-'is included in the number.With [o]sortingis done on the firstoctal number inthe line (after or insidea{pattern} match).With [b]sortingis done on the first binary number inthe line (after or insidea{pattern} match).With [u] (u stands for unique) only keep the first ofa sequence of identical lines (ignoringcase when [i]is used). Without this flag,a sequence of identicallines will be kept in their original order.Note that leading and trailing whitespace may causelines to be different.When /{pattern}/is specified and thereis no [r] flagthe text matched with{pattern}is skipped, so thatyou sort on what comes after the match.'ignorecase' applies to the pattern, but'smartcase'is not used.Instead of the slash any non-letter can be used.For example, to sort on the second comma-separatedfield::sort /[^,]*,/To sort on the textat virtual column 10 (thusignoring the difference between tabs and spaces)::sort /.*\%10v/To sort on the first number in the line, no matterwhatis in front of it::sort /.\{-}\ze\d/(Explanation: ".\{-}" matches any text, "\ze" sets theend of the match and \d matchesa digit.)With [r]sortingis done on the matching{pattern}instead of skipping pastitas described above.For example, to sort on only the first three lettersof each line::sort /\a\a\a/ rIfa{pattern}is used, any lines which don't haveamatch for{pattern} are kept in their current order,but separate from the lines whichdo match{pattern}.If you sorted in reverse, they will be in reverseorder after the sorted lines, otherwise they will bein their original order, right before the sortedlines.If{pattern}is empty (e.g.//is specified), thelast searchpatternis used. This allows trying outapattern first.Note that using:sort with:global doesn't sort the matching lines, it'squite useless.:sort does not use the currentlocale unless thel flagis used.Vim doesdoa "stable" sort.Thesorting can be interrupted, but if you interruptit too late in theprocess you mayend up with duplicated lines. This also depends on the systemlibrary function used. vim:tw=78:ts=8:noet:ft=help:norl: