mirror of
https://github.com/neovim/neovim.git
synced 2024-12-20 19:25:11 -07:00
131 lines
5.0 KiB
Plaintext
131 lines
5.0 KiB
Plaintext
*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.
|
|
- |'channel'| The nvim channel ID for the underlying PTY.
|
|
|chansend()| can be used to send input to the terminal.
|
|
- *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:
|