mirror of
https://github.com/neovim/neovim.git
synced 2024-12-25 13:45:15 -07:00
023f67cad8
Showing the 'number' column in terminal buffers is a bit silly because of 'scrollback'. But it's mostly harmless and technically works as expected. The least surprising thing is to leave the user's settings alone. Since there are tradeoffs in both cases, we choose inertia. We still disable 'relativenumber' in *terminal-mode* (as opposed to normal-mode) because it is totally broken: the Nvim cursor (not terminal cursor) is always on the last line.
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 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.
|
|
|
|
Type <M-]> to see the table of contents.
|
|
|
|
==============================================================================
|
|
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>
|
|
|
|
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-emulator-configuration*
|
|
|
|
Options: '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 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:
|