1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
*terminal_emulator.txt* Nvim
NVIM REFERENCE MANUAL by Thiago de Arruda
Terminal emulator *terminal* *terminal-emulator*
Nvim embeds a VT220/xterm terminal emulator based on libvterm. The terminal is
presented as a special buffer type, asynchronously updated from the virtual
terminal as data is received from the program connected to it.
Terminal buffers behave like normal buffers, except:
- With 'modifiable', lines can be edited but not deleted.
- 'scrollback' controls how many lines are kept.
- Output is followed if the cursor is on the last line.
- 'modified' is the default. You can set 'nomodified' to avoid a warning when
closing the terminal buffer.
- 'bufhidden' defaults to "hide".
Type |gO| to see the table of contents.
==============================================================================
Start *terminal-start*
There are 3 ways to create a terminal buffer:
- By invoking the |:terminal| ex command.
- By calling the |termopen()| function.
- By editing a file with a name matching `term://(.{-}//(\d+:)?)?\zs.*`.
For example:
>
:edit term://bash
:vsplit term://top
<
Note: The "term://" pattern is handled by a BufReadCmd handler, so the
|autocmd-nested| modifier is required to use it in an autocmd. >
autocmd VimEnter * nested split term://sh
< This is only mentioned for reference; use |:terminal| instead.
When the terminal starts, the buffer contents are updated and the buffer is
named in the form of `term://{cwd}//{pid}:{cmd}`. This naming scheme is used
by |:mksession| to restore a terminal buffer (by restarting the {cmd}).
==============================================================================
Input *terminal-input*
To send input, enter |Terminal-mode| using any command that would enter "insert
mode" in a normal buffer, such as |i| or |:startinsert|. In this mode all keys
except <C-\><C-N> are sent to the underlying program. Use <C-\><C-N> to return
to normal-mode. |CTRL-\_CTRL-N|
Terminal-mode has its own |:tnoremap| namespace for mappings, this can be used
to automate any terminal interaction.
To map <Esc> to exit terminal-mode: >
:tnoremap <Esc> <C-\><C-n>
To simulate |i_CTRL-R| in terminal-mode: >
:tnoremap <expr> <C-R> '<C-\><C-N>"'.nr2char(getchar()).'pi'
To use `ALT+{h,j,k,l}` to navigate windows from any mode: >
:tnoremap <A-h> <C-\><C-N><C-w>h
:tnoremap <A-j> <C-\><C-N><C-w>j
:tnoremap <A-k> <C-\><C-N><C-w>k
:tnoremap <A-l> <C-\><C-N><C-w>l
:inoremap <A-h> <C-\><C-N><C-w>h
:inoremap <A-j> <C-\><C-N><C-w>j
:inoremap <A-k> <C-\><C-N><C-w>k
:inoremap <A-l> <C-\><C-N><C-w>l
:nnoremap <A-h> <C-w>h
:nnoremap <A-j> <C-w>j
:nnoremap <A-k> <C-w>k
:nnoremap <A-l> <C-w>l
Mouse input has the following behavior:
- If the program has enabled mouse events, the corresponding events will be
forwarded to the program.
- If mouse events are disabled (the default), terminal focus will be lost and
the event will be processed as in a normal buffer.
- If another window is clicked, terminal focus will be lost and nvim will jump
to the clicked window
- If the mouse wheel is used while the mouse is positioned in another window,
the terminal wont lose focus and the hovered window will be scrolled.
==============================================================================
Configuration *terminal-configuration*
Options: 'modified', 'scrollback'
Events: |TermOpen|, |TermClose|
Highlight groups: |hl-TermCursor|, |hl-TermCursorNC|
Terminal sets local defaults for some options, which may differ from your
global configuration.
- 'list' is disabled
- 'wrap' is disabled
- 'relativenumber' is disabled in |Terminal-mode| (and cannot be enabled)
You can change the defaults with a TermOpen autocommand: >
au TermOpen * setlocal list
TERMINAL COLORS ~
The `{g,b}:terminal_color_$NUM` variables control the terminal color palette,
where `$NUM` is the color index between 0 and 255 inclusive. This setting only
affects UIs with RGB capabilities; for normal terminals the color index is
just forwarded. The variables are read only during |TermOpen|.
==============================================================================
Status Variables *terminal-status*
Terminal buffers maintain some information about the terminal in buffer-local
variables:
- *b:term_title* The settable title of the terminal, typically displayed in
the window title or tab title of a graphical terminal emulator. Programs
running in the terminal can set this title via an escape sequence.
- *b:terminal_job_id* The nvim job ID of the job running in the terminal. See
|job-control| for more information.
- *b:terminal_job_pid* The PID of the top-level process running in the
terminal.
These variables are initialized before TermOpen, so you can use them in
a local 'statusline'. Example: >
:autocmd TermOpen * setlocal statusline=%{b:term_title}
<
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:
|
