FILE: C:\Program Files\Git\usr\share\vim\vim91\doc\map.txt
--
*map.txt* For Vim version 9.1. Last change: 2024 Oct 08
VIM REFERENCE MANUAL by Bram Moolenaar
Key mapping, abbreviations and user-defined commands.
This subject is introduced in sections |05.4|, |24.7| and |40.1| of the user
manual.
1. Key mapping |key-mapping|
1.1 MAP COMMANDS |:map-commands|
1.2 Special arguments |:map-arguments|
1.3 Mapping and modes |:map-modes|
1.4 Listing mappings |map-listing|
1.5 Mapping special keys |:map-special-keys|
1.6 Special characters |:map-special-chars|
1.7 What keys to map |map-which-keys|
1.8 Examples |map-examples|
1.9 Using mappings |map-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 in modifyOtherKeys mode |modifyOtherKeys|
1.14 Mapping with Kitty keyboard protocol |kitty-keyboard-protocol|
1.15 Mapping an operator |:map-operator|
2. Abbreviations |abbreviations|
3. Local mappings and functions |script-local|
4. User-defined commands |user-commands|
==============================================================================
1. Key mapping *key-mapping* *mapping* *macro*
Key mapping is used to change the meaning of typed keys. The most common use
is to define a sequence of commands for a function key. Example: >
:map a=strftime("%c")
This appends the current date and time after the cursor (in <> notation |<>|).
1.1 MAP COMMANDS *:map-commands*
There are commands to enter new mappings, remove mappings and list mappings.
See |map-overview| for the various forms of "map" and their relationships with
modes.
{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* *:tmap*
Map the key sequence {lhs} to {rhs} for the modes
where the map command applies. The result, including
{rhs}, is then further scanned for mappings. This
allows for nested and recursive use of mappings.
Note: Trailing spaces are included in the {rhs},
because space is a valid Normal mode command.
See |map-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* *:tnoremap*
Map the key sequence {lhs} to {rhs} for the modes
where the map command applies. Disallow mapping of
{rhs}, to avoid nested and recursive mappings. Often
used to redefine a command.
Note: Keys in {rhs} also won't trigger abbreviation,
with the exception of |i_CTRL-]| and |c_CTRL-]|.
Note: When appears in the {rhs} this part is
always applied even if remapping is 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* *:tunmap*
Remove the mapping of {lhs} for the modes where the
map command applies. The mapping may remain defined
for other modes where it applies.
It also works when {lhs} matches the {rhs} of a
mapping. This is for when an abbreviation applied.
Note: Trailing spaces are included in the {lhs}.
See |map-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* *:tmapclear*
Remove ALL mappings for the modes where the map
command applies.
Use the argument to remove buffer-local
mappings |:map-|
Warning: This also removes the |mac-standard-mappings|
and the |dos-standard-mappings|.
:map |mapmode-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-t|
List all key mappings for the modes where the map
command applies. Note that ":map" and ":map!" are
used 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_l*
List the key mappings for the key sequences starting
with {lhs} in the modes where the map command applies.
These commands are used to map a key or key sequence to a string of
characters. You can use this to put command sequences under function keys,
translate one key into another, etc. See |:mkexrc| for how to save and
restore the current mappings.
*map-ambiguous*
When two mappings start with the same sequence of characters, they are
ambiguous. Example: >
:imap aa foo
:imap aaa bar
When Vim has read "aa", it will need to get another character to be able to
decide if "aa" or "aaa" should be mapped. This means that after typing "aa"
that mapping won't get expanded yet, Vim is waiting for another character.
If you type a space, then "foo" will get inserted, plus the space. If you
type "a", then "bar" will get inserted.
Trailing white space ~
*map-trailing-white*
This unmap command does NOT work: >
:map @@ foo
:unmap @@ | print
Because it tries to unmap "@@ ", including the white space before the command
separator "|". Other examples with trailing white space: >
unmap @@
unmap @@ # Vim9 script comment
unmap @@ " legacy script comment
An error will be issued, which is very hard to identify, because the ending
whitespace character in `unmap @@ ` is not visible.
A generic solution is to put the command separator "|" right after the mapped
keys. After that white space and a comment may follow: >
unmap @@| # Vim9 script comment
unmap @@| " legacy script comment
1.2 SPECIAL ARGUMENTS *:map-arguments*
"", "", "", "", "