diff options
Diffstat (limited to 'runtime/doc/nvim_terminal_emulator.txt')
| -rw-r--r-- | runtime/doc/nvim_terminal_emulator.txt | 99 |
1 files changed, 37 insertions, 62 deletions
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index f368e28911..0954dcb5a7 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -4,28 +4,19 @@ NVIM REFERENCE MANUAL by Thiago de Arruda -Embedded terminal emulator *terminal-emulator* +Terminal emulator *terminal-emulator* -1. Introduction |terminal-emulator-intro| -2. Spawning |terminal-emulator-spawning| -3. Input |terminal-emulator-input| -4. Configuration |terminal-emulator-configuration| -5. Status Variables |terminal-emulator-status| +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. -============================================================================== -1. Introduction *terminal-emulator-intro* - -Nvim offers a mostly complete VT220/xterm terminal emulator. The terminal is -presented as a special buffer type, asynchronously updated to mirror the -virtual terminal display as data is received from the program connected to it. -For most purposes, terminal buffers behave a lot like normal buffers with -'nomodifiable' set. - -The implementation is powered by libvterm, a powerful abstract terminal -emulation library. http://www.leonerd.org.uk/code/libvterm/ +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. ============================================================================== -2. Spawning *terminal-emulator-spawning* +Spawning *terminal-emulator-spawning* There are 3 ways to create a terminal buffer: @@ -40,34 +31,27 @@ There are 3 ways to create a terminal buffer: 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; you should use the |:terminal| - command instead. +< 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:$COMMAND`. -Note that |:mksession| will "save" the terminal buffers by restarting all -programs when the session is restored. +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. ============================================================================== -3. Input *terminal-emulator-input* - -Sending input is possible by entering terminal mode, which is achieved by -pressing any key that would enter insert mode in a normal buffer (|i| or |a| -for example). The |:terminal| ex command will automatically enter terminal -mode once it's spawned. While in terminal mode, Nvim will forward all keys to -the underlying program. The only exception is the <C-\><C-n> key combo, -which will exit back to normal mode. - -Terminal mode has its own namespace for mappings, which is accessed with the -"t" prefix. It's possible to use terminal mappings to customize interaction -with the terminal. For example, here's how to map <Esc> to exit terminal mode: -> +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 by exiting to normal mode, which -can be cumbersome with <C-\><C-n> keys. To improve the navigation experience, -you could use the following mappings: -> +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 @@ -77,11 +61,9 @@ you could use the following mappings: :nnoremap <A-k> <C-w>k :nnoremap <A-l> <C-w>l < -This configuration allows using `Alt+{h,j,k,l}` to navigate between windows no -matter if they are displaying a normal buffer or a terminal buffer in terminal -mode. +Then you can use `Alt+{h,j,k,l}` to navigate between windows from any mode. -Mouse input is also fully supported, and has the following behavior: +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. @@ -93,27 +75,23 @@ Mouse input is also fully supported, and has the following behavior: the terminal wont lose focus and the hovered window will be scrolled. ============================================================================== -4. Configuration *terminal-emulator-configuration* +Configuration *terminal-emulator-configuration* + +Options: 'scrollback' +Events: |TermOpen|, |TermClose| +Highlight groups: |hl-TermCursor|, |hl-TermCursorNC| -Terminal buffers can be customized through the following global/buffer-local -variables (set via the |TermOpen| autocmd): +Terminal colors can be customized with these variables: -- 'scrollback' option: Scrollback lines (output history) limit. - `{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 configuration variables are only processed when the terminal starts, which -is why it needs to be done with the |TermOpen| autocmd or setting global -variables before the terminal is started. - -There is also a corresponding |TermClose| event. - -The terminal cursor can be highlighted via |hl-TermCursor| and -|hl-TermCursorNC|. +The `{g,b}:terminal_color_$NUM` variables are processed only when the terminal +starts (after |TermOpen|). ============================================================================== -5. Status Variables *terminal-emulator-status* +Status Variables *terminal-emulator-status* Terminal buffers maintain some information about the terminal in buffer-local variables: @@ -126,11 +104,8 @@ variables: - *b:terminal_job_pid* The PID of the top-level process running in the terminal. -These variables will have a value by the time the TermOpen autocmd runs, and -will continue to have a value for the lifetime of the terminal buffer, making -them suitable for use in 'statusline'. For example, to show the terminal title -as the status line: -> +These variables are initialized before TermOpen, so you can use them in +a local 'statusline'. Example: > :autocmd TermOpen * setlocal statusline=%{b:term_title} < ============================================================================== |