*terminal.txt* For Vim version 8.2. Last change: 2020 Nov 25
VIM REFERENCE MANUAL by Bram Moolenaar
Terminal window support *terminal* *terminal-window*
The terminal feature is optional, use this to check if your Vim has it: >
echo has('terminal')
If the result is "1" you have it.
1. Basic use |terminal-use|
Typing |terminal-typing|
Size and color |terminal-size-color|
Command syntax |:terminal|
Resizing |terminal-resizing|
Terminal Modes |Terminal-mode|
Cursor style |terminal-cursor-style|
Session |terminal-session|
Special keys |terminal-special-keys|
Unix |terminal-unix|
MS-Windows |terminal-ms-windows|
2. Terminal functions |terminal-function-details|
3. Terminal communication |terminal-communication|
Vim to job: term_sendkeys() |terminal-to-job|
Job to Vim: JSON API |terminal-api|
Using the client-server feature |terminal-client-server|
4. Remote testing |terminal-testing|
5. Diffing screen dumps |terminal-diff|
Writing a screen dump test for Vim |terminal-dumptest|
Creating a screen dump |terminal-screendump|
Comparing screen dumps |terminal-diffscreendump|
6. Debugging |terminal-debug|
Starting |termdebug-starting|
Example session |termdebug-example|
Stepping through code |termdebug-stepping|
Inspecting variables |termdebug-variables|
Other commands |termdebug-commands|
Prompt mode |termdebug-prompt|
Communication |termdebug-communication|
Customizing |termdebug-customizing|
{only available when compiled with the |+terminal| feature}
The terminal feature requires the |+job| and |+channel| features.
==============================================================================
1. Basic use *terminal-use*
This feature is for running a terminal emulator in a Vim window. A job can be
started connected to the terminal emulator. For example, to run a shell: >
:term bash
Or to run build command: >
:term make myprogram
The job runs asynchronously from Vim, the window will be updated to show
output from the job, also while editing in another window.
Typing ~
*terminal-typing*
When the keyboard focus is in the terminal window, typed keys will be sent to
the job. This uses a pty when possible. You can click outside of the
terminal window to move keyboard focus elsewhere.
*t_CTRL-W_CTRL-W* *t_CTRL-W_:*
CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
CTRL-W CTRL-W move focus to the next window
CTRL-W : enter an Ex command
See |CTRL-W| for more commands.
Special in the terminal window: *t_CTRL-W_.* *t_CTRL-W_N*
CTRL-W . send a CTRL-W to the job in the terminal
CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal
CTRL-W N go to Terminal-Normal mode, see |Terminal-mode|
CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode|
CTRL-W " {reg} paste register {reg} *t_CTRL-W_quote*
Also works with the = register to insert the result of
evaluating an expression.
CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C|
CTRL-W gt go to next tabpage, same as `gt` *t_CTRL-W_gt*
CTRL-W gT go to previous tabpage, same as `gT` *t_CTRL-W_gT*
See option 'termwinkey' for specifying another key instead of CTRL-W that
will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey'
to the job. For example:
'termwinkey' CTRL-W move focus to the next window
'termwinkey' : enter an Ex command
'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal
'termwinkey' . send 'termwinkey' to the job in the terminal
'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal
'termwinkey' N go to terminal Normal mode, see below
'termwinkey' CTRL-N same as CTRL-W N |t_CTRL-W_N|
'termwinkey' CTRL-C same as CTRL-W CTRL-C |t_CTRL-W_CTRL-C|
*t_CTRL-\_CTRL-N*
The special key combination CTRL-\ CTRL-N can be used to switch to Normal
mode, just like this works in any other mode.
*t_CTRL-W_CTRL-C*
CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a
CTRL-BREAK will also kill the job.
If you type CTRL-C the effect depends on what the pty has been configured to
do. For simple commands this causes a SIGINT to be sent to the job, which
would end it. Other commands may ignore the SIGINT or handle the CTRL-C
themselves (like Vim does).
To change the keys you type use terminal mode mappings, see |:tmap|.
These are defined like any mapping, but apply only when typing keys that are
sent to the job running in the terminal. For example, to make F1 switch
to Terminal-Normal mode: >
tnoremap <F1> <C-W>N
You can use Esc, but you need to make sure it won't cause other keys to
break (cursor keys start with an Esc, so they may break), this probably only
works in the GUI: >
tnoremap <Esc> <C-W>N
set notimeout ttimeout timeoutlen=100
You can also create menus similar to terminal mode mappings, but you have to
use |:tlmenu| instead of |:tmenu|.
*options-in-terminal*
After opening the terminal window and setting 'buftype' to "terminal" the
|TerminalWinOpen| autocommand event is triggered. This makes it possible to set
options specifically for the terminal window and buffer. Example: >
au TerminalWinOpen * setlocal bufhidden=hide
There is also the |TerminalOpen| event, but this may be triggered for a hidden
terminal, and the current window and buffer may not be for the new terminal.
You need to use <abuf>, which is set to the terminal buffer. Example: >
au TerminalOpen * call setbufvar(+expand('<abuf>'), '&colorcolumn', 123)
Mouse events (click and drag) are passed to the terminal. Mouse move events
are only passed when Vim itself is receiving them. For a terminal that is
when 'balloonevalterm' is enabled.
Size and color ~
*terminal-size-color*
See option 'termwinsize' for controlling the size of the terminal window.
(TODO: scrolling when the terminal is larger than the window)
The job running in the terminal can change the colors. The default foreground
and background colors are taken from Vim, the Normal highlight group.
For a color terminal the 'background' option is used to decide whether the
terminal window will start with a white or black background.
To use a different color the Terminal highlight group can be used, for
example: >
hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
The highlight needs to be defined before the terminal is created. Doing it
later, or setting 'wincolor', w