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: