map.txt ForVim version 9.1. Last change: 2024 Oct 08VIM REFERENCE MANUAL by Bram MoolenaarKey mapping,abbreviations and user-defined commands.This subjectis introduced in sections05.4,24.7 and40.1 of the usermanual.1. Keymappingkey-mapping 1.1 MAP COMMANDS:map-commands 1.2Special arguments:map-arguments 1.3 Mapping and modes:map-modes 1.4 Listing mappingsmap-listing 1.5 Mapping special keys:map-special-keys 1.6Special characters:map-special-chars 1.7 What keys to mapmap-which-keys 1.8 Examplesmap-examples 1.9 Using mappingsmap-typing 1.10 Mapping alt-keys:map-alt-keys 1.11 Mapping meta-keys:map-meta-keys 1.12 Mapping super-keys or command keys:map-super-keys 1.13 Mapping inmodifyOtherKeys modemodifyOtherKeys 1.14 Mapping with Kitty keyboard protocolkitty-keyboard-protocol 1.15 Mapping anoperator:map-operator2.Abbreviationsabbreviations3. Local mappings andfunctionsscript-local4. User-defined commandsuser-commands==============================================================================1. Keymappingkey-mappingmappingmacroKeymappingis used to change the meaning of typed keys. The most common useis to definea sequence of commands fora function key. Example::map <F2> a<C-R>=strftime("%c")<CR><Esc>This appends the current date and time after the cursor (in<>notation<>).1.1 MAP COMMANDS:map-commandsThere are commands to enter new mappings, remove mappings andlist mappings.Seemap-overview for thevarious forms of "map" and their relationships withmodes.{lhs}means left-hand-side{lhs}{rhs}means right-hand-side{rhs}:map{lhs}{rhs}mapmode-nvo:map:nm[ap]{lhs}{rhs}mapmode-n:nm:nmap:vm[ap]{lhs}{rhs}mapmode-v:vm:vmap:xm[ap]{lhs}{rhs}mapmode-x:xm:xmap:smap{lhs}{rhs}mapmode-s:smap:om[ap]{lhs}{rhs}mapmode-o:om:omap:map!{lhs}{rhs}mapmode-ic:map!:im[ap]{lhs}{rhs}mapmode-i:im:imap:lm[ap]{lhs}{rhs}mapmode-l:lm:lma:lmap:cm[ap]{lhs}{rhs}mapmode-c:cm:cmap:tma[p]{lhs}{rhs}mapmode-t:tma:tmapMap the key sequence{lhs} to{rhs} for the modeswhere the map command applies. The result, including{rhs},is then further scanned for mappings. Thisallows for nested and recursive use of mappings.Note: Trailing spaces are included in the{rhs},becausespaceisa validNormal mode command.Seemap-trailing-white.:nore:norem:no[remap]{lhs}{rhs}mapmode-nvo:no:noremap:nor:nn[oremap]{lhs}{rhs}mapmode-n:nn:nnoremap:vn[oremap]{lhs}{rhs}mapmode-v:vn:vnoremap:xn[oremap]{lhs}{rhs}mapmode-x:xn:xnoremap:snor[emap]{lhs}{rhs}mapmode-s:snor:snore:snoremap:ono[remap]{lhs}{rhs}mapmode-o:ono:onoremap:no[remap]!{lhs}{rhs}mapmode-ic:no!:noremap!:ino[remap]{lhs}{rhs}mapmode-i:ino:inor:inoremap:ln[oremap]{lhs}{rhs}mapmode-l:ln:lnoremap:cno[remap]{lhs}{rhs}mapmode-c:cno:cnor:cnoremap:tno[remap]{lhs}{rhs}mapmode-t:tno:tnoremapMap the key sequence{lhs} to{rhs} for the modeswhere the map command applies. Disallowmapping of{rhs}, to avoid nested and recursive mappings. Oftenused to redefinea command.Note: Keys in{rhs} also won't trigger abbreviation,with the exception ofi_CTRL-] andc_CTRL-].Note: When<Plug> appears in the{rhs} this partisalways applied even if remappingis disallowed.:unm[ap]{lhs}mapmode-nvo:unm:unmap:nun[map]{lhs}mapmode-n:nun:nunmap:vu[nmap]{lhs}mapmode-v:vu:vunmap:xu[nmap]{lhs}mapmode-x:xu:xunmap:sunm[ap]{lhs}mapmode-s:sunm:sunmap:ou[nmap]{lhs}mapmode-o:ou:ounmap:unm[ap]!{lhs}mapmode-ic:unm!:unmap!:iu[nmap]{lhs}mapmode-i:iu:iunmap:lu[nmap]{lhs}mapmode-l:lu:lunmap:cu[nmap]{lhs}mapmode-c:cu:cun:cunmap:tunma[p]{lhs}mapmode-t:tunma:tunmapRemove themapping of{lhs} for the modes where themap command applies. Themapping may remain definedfor other modes whereit applies.It also works when{lhs} matches the{rhs} ofamapping. Thisis for when an abbreviation applied.Note: Trailing spaces are included in the{lhs}.Seemap-trailing-white.:mapc[lear]mapmode-nvo:mapc:mapclear:nmapc[lear]mapmode-n:nmapc:nmapclear:vmapc[lear]mapmode-v:vmapc:vmapclear:xmapc[lear]mapmode-x:xmapc:xmapclear:smapc[lear]mapmode-s:smapc:smapclear:omapc[lear]mapmode-o:omapc:omapclear:mapc[lear]!mapmode-ic:mapc!:mapclear!:imapc[lear]mapmode-i:imapc:imapclear:lmapc[lear]mapmode-l:lmapc:lmapclear:cmapc[lear]mapmode-c:cmapc:cmapclear:tmapc[lear]mapmode-t:tmapc:tmapclearRemove ALL mappings for the modes where the mapcommand applies.Use the<buffer> argument to remove buffer-localmappings:map-<buffer>Warning: This also removes themac-standard-mappingsand thedos-standard-mappings.:mapmapmode-nvo:nm[ap]mapmode-n:vm[ap]mapmode-v:xm[ap]mapmode-x:sm[ap]mapmode-s:om[ap]mapmode-o:map!mapmode-ic:im[ap]mapmode-i:lm[ap]mapmode-l:cm[ap]mapmode-c:tma[p]mapmode-tList all key mappings for the modes where the mapcommand applies.Note that ":map" and ":map!" areused most often, because they include the other modes.:map{lhs}mapmode-nvo:map_l:nm[ap]{lhs}mapmode-n:nmap_l:vm[ap]{lhs}mapmode-v:vmap_l:xm[ap]{lhs}mapmode-x:xmap_l:sm[ap]{lhs}mapmode-s:smap_l:om[ap]{lhs}mapmode-o:omap_l:map!{lhs}mapmode-ic:map_l!:im[ap]{lhs}mapmode-i:imap_l:lm[ap]{lhs}mapmode-l:lmap_l:cm[ap]{lhs}mapmode-c:cmap_l:tma[p]{lhs}mapmode-t:tmap_lList the key mappings for the key sequencesstartingwith{lhs} in the modes where the map command applies.These commands are used to mapa key or key sequence toastring ofcharacters. You can use this toput command sequences under function keys,translate one key into another, etc. See:mkexrc for how to save andrestore the current mappings.map-ambiguousWhen two mappings start with the same sequence of characters, they areambiguous. Example::imap aa foo:imap aaa barWhen Vim has read "aa",it will need to get another character to be able todecide if "aa" or "aaa" should be mapped. This means that after typing "aa"thatmapping won't get expanded yet, Vimis waiting for another character.If you typea space, then "foo" will get inserted, plus the space. If youtype "a", then "bar" will get inserted.Trailing white spacemap-trailing-whiteThis unmap command does NOT work::map @@ foo:unmap @@ | printBecauseit tries to unmap "@@ ", including the whitespace before the commandseparator "|". Other examples with trailing white space:unmap @@unmap @@ # Vim9 script commentunmap @@ " legacy script commentAn error will be issued, whichis very hard to identify, because the endingwhitespace character in `unmap@@`is not visible.A generic solutionis toput the command separator "|" right after the mappedkeys. After that whitespace anda comment may follow:unmap @@| # Vim9 script commentunmap @@| " legacy script comment1.2 SPECIAL ARGUMENTS:map-arguments"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and"<unique>" can be used in any order. Theymust appear right after thecommand, before any other arguments.:map-local:map-<buffer>:map-bufferE224E225If the first argument to one of these commandsis "<buffer>" themapping willbe effective in the current buffer only. Example::map <buffer> ,w /[.,;]<CR>Then you can map ",w" to something else in another buffer::map <buffer> ,w /[#&!]<CR>The local buffer mappings are used before the global ones. See<nowait> belowto makea short localmapping not taking effect whena longer global oneexists.The "<buffer>" argument can also be used to clear mappings::unmap <buffer> ,w:mapclear <buffer>Local mappings are also cleared whena bufferis deleted, but not whenitisunloaded. Just like local option values.Also seemap-precedence.:map-<nowait>:map-nowaitWhen defininga buffer-localmapping for "," there may bea globalmappingthat starts with ",". Then you need to type another character for Vim to knowwhether to use the ","mapping or the longer one. To avoid this add the<nowait> argument. Then themapping will be used whenit matches, Vim doesnot wait for more characters to be typed. However, if the characters werealready typed they are used.Note that this works when the<nowait>mapping fully matches andis foundbefore anypartial matches. This works when:- Thereis only one matching buffer-local mapping, since these are always found before global mappings.- Thereis another buffer-localmapping that partly matches, butitis defined earlier (last definedmappingis found first).:map-<silent>:map-silentTo defineamapping which will not be echoed on the command line, add"<silent>"as the first argument. Example::map <silent> ,h /Header<CR>The searchstring will not be echoed when using this mapping. Messages fromthe executed command are still given though. To shut them up too, adda":silent" in the executed command::map <silent> ,h :exe ":silent normal /Header\r"<CR>Note that the effect ofa command might also be silenced, e.g., when themapping selects another entry for command line completionit won't bedisplayed.Prompts will still be given, e.g., for inputdialog().Using "<silent>" for an abbreviationis possible, but will cause redrawing ofthe command line to fail.:map-<special>:map-specialDefineamapping with<>notation for special keys, even though the "<" flagmay appear in'cpoptions'. Thisis useful if the side effect of setting'cpoptions'is not desired. Example::map <special> <F12> /Header<CR>:map-<script>:map-scriptIf the first argument to one of these commandsis "<script>" anditis used todefinea newmapping or abbreviation, themapping will only remap charactersin the{rhs} using mappings that were defined local toa script,starting with"<SID>". This can be used to avoid that mappings from outsideascriptinterfere (e.g., whenCTRL-Vis remapped in mswin.vim), butdo use othermappings defined in the script.Note: ":map<script>" and ":noremap<script>"do the same thing. The"<script>" overrules the command name. Using ":noremap<script>"ispreferred, because it's clearer that remappingis (mostly) disabled.:map-<unique>:map-uniqueE226E227If the first argument to one of these commandsis "<unique>" anditis used todefinea newmapping or abbreviation, the command will fail if themapping orabbreviation already exists. Example::map <unique> ,w /[#&!]<CR>When defininga local mapping, there will also bea check ifa global mapalready exists whichis equal.Example of what will fail::map ,w /[#&!]<CR>:map <buffer> <unique> ,w /[.,;]<CR>If you want to mapa key and then haveitdo whatit was originally mapped to,havea lookatmaparg().:map-<expr>:map-expressionIf the first argument to one of these commandsis "<expr>" anditis used todefinea newmapping or abbreviation, the argumentis an expression. Theexpressionis evaluated to obtain the{rhs} thatis used. Example::inoremap <expr> . <SID>InsertDot()The result of the s:InsertDot() function will be inserted. It could check thetext before the cursor and start omni completion when some conditionis met.Usingascript-local functionis preferred, to avoid polluting the globalnamespace. Use<SID> in the RHS so that thescript that themapping wasdefined in can be found.Forabbreviationsv:charis set to the character that was typed to triggerthe abbreviation. You can use this to decide how to expand the{lhs}. Youshould not eitherinsert or change the v:char.Incase you want themapping to notdo anything, you can have theexpressionevaluate to an empty string. If something changed that requires Vim togo through the main loop (e.g. to update the display), return "\<Ignore>".Thisis similar to "nothing" but makes Vim return from the loop that waits forinput. Example:func s:OpenPopup() call popup_create(... arguments ...) return "\<Ignore>"endfuncnnoremap <expr> <F3> <SID>OpenPopup()Keep in mind that theexpression may be evaluated when looking fortypeahead, before the previous command has been executed. For example:func StoreColumn() let g:column = col('.') return 'x'endfuncnnoremap <expr> x StoreColumn()nmap ! f!xYou will notice that g:column has the value from before executing "f!",because "x"is evaluated before "f!"is executed.This can be solved byinserting<Ignore> before the character thatisexpression-mapped:nmap ! f!<Ignore>xWhen definingamapping inaVim9 script, theexpression will be evaluatedin the context of that script. This means thatscript-local items can beaccessed in the expression.Be very careful about side effects! Theexpressionis evaluated whileobtaining characters, you may very well make the command dysfunctional.For this reason the followingis blocked:- Changing the buffer texttextlock.- Editing another buffer.- The:normal command.- Moving the cursoris allowed, butitis restored afterwards.If you want themapping todo any of these let the returned charactersdothat, or usea<Cmd>mapping instead.You can use getchar(),it consumes typeahead if thereis any. E.g., if youhave these mappings: inoremap <expr> <C-L> nr2char(getchar()) inoremap <expr> <C-L>x "foo"If you now typeCTRL-L nothing happens yet, Vim needs the next character todecide whatmapping to use. If you type 'x' the secondmappingis used and"foo"is inserted. If you type any other key the firstmappingis used,getchar() gets the typed key and returns it.Hereis an example that insertsalist number that increases:let counter = 0inoremap <expr> <C-L> ListItem()inoremap <expr> <C-R> ListReset()func ListItem() let g:counter += 1 return g:counter .. '. 'endfuncfunc ListReset() let g:counter = 0 return ''endfuncCTRL-L inserts the next number,CTRL-R resets the count.CTRL-R returns anempty string, so that nothingis inserted.Note that using 0x80asa single byte before other text does not work,it willbe seenasa special key.<Cmd>:map-cmdThe special text<Cmd> beginsa "commandmapping",it executes the commanddirectly withoutchanging modes. Where you might use ":...<CR>" in the{rhs} ofa mapping, you can instead use "<Cmd>...<CR>".Example:noremap x <Cmd>echo mode(1)<CR>Thisis more flexible than:<C-U> inVisual andOperator-pending mode, or<C-O>: inInsert mode, because the commands are executed directly in thecurrent mode, instead of always going toNormal mode.Visual modeispreserved, so tricks withgv are not needed. Commands can be invokeddirectly inCommand-line mode (which would otherwise requiretimer hacks).Example of using<Cmd> halfwayInsert mode:nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc>Unlike<expr> mappings, there are no special restrictions on the<Cmd>command:itis executedas if an (unrestricted)autocommand was invoked.<ScriptCmd><ScriptCmd>is like<Cmd> but sets the context to thescript themapping wasdefined in, for the duration of the command execution. Thisis especiallyuseful forVim9 script. It also works to access an import, whichis usefulinaplugin using a, possibly autoloaded, script:vim9scriptimport autoload 'implementation.vim' as implnnoremap <F4> <ScriptCmd>impl.DoTheWork()<CR>No matter where<F4>is typed, the "impl" import will be found in thescriptcontext of where themapping was defined. When it's anautoload import,as inthe example, the "implementation.vim"script will only be loaded once<F4>istyped, not when themappingis defined.Without<ScriptCmd> using "s:impl" would result in "E121: Undefined variable".Note:- Because<Cmd> and<ScriptCmd> avoid mode-changesit does not triggerCmdlineEnter andCmdlineLeave events, because no user interactionis expected.- For the same reason,keycodes like<C-R><C-W> are interpretedas plain, unmapped keys.- The commandis not echo'ed, no need for<silent>.- The{rhs}is not subject toabbreviations nor to other mappings, even if themappingis recursive.- InVisual mode you can useline('v') andcol('v') to get oneend of theVisual area, the cursorisat the other end.E1255E1136<Cmd> and<ScriptCmd> commandsmust terminate, that is, theymust be followedby<CR> in the{rhs} of themapping definition.Command-line modeis neverentered. To usea literal<CR> in the{rhs}, use<lt>.1.3 MAPPING AND MODES:map-modesmapmode-nvomapmode-nmapmode-vmapmode-oThere are seven sets of mappings- ForNormal mode: When typing commands.- ForVisual mode: When typing commands while theVisual areais highlighted.- ForSelect mode: likeVisual mode but typing text replaces the selection.- ForOperator-pending mode: When anoperatoris pending (after "d", "y", "c", etc.). See below:omap-info.- ForInsert mode. These are also used inReplace mode.- ForCommand-line mode: When enteringa ":" or "/" command.- For Terminal mode: When typing ina:terminal buffer.Special case: While typingacount fora command inNormal mode,mapping zerois disabled. This makesit possible to map zero without makingit impossibleto typeacount witha zero.map-overviewmap-modesOverview of which map command works in which mode. More details below. COMMANDS MODES:map:noremap:unmap Normal, Visual, Select,Operator-pending:nmap:nnoremap:nunmapNormal:vmap:vnoremap:vunmapVisual andSelect:smap:snoremap:sunmapSelect:xmap:xnoremap:xunmapVisual:omap:onoremap:ounmapOperator-pending:map!:noremap!:unmap!Insert andCommand-line:imap:inoremap:iunmapInsert:lmap:lnoremap:lunmap Insert, Command-line, Lang-Arg:cmap:cnoremap:cunmapCommand-line:tmap:tnoremap:tunmapTerminal-JobSame information ina table:map-table Mode | Norm | Ins | Cmd | Vis | Sel | Opr | Term | Lang |Command +------+-----+-----+-----+-----+-----+------+------+[nore]map | yes |- |- | yes | yes | yes |- |- |n[nore]map | yes |- |- |- |- |- |- |- |[nore]map! |- | yes | yes |- |- |- |- |- |i[nore]map |- | yes |- |- |- |- |- |- |c[nore]map |- |- | yes |- |- |- |- |- |v[nore]map |- |- |- | yes | yes |- |- |- |x[nore]map |- |- |- | yes |- |- |- |- |s[nore]map |- |- |- |- | yes |- |- |- |o[nore]map |- |- |- |- |- | yes |- |- |t[nore]map |- |- |- |- |- |- | yes |- |l[nore]map |- | yes | yes |- |- |- |- | yes | COMMANDS MODES Normal Visual+Select Operator-pending:map:noremap:unmap:mapclear yes yes yes:nmap:nnoremap:nunmap:nmapclear yes--:vmap:vnoremap:vunmap:vmapclear- yes-:omap:onoremap:ounmap:omapclear-- yes:nunmap can also be used outside ofa monastery.mapmode-xmapmode-sSome commands work both inVisual andSelect mode, some in only one.Notethat quite often "Visual"is mentioned where bothVisual andSelect modeapply.Select-mode-mappingNOTE: Mappinga printable character inSelect mode may confuse the user. It'sbetter to explicitly use:xmap and:smap for printable characters. Or use:sunmap after defining the mapping. COMMANDS MODES Visual Select:vmap:vnoremap:vunmap:vmapclear yes yes:xmap:xnoremap:xunmap:xmapclear yes-:smap:snoremap:sunmap:smapclear- yesmapmode-icmapmode-imapmode-cmapmode-lSome commands work both inInsert mode andCommand-line mode, some not: COMMANDS MODES Insert Command-lineLang-Arg:map!:noremap!:unmap!:mapclear! yes yes-:imap:inoremap:iunmap:imapclear yes--:cmap:cnoremap:cunmap:cmapclear- yes-:lmap:lnoremap:lunmap:lmapclear yes* yes* yes** If'iminsert'is 1, seelanguage-mapping below.The originalVi did not have separate mappings forNormal/Visual/Operator-pending mode and for Insert/Command-line mode.Therefore the ":map" and ":map!" commands enter and display mappings forseveral modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and":imap" commands to enter mappings for each mode separately.mapmode-tTheterminal mappings are used inaterminal window, when typing keys for thejob running in the terminal. Seeterminal-typing.omap-infoOperator-pending mappings can be used to defineamovement command that can beused with any operator. Simple example::omap { wmakes "y{" work like "yw" and "d{" like "dw".To ignore thestarting cursor position and select different text, you can havethe omap startVisual mode to select the text to be operated upon. Examplethat operates ona function name in the current line:onoremap <silent> F :<C-U>normal! 0f(hviw<CR>TheCTRL-U (<C-U>)is used to remove the range that Vim may insert. TheNormal mode commands find the first '(' character and select the firstwordbefore it. That usuallyis the function name.To enteramapping forNormal andVisual mode, but notOperator-pending mode,first defineit for all three modes, then unmapit forOperator-pending mode::map xx something-difficult:ounmap xxLikewise foramapping forVisual andOperator-pending mode orNormal andOperator-pending mode.language-mapping":lmap" definesamapping that applies to:-Insert mode-Command-line mode- when enteringa searchpattern- the argument of the commands that accepta text character, suchas "r" and "f"- for theinput() lineGenerally: Whenevera characteris to be typed thatis part of the text in thebuffer, nota Vim command character. "Lang-Arg" isn't really another mode,it's just used here for this situation. The simplest way to loada set of related language mappingsis by using the'keymap' option. See45.5. InInsert mode and inCommand-line mode the mappings can be disabled withtheCTRL-^ commandi_CTRL-^c_CTRL-^. These commands change the value ofthe'iminsert' option. Whenstarting to entera normal command line (notasearch pattern) the mappings are disabled untilaCTRL-^is typed. The statelast usedis remembered forInsert mode and Search patterns separately. Thestate forInsert modeis also used when typinga characteras an argument tocommand like "f" or "t". Language mappings will never be applied to already mapped characters. Theyare only used for typed characters. This assumes that the languagemappingwas already done when typing the mapping.1.4 LISTING MAPPINGSmap-listingWhen listing mappings the characters in the first two columns are: CHARMODE<Space>Normal, Visual,Select andOperator-pendingnNormalvVisual andSelectsSelectxVisualoOperator-pending!Insert andCommand-lineiInsertl":lmap" mappings for Insert,Command-line and Lang-ArgcCommand-linetTerminal-JobJust before the{rhs}a special character can appear:*indicates thatitis not remappable&indicates that onlyscript-local mappings are remappable@indicatesa buffer-localmappingEverything from the first non-blank after{lhs} up to theend of the line(or'|')is considered to be part of{rhs}. This allows the{rhs} toendwitha space.Note: When using mappings forVisual mode, you can use the "'<" mark, whichis the start of the last selectedVisual area in the current buffer'<.The:filter command can be used to select what mappings to list. Thepatternis matched against the{lhs} and{rhs} in the raw form.While mappings are being listed,itis not possible to add or clear mappings,e.g. fromatimer callback.E1309:map-verboseWhen'verbose'is non-zero, the detected and used'keyprotocol' value will bedisplayed in the first line. Alsoa key map will also display whereit waslast defined. Example::verbose map <C-W>*Kitty keyboard protocol: Clearedn <C-W>* * <C-W><C-S>*Last set from /home/abcd/.vimrcSee:verbose-cmd for more information.1.5 MAPPING SPECIAL KEYS:map-special-keysThere are three ways to mapa special key:1. The Vi-compatible method: Map the key code. Often thisisa sequence that starts with<Esc>. To enteramapping like this you type ":map " and then you have to typeCTRL-V before hitting the function key.Note that when the key code for the keyis in thetermcap (the t_ options),it will automatically be translated into the internal code and become the second way ofmapping (unless the 'k' flagis included in'cpoptions').2. The secondmethodis to use the internal code for the function key. To enter suchamapping typeCTRL-K and then hit the function key, or use the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc. (see table of keyskey-notation, all keys from<Up> can be used). The first ten function keys can be defined in two ways: Just the number, like "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0" refers to function key 10, defined with option 't_f10', which may be function key zero on some keyboards. The<> form cannot be used when'cpoptions' includes the '<' flag.3. Use thetermcap entry, with the form<t_xx>, where "xx"is the name of thetermcap entry. Anystring entry can be used. For example: :map <t_F3> G Maps function key 13 to "G". This does not work if'cpoptions' includes the '<' flag.The advantage of the second and thirdmethodis that themapping will work ondifferent terminals without modification (the function key will betranslated into the same internal code or the actual key code, no matter whatterminal you are using. Thetermcapmust be correct for this to work, and youmust use the same mappings).DETAIL: Vim first checks ifa sequence from the keyboardis mapped. Ifitisn't theterminal key codes are tried (seeterminal-options). Ifaterminal codeis founditis replaced with the internal code. Then the checkforamappingis done again (so you can map an internal code to somethingelse). Whatis written into thescript file depends on whatis recognized.If theterminal key code was recognizedasamapping the key code itselfiswritten to thescript file. Ifit was recognizedasaterminal code theinternal codeis written to thescript file.1.6 SPECIAL CHARACTERS:map-special-charsmap_backslashmap-backslashNote that onlyCTRL-Vis mentioned hereasa special character for mappingsand abbreviations. When'cpoptions' does not contain 'B',abackslash canalso be used likeCTRL-V. The<>notation can be fully used then<>. Butyou cannot use "<C-V>" likeCTRL-V toescape the special meaning of whatfollows.To mapa backslash, or useabackslash literally in the{rhs}, the specialsequence "<Bslash>" can be used. This avoids the need to double backslasheswhen using nested mappings.map_CTRL-Cmap-CTRL-CUsingCTRL-C in the{lhs}is possible, butit will only work when Vimiswaiting fora key, not when Vimis busy with something. When Vimis busyCTRL-C interrupts/breaks the command.When using theGUI version onMS-WindowsCTRL-C can be mapped to allowa Copycommand to the clipboard. UseCTRL-Break to interrupt Vim.map_space_in_lhsmap-space_in_lhsTo includeaspace in{lhs} precedeit withaCTRL-V (type twoCTRL-Vs foreach space).map_space_in_rhsmap-space_in_rhsIf you wanta{rhs} that starts witha space, use "<Space>". To be fullyVicompatible (but unreadable) don't use the<> notation, precede{rhs} withasingleCTRL-V (you have to typeCTRL-V two times).map_empty_rhsmap-empty-rhsYou can create an empty{rhs} by typing nothing aftera singleCTRL-V (youhave to typeCTRL-V two times). Unfortunately, you cannotdo this inavimrcfile.<Nop>An easier way to getamapping that doesn't produce anything,is to use"<Nop>" for the{rhs}. This only works when the<>notationis enabled.For example, to make sure that function key 8 does nothingat all::map <F8> <Nop>:map! <F8> <Nop>map-multibyteItis possible to mapmultibyte characters, but only the whole character. Youcannot map the first byte only. This was done to prevent problems in thisscenario::set encoding=latin1:imap <M-C> foo:set encoding=utf-8Themapping for<M-C>is defined with the latin1 encoding, resulting ina 0xc3byte. If you type the character á (0xe1<M-a>) inUTF-8 encoding thisis thetwo bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then orotherwiseit would be impossible to type the á character.<Leader>mapleaderTo defineamapping which uses the "g:mapleader" variable, the specialstring"<Leader>" can be used. Itis replaced with thestring value of"g:mapleader". If "g:mapleader"is not set or empty,abackslashis usedinstead. Example:map <Leader>A oanother line<Esc>Works like:map \A oanother line<Esc>But after (legacy script):let mapleader = ","Or (Vim9 script):g:mapleader = ","It works like:map ,A oanother line<Esc>Note that the value of "g:mapleader"is usedat the moment themappingisdefined. Changing "g:mapleader" after that has no effect for already definedmappings.<LocalLeader>maplocalleader<LocalLeader>is just like<Leader>, except thatit uses "maplocalleader"instead of "mapleader".<LocalLeader>is to be used for mappings which arelocal toa buffer. Example: :map <buffer> <LocalLeader>A oanother line<Esc>Ina globalplugin<Leader> should be used and inafiletypeplugin<LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, ifyou make them different, thereisa smaller chance of mappings from globalplugins to clash with mappings forfiletype plugins. For example, you couldkeep "mapleader"at the default backslash, and set "maplocalleader" to anunderscore.map-<SID>Inascript the special key name "<SID>" can be used to defineamappingthat's local to the script. See<SID> for details.<Plug>The special key name "<Plug>" can be used for an internal mapping, whichisnot to be matched with any key sequence. Thisis useful in pluginsusing-<Plug>.<MouseMove>The special key name "<MouseMove>" can be used to handle mouse movement. Itneeds to be enabled with'mousemoveevent'. Currently only works in the GUI.Thegetmousepos() function can be used to obtain the mouse position.<Char><Char->To mapa character by its decimal,octal or hexadecimal number the<Char>construct can be used:<Char-123>character 123<Char-033>character 27<Char-0x7f>character 127<S-Char-114> character 114 ('r') shifted ('R')Thisis useful to specifya (multibyte) character ina'keymap' file.Upper andlowercase differences are ignored.map-commentsItis not possible toputa comment after these commands, because the'"'characteris considered to be part of the{lhs} or{rhs}. However, one canuse |", since this startsa new, empty command witha comment.map_barmap-barSince the'|' characteris used to separatea map command from the nextcommand, you will have todo something special to includea'|' in{rhs}.There are three methods: use works when example<Bar> '<'is not in'cpoptions':map _l :!ls<Bar> more^M \| 'b'is not in'cpoptions':map _l :!ls \| more^M ^V| always, in Vim andVi:map _l :!ls ^V| more^M(here ^V stands forCTRL-V; to get oneCTRL-V you have to typeit twice; youcannot use the<>notation "<C-V>" here).All three work when you use the default setting for'cpoptions'.When 'b'is present in'cpoptions', "\|" will be recognizedasamappingending ina '\' and then another command. ThisisVi compatible, butillogical when compared to other commands.map_returnmap-returnWhen you haveamapping that contains anEx command, you need toputa lineterminator afterit to haveit executed. The use of<CR>is recommended forthis (see<>). Example: :map _ls :!ls -l %:S<CR>:echo "the end"<CR>To avoidmapping of the characters you type ininsert orCommand-line mode,typeaCTRL-V first. Themapping inInsert modeis disabled if the'paste'optionis on.map-errorNote that when an erroris encountered (that causes an error message or mightcausea beep) the rest of themappingis not executed. Thisis Vi-compatible.Note that the second character (argument) of the commands @zZtTfF[]rm'`"vandCTRL-Xis not mapped. This was done to be able to use all the namedregisters and marks, even when the command with the same name has beenmapped.1.7 WHAT KEYS TO MAPmap-which-keysIf you are going to map something, you will need to choose which key(s) to usefor the{lhs}. You will have to avoid keys that are used for Vim commands,otherwise you would not be able to use those commands anymore. Here area fewsuggestions:- Function keys<F2>,<F3>, etc.. Also the shifted function keys<S-F1>,<S-F2>, etc.Note that<F1>is already used for thehelp command.- Any key with the Alt or Meta key pressed. Depending on your keyboard accented characters may be usedas well.:map-alt-keys- Use the '_' or ',' character and then any other character. The "_" and "," commandsdo exist in Vim (see_ and,), but you probably never use them.- Usea key thatisa synonym for another command. For example:CTRL-P andCTRL-N. Use an extra character to allow more mappings.- The key defined by<Leader> and one or more other keys. Thisis especially useful in scripts.mapleaderSee the file "index" for keys that are not used and thus can be mapped withoutlosing any builtin function. You can also use ":help{key}^D" to find out ifa keyis used for some command. ({key}is the specific key you want to findout about, ^DisCTRL-D).1.8 EXAMPLESmap-examplesA few examples (givenas you type them, for "<CR>" you type four characters;the '<' flagmust not be present in'cpoptions' for this to work). :map <F3> o#include :map <M-g> /foo<CR>cwbar<Esc> :map _x d/END/e<CR> :map! qq quadrillion questionsMultiplyingacountWhen you typeacount before triggeringa mapping, it's like thecount wastyped before the{lhs}. For example, with this mapping: :map <F4> 3wTyping 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words.If you want to multiply counts use theexpression register: :map <F4> @='3w'<CR>The part betweenquotesis theexpression being executed.@=1.9 USING MAPPINGSmap-typingVim will compare what you type with the start ofa mapped sequence. If thereis an incomplete match,it will get more characters until there eitherisacomplete match or until thereis no matchat all. Example: If you map! "qq",the first 'q' will not appear on the screen until you type anothercharacter. Thisis because Vim cannot know if the next character will bea'q' or not. If the'timeout' optionis on (whichis the default) Vim willonly wait for one second (oras longas specified with the'timeoutlen'option). After thatit assumes that the 'q'is to be interpretedas such. Ifyou type slowly, or your systemis slow, reset the'timeout' option. Then youmight want to set the'ttimeout' option.map-precedenceBuffer-local mappings (defined using:map-<buffer>) take precedence overglobal mappings. Whena buffer-localmappingis the sameasa global mapping,Vim will use the buffer-local mapping. In addition, Vim will usea completemapping immediately ifit was defined with<nowait>, even ifa longermappinghas the same prefix. For example, given the following two mappings: :map <buffer> <nowait> \a :echo "Local \a"<CR> :map \abc :echo "Global \abc"<CR>When typing \a the buffer-localmapping will be used immediately. Vim willnot wait for more characters to see if the user might be typing \abc.map-keys-failsThere are situations where key codes might not be recognized:- Vim can only read part of the key code. Mostly thisis only the first character. This happens on someUnix versions in an xterm.- The key codeis after character(s) that are mapped. E.g., "<F1><F1>" or "g<F1>".The resultis that the key codeis not recognized in this situation, and themapping fails. There are two actions needed to avoid this problem:- Remove the 'K' flag from'cpoptions'. This will make Vim wait for the rest of the characters of the function key.- When using<F1> to<F4> the actual key code generated may correspond to<xF1> to<xF4>. There are mappings from<xF1> to<F1>,<xF2> to<F2>, etc., but these are not recognized after another halfa mapping. Make sure the key codes for<F1> to<F4> are correct::set <F1>=<type CTRL-V><type F1> Type the<F1>as four characters. The part after the "="must be done with the actual keys, not the literal text.Another solutionis to use the actual key code in themapping for the secondspecial key::map <F1><Esc>OP :echo "yes"<CR>Don't typea real<Esc>, Vim will recognize the key code and replaceit with<F1> anyway.Another problem may be that when keeping ALT or Meta pressed theterminalprepends ESC instead of setting the 8th bit. See:map-alt-keys.recursive_mappingIf you include the{lhs} in the{rhs} you havea recursive mapping. When{lhs}is typed,it will be replaced with{rhs}. When the{lhs} whichisincluded in{rhs}is encounteredit will be replaced with{rhs}, and so on.This makesit possible to repeata command an infinite number of times. Theonly problemis that the only way to stop thisis by causing an error. Themacros to solvea maze uses this, look there for an example. Thereis oneexception: If the{rhs} starts with{lhs}, the first characteris not mappedagain (thisisVi compatible).For example: :map ab abcdwill execute the "a" command andinsert "bcd" in the text. The "ab" in the{rhs} will not be mapped again.If you want to exchange the meaning of two keys you should use the:noremapcommand. For example: :noremap k j :noremap j kThis will exchange the cursor up and down commands.With the normal:map command, when the'remap' optionis on,mapping takesplace until the textis found not to bea part ofa{lhs}. For example, ifyou use: :map x y :map y xVim will replacex with y, and theny with x, etc. When this has happened'maxmapdepth' times (default 1000), Vim will give the error message"recursivemapping".:map-undoIf you include anundo command insidea mapped sequence, this will bring thetext back in the state before executing the macro. Thisis compatible withthe original Vi,as longas thereis only oneundo command in the mappedsequence (having twoundo commands ina mapped sequence did not make sensein the original Vi, you would get back the text before the first undo).1.10 MAPPINGALT-KEYS:map-alt-keysFora readablemapping command the<A-k> form can be used.Note that<A-k>and<A-K> are different, the latter will use an uppercase letter. Actually,<A-K> and<A-S-K> are the same. Instead of "A" you can use "M". If you havean actual Meta modifier key, please see:map-meta-keys.In theGUI Vim handles the Alt key itself, thusmapping keys with ALT shouldalways work. But inaterminal Vim getsa sequence of bytes and has to figureout whether ALT was pressed or not.If theterminal supports themodifyOtherKeys mode andit has been enabled,then Vim can recognize more key combinations, seemodifyOtherKeys below.The Kitty keyboard protocol works ina similar way, seekitty-keyboard-protocol.By default Vim assumes that pressing the ALT key sets the 8th bit ofa typedcharacter. Most decent terminals can work that way, suchas xterm, aterm andrxvt. If your<A-k> mappings don't workit might be that theterminalisprefixing the character with an ESC character. But you can justas well typeESC beforea character, thus Vim doesn't know what happened (except forchecking the delay between characters, whichis not reliable).As of this writing, some mainstream terminals like gnome-terminal and konsoleuse the ESC prefix. There doesn't appeara way to have them use the 8th bitinstead. Xterm should work well by default. Aterm andrxvt should work wellwhen started with the "--meta8" argument. You can also tweak resources like"metaSendsEscape", "eightBitInput" and "eightBitOutput".On the Linux console, this behavior can be toggled with the "setmetamode"command. Bear in mind that not using an ESC prefix could get you in troublewith other programs. You should make sure that bash has the "convert-meta"option set to "on" in order for your Meta keybindings to still work onit(it's the default readline behavior, unless changed by specific systemconfiguration). For that, you can add the line:set convert-meta onto your ~/.inputrc file. If you're creating the file, you might want to use:$include /etc/inputrcas the first line, if that file exists on your system, to keep global options.This may causea problem for entering special characters, suchas the umlaut.Then you should useCTRL-V before that character.Bear in mind that convert-meta has been reported to have troubles when used inUTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can betoggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClickon the terminal; that'sa good last resource incase you want to send ESC whenusing other applications but not when inside Vim.1.11 MAPPINGMETA-KEYS:map-meta-keysMapping keys with the Meta modifier works very similar to using the Alt key.What key on your keyboard produces the Meta modifier depends on your keyboardand configuration.Note thatmapping<M-a> actuallyis for using the Alt key. That can beconfusing! It cannot be changed,it would not be backwards compatible.For the Meta modifier the "T" characteris used. For example, to map Meta-binInsert mode::imap <T-b> terrible1.12 MAPPING SUPER-KEYS or COMMAND-KEYS:map-super-keys:map-cmd-keyThe Super modifieris available inGUI mode (whengui_runningis 1) for gVimon Linux and MacVim onMac OS. If you're ona Mac, this represents the Commandkey, on Linux with theGTKGUIit represents the Super key.The character "D"is used for the Super/ Command modifier.For example, to map Command-b inInsert mode::imap <D-b> barritone1.13 MAPPING INmodifyOtherKeys modemodifyOtherKeysXterm anda few other terminals can beput ina mode where keys with modifiersare sent witha specialescape code. Vim recognizes these codes and can thenmakea difference betweenCTRL-H and Backspace, even when Backspace sends thecharacter 8. And many more special keys, suchasTab andCTRL-I, which cannotbe mapped separately otherwise.For xtermmodifyOtherKeysis enabled in the builtintermcap entry. If thisisnot used you can enablemodifyOtherKeys with these lines in your vimrc: let &t_TI = "\<Esc>[>4;2m" let &t_TE = "\<Esc>[>4;m"This setsmodifyOtherKeys to level 2.Note thatmodifyOtherKeys level 1 doesnot work. Some terminalsdo not support level 2 and then send key codes thatVim will not be able to correctly recognize.Incase themodifyOtherKeys mode causes problems you can disable it: let &t_TI = "" let &t_TE = ""It does not take effect immediately. To have this work without restarting Vimexecutea shell command, e.g.:!ls Orput the lines in yourvimrc.WhenmodifyOtherKeysis enabled you can map<C-[> and <C-S-{>:imap <C-[> [[[imap <C-{> {{{WithoutmodifyOtherKeys<C-[> and<C-{> are indistinguishable from Esc.Note that<C-{>is used and not <C-S-[> or <C-S-{>. This works on mostkeyboards. Similarly,<C-}>is used instead of <C-S-]> or <C-S-}> and<C-|> instead of <C-S-\> or <C-S-|>.Note that'|' hasa special meaning inamapping, seemap-bar.WARNING: if you map<C-[> you may very well break any key codes that startwith Esc. Make sureit comes AFTER other mappings.Starting with xterm version 377 Vim can detect themodifyOtherKeys state byrequesting it. For this the't_RK'termcap entryis used. When the responseis found then Vim will know whethermodifyOtherKeys level 2is enabled, andhandle mappings accordingly.Before version 377 Vim automatically detects if themodifyOtherKeys mode wasenabled whenit spots anescape sequence thatmust have been created by it.To see if Vim detected such anescape sequence use `:verbose map`, the firstline will then show "Seen modifyOtherKeys:true" (possibly translated).This automatic detection depends on receiving anescape codestarting with"<1b>[27;". Thisis the normal way xterm sends these key codes. However, iftheformatOtherKeys resourceis set another formis used thatis notrecognized, therefore youmust not set formatOtherKeys.A known side effectis that inInsert mode the rawescape sequenceis insertedafter theCTRL-V key. This can be used to check whethermodifyOtherKeysisenabled: InInsert mode typeCTRL-SHIFT-VCTRL-V, if you get one byte thenmodifyOtherKeysis off, if you get<1b>[27;5;118~ thenitis on.Note that xterm up to version 376 hasa bug that makes Shift-Esc sendaregular Esc code, the Shift modifieris dropped.When the'esckeys' optionis off, thenmodifyOtherKeys will be disabled inInsert mode to avoid every key witha modifier causingInsert mode to end.1.14 MAPPING WITH KITTY KEYBOARD PROTOCOLkitty-keyboard-protocolIf the value of'term' contains "kitty" then Vim will send out anescapesequence to enable the Kitty keyboard protocol. This can be changed with the'keyprotocol' option.Like modifyOtherKeys, this will makeit possible to distinguish between morekeys with modifiers. Also, this protocol sends anescape sequence for the Esckey, so that Vim does not need to usea timeout to know whether receiving anEsc character means the Esc key was pressed or it's the start of anescapesequence.Vim automatically detects if the Kitty keyboard protocol was enabled whenitspots the response to the status request (this should be part of thet_TItermcap entry). To see if Vim detected such anescape sequence use::verbose mapThe first line will then show "Kitty keyboard protocol:{value}" (possiblytranslated). The meaning of{value}:Unknownno status received yetOffprotocolis not usedOnprotocolis usedDisabledprotocol was used but expected to have been disabledby't_TE'Clearedprotocol expected to have been disabled by't_TE',previous stateis unknown1.15 MAPPING AN OPERATOR:map-operatorAnoperatoris used beforea{motion} command. To define your ownoperatoryoumust createamapping that first sets the'operatorfunc' option and theninvoke theg@ operator. After the user types the{motion} command thespecified function will be called.g@E774E775g@{motion}Call the function set by the'operatorfunc' option.The'[markis positionedat the start of the textmoved over by{motion}, the']mark on the lastcharacter of the text.The functionis called with oneString argument: "line"{motion} waslinewise "char"{motion} wascharacterwise "block"{motion} wasblockwise-visualThe type can be forced, seeforced-motion.{not available when compiled without the+evalfeature}Hereis an example that counts the number of spaces with<F4>:nnoremap <expr> <F4> CountSpaces()xnoremap <expr> <F4> CountSpaces()" doubling <F4> works on a linennoremap <expr> <F4><F4> CountSpaces() .. '_'function CountSpaces(context = {}, type = '') abort if a:type == '' let context = #{ \ dot_command: v:false, \ extend_block: '', \ virtualedit: [&l:virtualedit, &g:virtualedit], \ } let &operatorfunc = function('CountSpaces', [context]) set virtualedit=block return 'g@' endif let save = #{ \ clipboard: &clipboard, \ selection: &selection, \ virtualedit: [&l:virtualedit, &g:virtualedit], \ register: getreginfo('"'), \ visual_marks: [getpos("'<"), getpos("'>")], \ } try set clipboard= selection=inclusive virtualedit= let commands = #{ \ line: "'[V']", \ char: "`[v`]", \ block: "`[\<C-V>`]", \ }[a:type] let [_, _, col, off] = getpos("']") if off != 0 let vcol = getline("'[")->strpart(0, col + off)->strdisplaywidth() if vcol >= [line("'["), '$']->virtcol() - 1 let a:context.extend_block = '$' else let a:context.extend_block = vcol .. '|' endif endif if a:context.extend_block != '' let commands ..= 'oO' .. a:context.extend_block endif let commands ..= 'y' execute 'silent noautocmd keepjumps normal! ' .. commands echomsg getreg('"')->count(' ') finally call setreg('"', save.register) call setpos("'<", save.visual_marks[0]) call setpos("'>", save.visual_marks[1]) let &clipboard = save.clipboard let &selection = save.selection let [&l:virtualedit, &g:virtualedit] = get(a:context.dot_command ? save : a:context, 'virtualedit') let a:context.dot_command = v:true endtryendfunctionAn<expr>mappingis used to be able tofetch any prefixedcount and register.This also avoids usinga command line, which would triggerCmdlineEnter andCmdlineLeave autocommands.Note that the'selection' optionis temporarily set to "inclusive" to be abletoyank exactly the right text by usingVisual mode from the'[ to the']mark.Alsonote that the'clipboard' optionis temporarily emptied to avoidclobbering the"* or"+ registers, if its value contains the itemunnamedorunnamedplus.Themode() function will return the stateasit will be after applying theoperator.Hereis an example for usingalambda function to createa normal-modeoperator to addquotes around text in the current line:nnoremap <F4> <Cmd>let &opfunc='{t ->\ getline(".")\ ->split("\\zs")\ ->insert("\"", col("'']"))\ ->insert("\"", col("''[") - 1)\ ->join("")\ ->setline(".")}'<CR>g@==============================================================================2.AbbreviationsabbreviationsAbbreviationsAbbreviations are used inInsert mode,Replace mode andCommand-line mode.If you enteraword thatis an abbreviation,itis replaced with theworditstands for. This can be used to save typing for often used long words. Andyou can useit to automatically correct obvious spelling errors.Examples::iab ms Microsoft:iab tihs thisThere are three types of abbreviations:full-id The "full-id" type consists entirely of keyword characters (letters and characters from'iskeyword' option). Thisis the most common abbreviation. Examples: "foo", "g3", "-1"end-id The "end-id" type ends ina keyword character, but all the other characters are not keyword characters. Examples: "#i", "..f", "$/7"non-id The "non-id" type ends ina non-keyword character, the other characters may be of any type, excludingspace and tab. {this typeis not supported by Vi} Examples: "def#", "4/7$"Examples of strings that cannot be abbreviations: "a.b", "#def", "ab", "_$r"An abbreviationis only recognized when you typea non-keyword character.This can also be the<Esc> that endsInsert mode or the<CR> that endsacommand. The non-keyword character which ends the abbreviationis insertedafter the expanded abbreviation. An exception to thisis the character<C-]>,whichis used to expand an abbreviation withoutinserting any extracharacters.Example: :ab hhhello "hh<Space>"is expanded to "hello<Space>" "hh<C-]>"is expanded to "hello"The characters before the cursormust match the abbreviation. Each type hasan additional rule:full-id In front of the matchisa non-keyword character, or thisis where the line or insertion starts. Exception: When the abbreviationis only one character,itis not recognized if thereisa non-keyword character in front of it, other thanaspace ora tab. However, for the command line "'<,'>" (or any other marks)is ignored,as if the command line starts after it.end-id In front of the matchisa keyword character, oraspace ora tab, or thisis where the line or insertion starts.non-id In front of the matchisa space,tab or the start of the line or the insertion.Examples: ({CURSOR}is where you typea non-keyword character) :ab foo four old otters" foo{CURSOR}"is expanded to " four old otters"" foobar{CURSOR}"is not expanded"barfoo{CURSOR}"is not expanded :ab #i #include"#i{CURSOR}"is expanded to "#include"">#i{CURSOR}"is not expanded :ab ;; <endofline>"test;;"is not expanded"test ;;"is expanded to "test<endofline>"To avoid the abbreviation inInsert mode: TypeCTRL-V before the characterthat would trigger the abbreviation. E.g.CTRL-V<Space>. Or type part ofthe abbreviation, exitinsert mode with<Esc>, re-enterinsert mode with "a"and type the rest.To avoid the abbreviation inCommand-line mode: TypeCTRL-V twice somewhere inthe abbreviation to avoidit to be replaced.ACTRL-V in front ofa normalcharacteris mostly ignored otherwise.Itis possible to move the cursor after an abbreviation: :iab if if ()<Left>This does not work if'cpoptions' includes the '<' flag.<>You can evendo more complicated things. For example, to consume thespacetyped after an abbreviation: func Eatchar(pat) let c = nr2char(getchar(0)) return (c =~ a:pat) ? '' : c endfunc iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR>There are no default abbreviations.Abbreviations are never recursive. You can use ":abf f-o-o" without anyproblem. Butabbreviations can be mapped. {some versions ofVi supportrecursive abbreviations, for no apparent reason}Abbreviations are disabled if the'paste' optionis on.:abbreviate-local:abbreviate-<buffer>Just like mappings,abbreviations can be local toa buffer. Thisis mostlyused inafiletype-plugin file. Example foraCplugin file::abb <buffer> FF for (i = 0; i < ; ++i):ab:abbreviate:ab[breviate]list all abbreviations. The character in the firstcolumn indicates the mode where the abbreviationisused: 'i' forinsert mode, 'c' forCommand-linemode, '!' for both. These are the sameas formappings, seemap-listing.:abbreviate-verboseWhen'verbose'is non-zero, listing an abbreviation will also display whereitwas last defined. Example::verbose abbreviate! teh theLast set from /home/abcd/vim/abbr.vimSee:verbose-cmd for more information.:ab[breviate]{lhs}list theabbreviations that start with{lhs}You may need toinsertaCTRL-V (typeit twice) toavoid thata typed{lhs}is expanded, sincecommand-lineabbreviations apply here.:ab[breviate] [<expr>] [<buffer>]{lhs}{rhs}add abbreviation for{lhs} to{rhs}. If{lhs} alreadyexisteditis replaced with the new{rhs}.{rhs} maycontain spaces.See:map-<expr> for the optional<expr> argument.See:map-<buffer> for the optional<buffer> argument.:una:unabbreviate:una[bbreviate] [<buffer>]{lhs}Remove abbreviation for{lhs} from the list. If noneis found, removeabbreviations in which{lhs} matcheswith the{rhs}. Thisis done so that you can evenremoveabbreviations after expansion. To avoidexpansioninsertaCTRL-V (typeit twice).:norea:noreabbrev:norea[bbrev] [<expr>] [<buffer>][lhs][rhs]Sameas ":ab", but no remapping for this{rhs}.:ca:cab:cabbrev:ca[bbrev] [<expr>] [<buffer>][lhs][rhs]Sameas ":ab", but forCommand-line mode only.:cuna:cunabbrev:cuna[bbrev] [<buffer>]{lhs}Sameas ":una", but forCommand-line mode only.:cnorea:cnoreabbrev:cnorea[bbrev] [<expr>] [<buffer>][lhs][rhs]sameas ":ab", but forCommand-line mode only and noremapping for this{rhs}:ia:iabbrev:ia[bbrev] [<expr>] [<buffer>][lhs][rhs]Sameas ":ab", but forInsert mode only.:iuna:iunabbrev:iuna[bbrev] [<buffer>]{lhs}Sameas ":una", but forinsert mode only.:inorea:inoreabbrev:inorea[bbrev] [<expr>] [<buffer>][lhs][rhs]Sameas ":ab", but forInsert mode only and noremapping for this{rhs}.:abc:abclear:abc[lear] [<buffer>]Remove all abbreviations.:iabc:iabclear:iabc[lear] [<buffer>]Remove allabbreviations forInsert mode.:cabc:cabclear:cabc[lear] [<buffer>]Remove allabbreviations forCommand-line mode.using_CTRL-VItis possible to use special characters in the rhs of an abbreviation.CTRL-V has to be used to avoid the special meaning of most non printablecharacters. How manyCTRL-Vs need to be typed depends on how you enter theabbreviation. This also applies to mappings. Let's use an example here.Suppose you want to abbreviate "esc" to enter an<Esc> character. When youtype the ":ab" command in Vim, you have to enter this: (here ^VisaCTRL-Vand ^[is<Esc>)You type:ab esc ^V^V^V^V^V^[All keyboard inputis subjected to ^Vquote interpretation, sothe first, third, and fifth ^V characters simply allow the second,and fourth ^Vs, and the ^[, to be entered into the command-line.You see:ab esc ^V^V^[The command-line contains two actual ^Vs before the ^[. Thisishowit should appear in your.exrc file, if you choose togo thatroute. The first ^Vis there toquote the second ^V; the:abcommand uses ^Vas its ownquote character, so you can include quotedwhitespace or the | character in the abbreviation. The:ab commanddoesn'tdo anything special with the ^[ character, soit doesn't needto be quoted. (Although quoting isn't harmful; that's why typing 7[but not 8!] ^Vs works.)Stored as: esc ^V^[After parsing, the abbreviation's short form("esc") and long form(the two characters "^V^[") are stored in the abbreviation table.If you give the:ab command with no arguments, thisis how theabbreviation will be displayed.Later, when the abbreviationis expanded because the user typed intheword "esc", the long formis subjected to the same type of^V interpretationas keyboard input. So the ^V protects the ^[character from being interpretedas the "exitInsert mode" character.Instead, the ^[is inserted into the text.Expands to: ^[[example given by Steve Kirkendall]==============================================================================3. Local mappings andfunctionsscript-localWhen using several Vimscript files, thereis the danger that mappings andfunctions used in onescript use the same nameas in other scripts. To avoidthis, they can be made local to the script.<SID><SNR>E81Thestring "<SID>" can be used inamapping or menu. This requires that the'<' flagis not present in'cpoptions'. Thisis useful if you haveascript-local function that you want to call fromamapping in the same script. When executing the map command, Vim will replace "<SID>" with the specialkey code<SNR>, followed bya number that's unique for the script, and anunderscore. Example::map <SID>Addwould defineamapping "<SNR>23_Add".When defininga function ina script, "s:" can be prepended to the name tomakeit local to thescript (inVim9scriptfunctions withouta prefix arelocal to the script). But whenamappingis executed from outside ofthe script,it doesn't know in whichscript the function was defined. Toavoid this problem, use "<SID>" instead of "s:". The same translationis doneas for mappings. This makesit possible to definea call to the function ina mapping.Whena local functionis executed,it runs in the context of thescriptit wasdefined in. This means that newfunctions and mappingsit defines can alsouse "s:" or "<SID>" andit will use the same unique numberas when thefunction itself was defined. Also, the "s:var" localscriptvariables can beused.When executing anautocommand ora user command,it will run in the context ofthescriptit was defined in. This makesit possible that the command callsalocal function or usesa local mapping.Incase the valueis used ina context where<SID> cannot be correctlyexpanded, use theexpand() function:let &includexpr = expand('<SID>') .. 'My_includeexpr()'Otherwise, using "<SID>" outside ofascript contextis an error.If you need to get thescript number to use ina complicated script, you canuse this function:func s:ScriptNumber() return matchstr(expand('<SID>'), '<SNR>\zs\d\+\ze_')endfuncThe "<SNR>" will be shown when listingfunctions and mappings. Thisis usefulto find out what they are defined to.The:scriptnames command can be used to see which scripts have been sourcedand what their<SNR> number is.Thisis all{not available when compiled without the |+eval| feature}.==============================================================================4. User-defined commandsuser-commandsItis possible to define your ownEx commands.A user-defined command can actjust likea built-in command (it can havea range or arguments, arguments canbe completedas filenames or buffer names, etc), except that when the commandis executed,itis transformed intoa normalEx command and then executed.For starters: Seesection40.2 in the user manual.E183E841user-cmd-ambiguousAll user defined commandsmust start with anuppercase letter, to avoidconfusion with builtin commands. Exceptions are these builtin commands::Next:XThey cannot be used fora user defined command. ":Print"is also an existingcommand, butitis deprecated and can be overruled.The other characters of the user command can beuppercase letters,lowercaseletters or digits. When using digits,note that other commands that takeanumeric argument may become ambiguous. For example, the command ":Cc2" couldbe the user command ":Cc2" without an argument, or the command ":Cc" withargument "2". Itis advised toputaspace between the command name and theargument to avoid these problems.When usinga user-defined command, the command can be abbreviated. However, ifan abbreviationis not unique, an error will be issued. Furthermore,abuilt-in command will always take precedence.Example::command Rename ...:command Renumber ...:Rena" Means "Rename":Renu" Means "Renumber":Ren" Error - ambiguous:command Paste ...:P" The built-in :PrintItis recommended that full names for user-defined commands are used inscripts.:com[mand]:com:commandList all user-defined commands. When listing commands,the characters in the first columns are:!Command has the -bang attribute "Command has the-register attribute | Command has the -bar attributebCommandis local to current buffer(see below for details on attributes)Thelist can be filtered on command name with:filter, e.g., tolist all commands with "Pyth" inthe name:filter Pyth command:com[mand]{cmd}List the user-defined commands that start with{cmd}:command-verboseWhen'verbose'is non-zero, listinga command will also display whereit waslast defined and any completion argument. Example: :verbose command TOhtmlName Args Range Complete DefinitionTOhtml 0 % :call Convert2HTML(<line1>, <line2>) Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vimSee:verbose-cmd for more information.E174E182:com[mand][!] [{attr}...]{cmd}{repl}Definea user command. The name of the commandis{cmd} and its replacement textis{repl}. Thecommand's attributes (see below) are{attr}. If thecommand already exists, an erroris reported, unlessa!is specified, in whichcase the commandisredefined. Thereis one exception: When sourcingascript again,a command that was previously defined inthatscript will be silently replaced.:delc[ommand]{cmd}:delc:delcommandE184Delete the user-defined command{cmd}.Thisis not allowed while listing commands, e.g. froma timer.E1311:delc[ommand] -buffer{cmd}E1237Delete the user-defined command{cmd} that was definedfor the current buffer.:comc[lear]:comc:comclearDelete all user-defined commands.Command attributescommand-attributesUser-defined commands are treated by Vim just like any otherEx commands. Theycan have arguments, or havea range specified. Arguments are subject tocompletionas filenames, buffers, etc. Exactly how this works depends upon thecommand's attributes, which are specified when the commandis defined.When defininga user command ina script,it will be able to callfunctionslocal to thescript and use mappings local to the script. When the userinvokes the user command,it will run in the context of thescriptit wasdefined in. This matters if<SID>is used ina command.There area number of attributes, split into four categories: argumenthandling, completion behavior, range handling, and special cases. Theattributes are described below, by category.Argument handlingE175E176:command-nargsBy default,a user defined command will take no arguments (and an errorisreported if any are supplied). However,itis possible to specify that thecommand can take arguments, using the -nargs attribute. Valid cases are:-nargs=0 No arguments are allowed (the default)-nargs=1 Exactly one argumentis required,it includes spaces-nargs=* Any number of arguments are allowed (0, 1, or many), separated by whitespace-nargs=?0 or 1 arguments are allowed-nargs=+ Argumentsmust be supplied, but any number are allowedArguments are considered to be separated by (unescaped) spaces or tabs in thiscontext, except when thereis one argument, then the whitespaceis part ofthe argument.Note that arguments are usedas text, notas expressions. Specifically,"s:var" will use thescript-local variable in thescript where the command wasdefined, not whereitis invoked! Example: script1.vim::let s:error = "None":command -nargs=1 Error echoerr <args> script2.vim::source script1.vim:let s:error = "Wrong!":Error s:errorExecuting script2.vim will result in "None" being echoed. Not what youintended! Callinga function may be an alternative.Completion behavior:command-completionE179E180E181:command-completeBy default, the arguments of user defined commandsdo not undergo completion.However, by specifying one or the other of the following attributes, argumentcompletion can be enabled:-complete=arglistfile names in argumentlist-complete=augroupautocmd groups-complete=behave:behave suboptions-complete=breakpoint:breakadd suboptions-complete=bufferbuffer names-complete=colorcolor schemes-complete=commandEx command (and arguments)-complete=compilercompilers-complete=cscope:cscope suboptions-complete=diff_bufferdiff buffer names-complete=dirdirectory names-complete=dir_in_pathdirectory names in'cdpath'-complete=environmentenvironment variable names-complete=eventautocommand events-complete=expressionVimexpression-complete=filefile and directory names-complete=file_in_pathfile and directory names in'path'-complete=filetypefiletype names'filetype'-complete=functionfunction name-complete=helphelp subjects-complete=highlighthighlight groups-complete=history:history suboptions-complete=keymapkeyboard mappings-complete=localelocale names (as output oflocale -a)-complete=mapclearbuffer argument-complete=mappingmapping name-complete=menumenus-complete=messages:messages suboptions-complete=optionoptions-complete=packaddoptional packagepack-add names-complete=runtimefile and directory names in'runtimepath'-complete=scriptnamessourcedscript names-complete=shellcmdShell command-complete=shellcmdlineFirstisa shell command and subsequent onesare filenames. The same behavioras:!cmd-complete=sign:sign suboptions-complete=syntaxsyntax file names'syntax'-complete=syntime:syntime suboptions-complete=tagtags-complete=tag_listfilestags, file names are shown whenCTRL-Dis hit-complete=useruser names-complete=varuservariables-complete=custom,{func} custom completion, defined via{func}-complete=customlist,{func} custom completion, defined via{func}If you specify completion while thereis nothing to complete (-nargs=0, thedefault) then you get errorE1208.Note: That some completion methods might expand environment variables.Custom completion:command-completion-custom:command-completion-customlistE467E468Itis possible to define customized completion schemes via the "custom,{func}"or the "customlist,{func}" completion argument. The{func} part should beafunction with the following signature::function {func}(ArgLead, CmdLine, CursorPos)The function need not use all these arguments. The function should provide thecompletion candidatesas the return value.For the "custom" argument, the function should return the completioncandidates one per line ina newline separated string.E1303For the "customlist" argument, the function should return the completioncandidatesasa Vim List. Non-string items in thelist are ignored.The function arguments are:ArgLeadthe leading portion of the argument currently beingcompleted onCmdLinethe entire command lineCursorPosthe cursor position init (byte index)The function may use these for determining context. For the "custom"argument,itis not necessary tofilter candidates against the (implicitpattern in) ArgLead. Vim willfilter the candidates with itsregexp engineafter function return, and thisis probably more efficient in most cases. If'wildoptions' contains "fuzzy", then the candidates will be filtered usingfuzzy-matching. For the "customlist" argument, Vim will notfilter the returned completion candidates and the user supplied functionshouldfilter the candidates.The following example lists user names toa Finger command :com -complete=custom,ListUsers -nargs=1 Finger !finger <args> :fun ListUsers(A,L,P) : return system("cut -d: -f1 /etc/passwd") :endfunThe following example completes filenames from the directories specified inthe'path' option: :com -nargs=1 -bang -complete=customlist,EditFileComplete\ EditFile edit<bang> <args> :fun EditFileComplete(A,L,P) : return split(globpath(&path, a:A), "\n") :endfunThis example does not work for file names with spaces!Range handlingE177E178:command-range:command-countBy default, user-defined commandsdo not accepta line number range. However,itis possible to specify that the command does takea range (the -rangeattribute), or thatit takes an arbitrarycount value, either in the linenumber position (-range=N, like the:split command) orasa "count"argument (-count=N, like the:Next command). Thecount will then beavailable in the argument with<count>.Possible attributes are:-range Range allowed, defaultis current line-range=% Range allowed, defaultis whole file (1,$)-range=NAcount (default N) whichis specified in the line number position (like:split); allows for zero line number.-count=NAcount (default N) whichis specified either in the line number position, oras an initial argument (like:Next).-count Acts like -count=0Note that -range=N and -count=N are mutuallyexclusive- only one should bespecified.:command-addrItis possible that the special characters in the range like .,$ or% whichby default correspond to the current line, last line and the whole buffer,relate to arguments, (loaded) buffers,windows ortab pages.Possible values are (second columnis the short name used in listing): -addr=linesRange of lines (thisis the default for -range) -addr=arguments argRange for arguments -addr=buffers bufRange forbuffers (also not loaded buffers) -addr=loaded_buffers loadRange for loadedbuffers -addr=windows winRange forwindows -addr=tabstabRange fortab pages -addr=quickfix qfRange forquickfix entries -addr=other?Other kind of range; can use ".", "$" and "%"as with "lines" (thisis the default for-count)Special cases:command-bang:command-bar:command-register:command-buffer:command-keepscriptThere are some special casesas well:-bang The command can takea! modifier (like:q or :w)-bar The command can be followed bya "|" and another command.A "|" inside the command argumentis not allowed then. Also checks fora " to starta comment.-register The first argument to the command can be an optionalregister name (like :del, :put, :yank).-buffer The command will only be available in the current buffer.-keepscript Do not use the location of where the user command was defined forverbose messages, use the location of where the user command was invoked.In the cases of the -count and-register attributes, if the optional argumentis supplied,itis removed from the argumentlist andis available to thereplacement text separately.Note that these arguments can be abbreviated, but thatisa deprecatedfeature. Use the full name for new scripts.Replacement text:command-replThe{repl} argumentis normally one long string, possibly with "|" separatedcommands.A specialcaseis when the argumentis "{", then the followinglines, up toa linestarting with "}" are used andVim9syntax applies.Example::command MyCommand {echo 'hello'g:calledMyCommand = true }E1231Theremust be whitespace before the "{". No nestingis supported, inlinefunctions cannot be used. Commands wherea "|" may appear in the argument,suchas commands with anexpression argument, cannot be followed bya "|" andanother command.If the commandis defined inVim9script (ascript that starts with:vim9script and ina:def function) then{repl} will be executedas inVim9script. Thus this depends on where the commandis defined, not whereitisused.The replacement text{repl} fora user defined commandis scanned for specialescape sequences, using <...> notation. Escape sequences are replaced withvalues from the entered command line, and all other textis copied unchanged.The resultingstringis executedas anEx command. To avoid the replacementuse<lt> in place of the initial <. Thus to include "<bang>" literally use"<lt>bang>".The validescape sequences are<line1><line1>Thestarting line of the command range.<line2><line2>The final line of the command range.<range><range> The number of items in the command range: 0, 1 or 2<count><count>Anycount supplied (as described for the '-range'and '-count' attributes).<bang><bang>(See the '-bang' attribute) Expands toa! if thecommand was executed witha! modifier, otherwiseexpands to nothing.<mods><q-mods>:command-modifiers<mods> The command modifiers, if specified. Otherwise, expands tonothing. Supported modifiers are:aboveleft,:belowright,:botright,:browse,:confirm,:hide,:horizontal,:keepalt,:keepjumps,:keepmarks,:keeppatterns,:leftabove,:lockmarks,:noautocmd,:noswapfile,:rightbelow,:sandbox,:silent,:tab,:topleft,:unsilent,:verbose, and:vertical.Note that:filteris not supported.Examples: command! -nargs=+ -complete=file MyEdit\ for f in expand(<q-args>, 0, 1) |\ exe '<mods> split ' .. f |\ endfor function! SpecialEdit(files, mods)for f in expand(a:files, 0, 1) exe a:mods .. ' split ' .. fendfor endfunction command! -nargs=+ -complete=file Sedit\ call SpecialEdit(<q-args>, <q-mods>)<reg><register><reg>(See the '-register' attribute) The optional register,if specified. Otherwise, expands to nothing.<register>isa synonym for this.<args><args>The command arguments, exactlyas supplied (butasnoted above, anycount orregister can consume someof the arguments, which are then not part of<args>).<lt>A single '<' (Less-Than) character. Thisis needed if youwant to geta literal copy of one of theseescape sequencesinto the expansion- for example, to get<bang>, use<lt>bang>.<q-args>If the first two characters of anescape sequence are "q-" (for example,<q-args>) then the valueis quoted in sucha wayas to makeita valid valuefor use in an expression. This uses the argumentas one single value.When thereis no argument<q-args>is an empty string. See theq-args-example below.<f-args>To allow commands to pass their arguments on toa user-defined function, thereisa special form<f-args>("function args"). This splits the commandargumentsat spaces and tabs,quotes each argument individually, and the<f-args> sequenceis replaced by the comma-separatedlist of quoted arguments.See the Mycmd example below. If no arguments are given<f-args>is removed. To embedwhitespace into an argument of<f-args>, prependa backslash.<f-args> replaces every pair of backslashes (\\) with one backslash.Abackslash followed bya character other than whitespace orabackslashremains unmodified. Also seef-args-example below. Overview:command <f-args>XXab'ab'XX a\b 'a\b'XX a\b'a b'XX a\b'a ', 'b'XX a\\b 'a\b'XX a\\b 'a\', 'b'XX a\\\b 'a\\b'XX a\\\b 'a\ b'XX a\\\\b 'a\\b'XX a\\\\b 'a\\', 'b'XX[nothing]Note that if the "no arguments" situationis to be handled, you have to makesure that the function can be called without arguments. Fora compiledfunction you might want to use variable arguments, seevim9-variable-arguments.Examples for user commands: " Delete everything after here to the end :com Ddel +,$d " Rename the current buffer :com -nargs=1 -bang -complete=file Ren f <args>|w<bang> " Replace a range with the contents of a file " (Enter this all as one line) :com -range -nargs=1 -complete=file Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d " Count the number of lines in the range :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines"f-args-exampleCalla user function (example of<f-args>) :com -nargs=* Mycmd call Myfunc(<f-args>)When executed as::Mycmd arg1 arg2This will invoke::call Myfunc("arg1","arg2")q-args-exampleA more substantial example: :function Allargs(command) : let i = 0 : while i < argc() : if filereadable(argv(i)) : execute "e " .. argv(i) : execute a:command : endif : let i = i + 1 : endwhile :endfunction :command -nargs=+ -complete=command Allargs call Allargs(<q-args>)The command Allargs takes any Vim command(s)as argument and executesit on allfiles in the argument list. Usage example (note use of the "e" flag to ignoreerrors and the "update" command to write modified buffers)::Allargs %s/foo/bar/ge|updateThis will invoke::call Allargs("%s/foo/bar/ge|update") vim:tw=78:ts=8:noet:ft=help:norl: