neovim/runtime/doc/nvim_terminal_emulator.txt

*terminal_emulator.txt*    						{Nvim}


		 NVIM REFERENCE MANUAL    by Thiago de Arruda


Embedded 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|

==============================================================================
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/

==============================================================================
2. 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; you should use the |:terminal|
    command 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.

==============================================================================
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:
>
    :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:
>
    :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
<
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.

Mouse input is also fully 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.

==============================================================================
4. Configuration			     *terminal-emulator-configuration*

Terminal buffers can be customized through the following global/buffer-local
variables (set via the |TermOpen| autocmd):

- `{g,b}:terminal_scrollback_buffer_size`: Scrollback buffer size, between 1
  and 100000 inclusive. The default is 1000.
- `{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|.

==============================================================================
5. 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 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:
>
    :autocmd TermOpen * setlocal statusline=%{b:term_title}
<
==============================================================================
 vim:tw=78:ts=8:noet:ft=help:norl: