*terminal.txt* For Vim version 8.1. Last change: 2019 Sep 26
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): >
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
TerminalOpen autocommand event is triggered. This makes it possible to set
options specifically for the window and buffer. Example: >
au TerminalOpen * if &buftype == 'terminal' | setlocal bufhidden=hide | endif
The <abuf> is set to the terminal buffer, but if there is no window (hidden
terminal) then setting options will happen in the wrong buffer, therefore the
check for &buftype in the example.
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
<
*g:terminal_ansi_colors*
In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new
terminal windows may be configured using the variable
`g:terminal_ansi_colors`, which should be a list of 16 color names or
hexadecimal color codes, similar to those accepted by |highlight-guifg|. When
not using GUI colors, the terminal window always uses the 16 ANSI colors of
the underlying terminal.
The |term_setansicolors()| function can be used to change the colors, and
|term_getansicolors()| to get the currently used colors.
Command syntax ~
:[range]ter[minal] [options] [command] *:ter* *:terminal*
Open a new terminal window.
If [command] is provided run it as a job and connect
the input and output to the terminal.
If [command] is not given the 'shell' option is used.
if [command] is NONE no job is started, the pty of the
terminal can be used by a command like gdb.
If [command] is missing the default behavior is to
close the terminal when the shell exits. This can be
changed with the ++noclose argument.
If [command] is present the default behavior is to
keep the terminal open in Terminal-Normal mode. This
can be changed with the ++close argument.
A new buffer will be created, using [command] or
'shell' as the name, prefixed with a "!". If a buffer
by this name already exists a number is added in
parentheses. E.g. if "gdb" exists the second terminal
buffer will use "!gdb (1)".
If [range] is given the specified lines are used as
input for the job. It will not be possible to type
keys in the ter