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
|
*terminal_emulator.txt* Nvim
NVIM REFERENCE MANUAL by Thiago de Arruda
Terminal emulator *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 mostly like normal 'nomodifiable' buffers, except:
- Plugins can set 'modifiable' to modify text, but lines cannot be deleted.
- 'scrollback' controls how many off-screen lines are kept.
- Terminal output is followed if the cursor is on the last line.
==============================================================================
Spawning *terminal-emulator-spawning*
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 spawns the program, the buffer will start to mirror the
terminal display and change its name to `term://{cwd}//{pid}:{cmd}`.
The "term://..." scheme enables |:mksession| to "restore" a terminal buffer by
restarting the {cmd} when the session is loaded.
==============================================================================
Input *terminal-emulator-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>
<
Navigating to other windows is only possible in normal mode. For convenience,
you could use these mappings: >
: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
:nnoremap <A-h> <C-w>h
:nnoremap <A-j> <C-w>j
:nnoremap <A-k> <C-w>k
:nnoremap <A-l> <C-w>l
<
Then you can use `Alt+{h,j,k,l}` to navigate between windows from any mode.
Mouse input is supported, and 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-emulator-configuration*
Options: 'scrollback'
Events: |TermOpen|, |TermClose|
Highlight groups: |hl-TermCursor|, |hl-TermCursorNC|
Terminal colors can be customized with these variables:
- `{g,b}:terminal_color_$NUM`: 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 simply forwarded.
The `{g,b}:terminal_color_$NUM` variables are processed only when the terminal
starts (after |TermOpen|).
==============================================================================
Status Variables *terminal-emulator-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:
|
