Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gz gunzip terminfo.src.gz tic terminfo.src
$TERM
The $TERM environment variable must match the terminal you are using!
Otherwise Nvim cannot know what sequences your terminal expects, and weird
or sub-optimal behavior will result (scrolling quirks, wrong colors, etc.).builtin-terms
builtin_terms
If a terminfo database is not available or there is no entry for the current
terminal, Nvim will map $TERM to a builtin entry according to the above
table, or "ansi" if there is no match. For example "TERM=putty-256color" will
be mapped to the builtin "putty" entry. See also tui-colors.if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$'
set notermguicolors
elseif $TERM =~ '^\(tmux\|iterm\|vte\|gnome\)\(-.*\)\?$'
set termguicolors
elseif $TERM =~ '^\(xterm\)\(-.*\)\?$'
if $XTERM_VERSION != ''
set termguicolors
elseif $KONSOLE_PROFILE_NAME != ''
set termguicolors
elseif $VTE_VERSION != ''
set termguicolors
else
set notermguicolors
endif
elseif $TERM =~ ...
... and so forth ...
endif
scroll-region
xterm-scroll-region
Where possible, Nvim will use the terminal's ability to set a scroll region in
order to redraw faster when a window is scrolled. If the terminal's terminfo
description describes an ability to set top and bottom scroll margins, that is
used.tui-input
Nvim uses libtermkey to convert terminal escape sequences to key codes.
terminfo is used first, and CSI sequences not in terminfo (including
extended keys a.k.a. modifyOtherKeys or "CSI u") can also be parsed.
For example, when running Nvim in tmux, this makes Nvim leave Insert mode and
go to the window below:tmux send-keys 'Escape' [ 2 7 u 'C-W' jWhere
'Escape' [ 2 7 u
is an unambiguous "CSI u" sequence for the <Esc>
key.<C-kEnter>
:CSI 57414 ; 5 uand can be used differently from
<C-CR>
in mappings.tui-modifyOtherKeys
tui-csiu
Historically, terminal emulators could not distinguish between certain control
key modifiers and other keys. For example, <C-I>
and <Tab>
are represented the
same way, as are <Esc>
and <C-[>
, <CR>
and <C-M>
, and <NL>
and <C-J>
. This
meant that Nvim also could not map these keys separately.CSI ? u CSI cIf your terminal emulator responds with
CSI ? <flags> uthis means your terminal supports the CSI u encoding and Nvim will tell your terminal to enable it by writing the sequence
CSI > 1 uIf your terminal does not support CSI u then Nvim will instead enable the "modifyOtherKeys" encoding by writing the sequence
CSI > 4 ; 2 mWhen Nvim exits cleanly it will send the corresponding sequence to disable the special key encoding. If Nvim does not exit cleanly then your terminal emulator could be in a bad state. If this happens, simply run "reset".
tui-colors
Nvim uses 256 colours by default, ignoring terminfo for most terminal types,
including "linux" (whose virtual terminals have had 256-colour support since
4.8) and anything claiming to be "xterm". Also when $COLORTERM or $TERM
contain the string "256".true-color
xterm-true-color
Nvim emits true (24-bit) colours in the terminal, if 'termguicolors' is set.xterm-resize
Nvim can resize the terminal display on some terminals that implement an
extension pioneered by dtterm. terminfo does not have a flag for this
extension. So Nvim simply assumes that (all) "dtterm", "xterm", "teraterm",
"rxvt" terminal types, and Konsole, are capable of this.tui-cursor-shape
Nvim will adjust the shape of the cursor from a block to a line when in insert
mode (or as specified by the 'guicursor' option), on terminals that support
it. It uses the same terminfo extensions that were pioneered by tmux for
this: "Ss" and "Se".
Similarly, if you set the cursor highlight group with blend=100, Nvim hides
the cursor through the "cvvis" and "civis" extensions.tui-cursor-tmux
Within tmux it may appear that Nvim is not changing the cursor, but in fact it
is tmux receiving instructions from Nvim to change the cursor and not knowing
what to do in turn. tmux must translate what it receives from Nvim into
whatever control sequence is appropriate for the host terminal. It shares
a common mechanism with Nvim, of using the "Ss" and "Se" capabilities from
terminfo (for the output terminal) if they are present. Unlike Nvim, if they
are not in terminfo you must add them by setting "terminal-overrides" in
~/.tmux.conf .set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q'
<or (alas!) for Konsole 18.07.70 or older, something more complex like:set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007'
hi NonText cterm=NONE ctermfg=NONE
This draws the spaces with the default colours and attributes, which allows the
second pass of drawing to be optimized away. Note: Although in theory the
colours of whitespace are immaterial, in practice they change the colours of
cursors and selections that cross them. This may have a visible, but minor,
effect on some UIs.mouse-mode-table
mouse-overview
Overview of what the mouse buttons do, when 'mousemodel' is "extend":<LeftMouse>
yes end yes
<C-LeftMouse>
yes end yes "CTRL-]" (2)
<S-LeftMouse>
yes no change yes "*" (2) <S-LeftMouse>
<LeftDrag>
yes start or extend (1) no <LeftDrag>
<LeftRelease>
yes start or extend (1) no
<MiddleMouse>
yes if not active no put
<MiddleMouse>
yes if active no yank and put
<RightMouse>
yes start or extend yes
<A-RightMouse>
yes start or extend blockw. yes <A-RightMouse>
<S-RightMouse>
yes no change yes "#" (2) <S-RightMouse>
<C-RightMouse>
no no change no "CTRL-T"
<RightDrag>
yes extend no <RightDrag>
<RightRelease>
yes extend no <RightRelease>
<LeftMouse>
yes (cannot be active) yes
<C-LeftMouse>
yes (cannot be active) yes "CTRL-O^]" (2)
<S-LeftMouse>
yes (cannot be active) yes "CTRL-O*" (2)
<LeftDrag>
yes start or extend (1) no like CTRL-O
(1)
<LeftRelease>
yes start or extend (1) no like CTRL-O
(1)
<MiddleMouse>
no (cannot be active) no put register
<RightMouse>
yes start or extend yes like CTRL-O
<A-RightMouse>
yes start or extend blockw. yes
<S-RightMouse>
yes (cannot be active) yes "CTRL-O#" (2)
<C-RightMouse>
no (cannot be active) no "CTRL-O CTRL-T
"<2-LeftMouse>
yes (cannot be active) no "^]" (jump to help tag)<S-LeftMouse>
yes start or extend (1) no
<A-LeftMouse>
yes start or extend blockw. no <A-LeftMouse>
<RightMouse>
no popup menu no<S-LeftMouse>
yes start or extend (1) no like CTRL-O
(1)
<A-LeftMouse>
yes start or extend blockw. no
<RightMouse>
no popup menu nodouble-click
Double, triple and quadruple clicks are supported when the GUI is active, for
Win32 and for an xterm. For selecting text, extra clicks extend the
selection:
<2-LeftMouse>
triple line <3-LeftMouse>
quadruple rectangular block <4-LeftMouse>
Exception: In a Help window a double click jumps to help for the word that is
clicked on.
A double click on a word selects that word. 'iskeyword' is used to specify
which characters are included in a word. A double click on a character
that has a match selects until that match (like using "v%"). If the match is
an #if/#else/#endif block, the selection becomes linewise.
For MS-Windows and xterm the time for double clicking can be set with the
'mousetime' option. For the other systems this time is defined outside of Vim.
An example, for using a double click to jump to the tag under the cursor::map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR>
Dragging the mouse with a double click (button-down, button-up, button-down
and then drag) will result in whole words to be selected. This continues
until the button is released, at which point the selection is per character
again.CTRL-O
in Insert mode. Select mode is used when the
'selectmode' option contains "mouse".<MiddleRelease>
<MiddleDrag>
Mouse clicks can be mapped. The codes for mouse clicks are:
<LeftMouse>
left pressed set cursor position
<LeftDrag>
left moved while pressed extend selection
<LeftRelease>
left released set selection end
<MiddleMouse>
middle pressed paste text at cursor position
<MiddleDrag>
middle moved while pressed -
<MiddleRelease>
middle released -
<RightMouse>
right pressed extend selection
<RightDrag>
right moved while pressed extend selection
<RightRelease>
right released set selection end
<X1Mouse>
X1 button pressed - X1Mouse
<X1Drag>
X1 moved while pressed - X1Drag
<X1Release>
X1 button release - X1Release
<X2Mouse>
X2 button pressed - X2Mouse
<X2Drag>
X2 moved while pressed - X2Drag
<X2Release>
X2 button release - X2Release
:noremap <MiddleMouse> <LeftMouse><MiddleMouse>
Paste at the position of the middle mouse button click (otherwise the paste
would be done at the cursor position).:noremap <LeftRelease> <LeftRelease>y
Immediately yank the selection, when using Visual mode.:map <X1Mouse> <C-O>
:map <X2Mouse> <C-I>
Map the X1 and X2 buttons to go forwards and backwards in the jump list, see
CTRL-O and CTRL-I.mouse-swap-buttons
To swap the meaning of the left and right mouse buttons::noremap <LeftMouse> <RightMouse>
:noremap <LeftDrag> <RightDrag>
:noremap <LeftRelease> <RightRelease>
:noremap <RightMouse> <LeftMouse>
:noremap <RightDrag> <LeftDrag>
:noremap <RightRelease> <LeftRelease>
:noremap g<LeftMouse> <C-RightMouse>
:noremap g<RightMouse> <C-LeftMouse>
:noremap! <LeftMouse> <RightMouse>
:noremap! <LeftDrag> <RightDrag>
:noremap! <LeftRelease> <RightRelease>
:noremap! <RightMouse> <LeftMouse>
:noremap! <RightDrag> <LeftDrag>
:noremap! <RightRelease> <LeftRelease>