*terminal.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 'buftype', asynchronously updated as data is received
from the connected program.

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 ("tailed") if 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 several ways to create a terminal buffer:

- Run the |:terminal| command.
- Call |nvim_open_term()| or `jobstart(…, {'term': v:true})`.
- Edit a "term://" buffer. Examples: >vim
    :edit term://bash
    :vsplit term://top

<    Note: To open a "term://" buffer from an autocmd, the |autocmd-nested|
    modifier is required. >vim
        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}).

The terminal environment is initialized as in |jobstart-env|.

==============================================================================
Input						*terminal-input*

To send input, enter |Terminal-mode| with |i|, |I|, |a|, |A| or
|:startinsert|. In this mode all keys except <C-\> are sent to the underlying
program. If <C-\> is pressed, the next key is sent unless it is <C-N> or <C-O>.
Use <C-\><C-N> to return to normal mode. |CTRL-\_CTRL-N|
Use <C-\><C-O> to execute one normal mode command and then return to terminal
mode. *t_CTRL-\_CTRL-O*

Terminal-mode forces these local options:

    'cursorlineopt' = number
    'nocursorcolumn'
    'scrolloff' = 0
    'sidescrolloff' = 0

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: >vim
    :tnoremap <Esc> <C-\><C-n>

To simulate |i_CTRL-R| in terminal-mode: >vim
    :tnoremap <expr> <C-R> '<C-\><C-N>"'.nr2char(getchar()).'pi'

To use `ALT+{h,j,k,l}` to navigate windows from any mode: >vim
    :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

You can also create menus similar to terminal mode mappings, but you have to
use |:tlmenu| instead of |:tmenu|.

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 won't lose focus and the hovered window will be scrolled.

==============================================================================
Configuration					*terminal-config*

Options:		'modified', 'scrollback'
Events:			|TermOpen|, |TermEnter|, |TermLeave|, |TermClose|
Highlight groups:	|hl-TermCursor|

Terminal sets local defaults for some options, which may differ from your
global configuration.

- 'list' is disabled
- 'wrap'