blob: 2c2275cb2ceee3f809c8407665d9549719b4d96f [file] [log] [blame]
Bram Moolenaar38baa3e2017-09-14 16:10:38 +02001*terminal.txt* For Vim version 8.0. Last change: 2017 Sep 13
Bram Moolenaare4f25e42017-07-07 11:54:15 +02002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Terminal window support *terminal*
8
9
10WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE
11
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +020012The terminal feature is optional, use this to check if your Vim has it: >
13 echo has('terminal')
14If the result is "1" you have it.
15
Bram Moolenaare4f25e42017-07-07 11:54:15 +020016
171. Basic use |terminal-use|
182. Remote testing |terminal-testing|
193. Debugging |terminal-debug|
20
21{Vi does not have any of these commands}
Bram Moolenaarc572da52017-08-27 16:52:01 +020022{only available when compiled with the |+terminal| feature}
23
24The terminal feature requires the |+multi_byte|, |+job| and |+channel| features.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020025
26==============================================================================
271. Basic use *terminal-use*
28
29This feature is for running a terminal emulator in a Vim window. A job can be
30started connected to the terminal emulator. For example, to run a shell: >
31 :term bash
32
Bram Moolenaare09ba7b2017-09-09 22:19:47 +020033Or to run build command: >
34 :term make myprogram
Bram Moolenaare4f25e42017-07-07 11:54:15 +020035
36The job runs asynchronously from Vim, the window will be updated to show
Bram Moolenaare09ba7b2017-09-09 22:19:47 +020037output from the job, also while editing in another window.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020038
Bram Moolenaar423802d2017-07-30 16:52:24 +020039
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020040Typing ~
41
Bram Moolenaardd693ce2017-08-10 23:15:19 +020042When the keyboard focus is in the terminal window, typed keys will be sent to
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020043the job. This uses a pty when possible. You can click outside of the
44terminal window to move keyboard focus elsewhere.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020045
Bram Moolenaar423802d2017-07-30 16:52:24 +020046CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
47 CTRL-W CTRL-W move focus to the next window
48 CTRL-W : enter an Ex command
49See |CTRL-W| for more commands.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020050
Bram Moolenaar423802d2017-07-30 16:52:24 +020051Special in the terminal window: *CTRL-W_.* *CTRL-W_N*
52 CTRL-W . send a CTRL-W to the job in the terminal
Bram Moolenaardd693ce2017-08-10 23:15:19 +020053 CTRL-W N go to Terminal-Normal mode, see |Terminal-mode|
54 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode|
Bram Moolenaarf55e4c82017-08-01 20:44:53 +020055 CTRL-W " {reg} paste register {reg} *CTRL-W_quote*
56 Also works with the = register to insert the result of
57 evaluating an expression.
Bram Moolenaar8e539c52017-08-18 22:57:06 +020058 CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C|
Bram Moolenaar423802d2017-07-30 16:52:24 +020059
60See option 'termkey' for specifying another key instead of CTRL-W that
61will work like CTRL-W. However, typing 'termkey' twice sends 'termkey' to
62the job. For example:
63 'termkey' CTRL-W move focus to the next window
64 'termkey' : enter an Ex command
65 'termkey' 'termkey' send 'termkey' to the job in the terminal
66 'termkey' . send a CTRL-W to the job in the terminal
67 'termkey' N go to terminal Normal mode, see below
68 'termkey' CTRL-N same as CTRL-W N
Bram Moolenaar8e539c52017-08-18 22:57:06 +020069 'termkey' CTRL-C same as |t_CTRL-W_CTRL-C|
Bram Moolenaar69198192017-08-05 14:10:48 +020070 *t_CTRL-\_CTRL-N*
Bram Moolenaardd693ce2017-08-10 23:15:19 +020071The special key combination CTRL-\ CTRL-N can be used to switch to Normal
72mode, just like this works in any other mode.
Bram Moolenaar8e539c52017-08-18 22:57:06 +020073 *t_CTRL-W_CTRL-C*
74CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a
75CTRL-BREAK will also kill the job.
76
77If you type CTRL-C the effect depends on what the pty has been configured to
78do. For simple commands this causes a SIGINT to be sent to the job, which
79would end it. Other commands may ignore the SIGINT or handle the CTRL-C
80themselves (like Vim does).
Bram Moolenaar423802d2017-07-30 16:52:24 +020081
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020082
Bram Moolenaar8e539c52017-08-18 22:57:06 +020083Size and color ~
Bram Moolenaare4f25e42017-07-07 11:54:15 +020084
Bram Moolenaar74675a62017-07-15 13:53:23 +020085See option 'termsize' for controlling the size of the terminal window.
86(TODO: scrolling when the terminal is larger than the window)
Bram Moolenaare4f25e42017-07-07 11:54:15 +020087
Bram Moolenaar38baa3e2017-09-14 16:10:38 +020088The job running in the terminal can change the colors. The default foreground
89and background colors are taken from Vim, the Normal highlight group.
90
91For a color terminal the 'background' option is used to decide whether the
92terminal window will start with a white or black background.
93
94To use a different color the Terminal highlight group can be used: >
95 hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
Bram Moolenaar8e539c52017-08-18 22:57:06 +020096
Bram Moolenaar423802d2017-07-30 16:52:24 +020097
Bram Moolenaare4f25e42017-07-07 11:54:15 +020098Syntax ~
Bram Moolenaar8a773062017-07-24 22:29:21 +020099
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200100:[range]ter[minal] [options] [command] *:ter* *:terminal*
Bram Moolenaar8a773062017-07-24 22:29:21 +0200101 Open a new terminal window.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200102
103 If [command] is provided run it as a job and connect
104 the input and output to the terminal.
105 If [command] is not given the 'shell' option is used.
Bram Moolenaarc572da52017-08-27 16:52:01 +0200106 if [command] is NONE no job is started, the pty of the
107 terminal can be used by a command like gdb.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200108
109 A new buffer will be created, using [command] or
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200110 'shell' as the name, prefixed with a "!". If a buffer
111 by this name already exists a number is added in
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200112 parentheses. E.g. if "gdb" exists the second terminal
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200113 buffer will use "!gdb (1)".
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200114
Bram Moolenaarb2412082017-08-20 18:09:14 +0200115 If [range] is given the specified lines are used as
116 input for the job. It will not be possible to type
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200117 keys in the terminal window. For MS-Windows see the
118 ++eof argument below.
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200119
120 Two comma separated numbers are used as "rows,cols".
121 E.g. `:24,80gdb` opens a terminal with 24 rows and 80
122 columns. However, if the terminal window spans the
123 Vim window with, there is no vertical split, the Vim
124 window width is used.
125 *term++close* *term++open*
126 Supported [options] are:
127 ++close The terminal window will close
128 automatically when the job terminates.
129 ++open When the job terminates and no window
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200130 shows it, a window will be opened.
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200131 Note that this can be interruptive.
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200132 ++curwin Open the terminal in the current
133 window, do not split the current
134 window. Fails if the current buffer
135 cannot be |abandon|ed.
136 ++hidden Open the terminal in a hidden buffer,
137 no window will be used.
Bram Moolenaarb2412082017-08-20 18:09:14 +0200138 ++rows={height} Use {height} for the terminal window
139 height.
140 ++cols={width} Use {width} for the terminal window
141 width.
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200142 ++eof={text} when using [range]: text to send after
143 the last line was written. Cannot
144 contain white space. A CR is
145 appended. For MS-Windows the default
146 is to send CTRL-D.
Bram Moolenaaref68e4f2017-09-02 16:28:36 +0200147 E.g. for a shell use "++eof=exit" and
148 for Python "++eof=exit()". Special
149 codes can be used like with `:map`,
150 e.g. "<C-Z>" for CTRL-Z.
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200151
152 If you want to use more options use the |term_start()|
153 function.
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200154
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200155When the buffer associated with the terminal is unloaded or wiped out the job
156is killed, similar to calling `job_stop(job, "kill")`
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200157
Bram Moolenaare561a7e2017-08-29 22:44:59 +0200158So long as the job is running the window behaves like it contains a modified
Bram Moolenaaref68e4f2017-09-02 16:28:36 +0200159buffer. Trying to close the window with `CTRL-W :quit` fails. When using
160`CTRL-W :quit!` the job is ended. The text in the window is lost. The buffer
161still exists, but getting it in a window with `:buffer` will show an empty
162buffer.
163
164Trying to close the window with `CTRL-W :close` also fails. Using
165`CTRL-W :close!` will close the window and make the buffer hidden.
Bram Moolenaare561a7e2017-08-29 22:44:59 +0200166
167You can use `CTRL-W :hide` to close the terminal window and make the buffer
168hidden, the job keeps running. The `:buffer` command can be used to turn the
169current window into a terminal window. If there are unsaved changes this
170fails, use ! to force, as usual.
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200171
172To have a background job run without a window, and open the window when it's
173done, use options like this: >
174 :term ++hidden ++open make
175Note that the window will open at an unexpected moment, this will interrupt
176what you are doing.
177
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200178 *E947* *E948*
Bram Moolenaar78712a72017-08-05 14:50:12 +0200179So long as the job is running, the buffer is considered modified and Vim
180cannot be quit easily, see |abandon|.
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200181
182When the job has finished and no changes were made to the buffer: closing the
183window will wipe out the buffer.
184
185Before changes can be made to a terminal buffer, the 'modifiable' option must
186be set. This is only possible when the job has finished. At the first change
187the buffer will become a normal buffer and the highlighting is removed.
188You may want to change the buffer name with |:file| to be able to write, since
189the buffer name will still be set to the command.
190
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200191
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200192Resizing ~
193
194The size of the terminal can be in one of three modes:
195
1961. The 'termsize' option is empty: The terminal size follows the window size.
197 The minimal size is 2 screen lines with 10 cells.
198
1992. The 'termsize' option is "rows*cols", where "rows" is the minimal number of
Bram Moolenaar8a773062017-07-24 22:29:21 +0200200 screen rows and "cols" is the minimal number of cells.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200201
2023. The 'termsize' option is "rowsXcols" (where the x is upper or lower case).
203 The terminal size is fixed to the specified number of screen lines and
204 cells. If the window is bigger there will be unused empty space.
205
206If the window is smaller than the terminal size, only part of the terminal can
207be seen (the lower-left part).
208
209The |term_getsize()| function can be used to get the current size of the
210terminal. |term_setsize()| can be used only when in the first or second mode,
211not when 'termsize' is "rowsXcols".
212
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200213
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200214Terminal-Job and Terminal-Normal mode ~
Bram Moolenaar423802d2017-07-30 16:52:24 +0200215 *Terminal-mode*
216When the job is running the contents of the terminal is under control of the
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200217job. That includes the cursor position. Typed keys are sent to the job.
218The terminal contents can change at any time. This is called Terminal-Job
219mode.
Bram Moolenaar423802d2017-07-30 16:52:24 +0200220
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200221Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode. Now the
222contents of the terminal window is under control of Vim, the job output is
223suspended. CTRL-\ CTRL-N does the same.
Bram Moolenaar423802d2017-07-30 16:52:24 +0200224 *E946*
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200225In Terminal-Normal mode you can move the cursor around with the usual Vim
226commands, Visually mark text, yank text, etc. But you cannot change the
227contents of the buffer. The commands that would start insert mode, such as
228'i' and 'a', return to Terminal-Job mode. The window will be updated to show
229the contents of the terminal.
Bram Moolenaar423802d2017-07-30 16:52:24 +0200230
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200231In Terminal-Normal mode the statusline and window title show "(Terminal)". If
232the job ends while in Terminal-Normal mode this changes to
233"(Terminal-finished)".
Bram Moolenaar423802d2017-07-30 16:52:24 +0200234
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200235It is not possible to enter Insert mode from Terminal-Job mode.
236
Bram Moolenaar423802d2017-07-30 16:52:24 +0200237
Bram Moolenaarc572da52017-08-27 16:52:01 +0200238Cursor style ~
239
240By default the cursor in the terminal window uses a not blinking block. The
241normal xterm escape sequences can be used to change the blinking state and the
242shape. Once focus leaves the terminal window Vim will restore the original
243cursor.
244
245An exception is when xterm is started with the "-bc" argument, or another way
246that causes the cursor to blink. This actually means that the blinking flag
247is inverted. Since Vim cannot detect this, the terminal window cursor
248blinking will also be inverted.
249
250
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200251Unix ~
252
253On Unix a pty is used to make it possible to run all kinds of commands. You
254can even run Vim in the terminal! That's used for debugging, see below.
255
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200256Environment variables are used to pass information to the running job:
257 TERM name of the terminal, 'term'
258 ROWS number of rows in the terminal initially
259 LINES same as ROWS
260 COLUMNS number of columns in the terminal initially
261 COLORS number of colors, 't_Co' (256*256*256 in the GUI)
262 VIM_SERVERNAME v:servername
263
264The |client-server| feature can be used to communicate with the Vim instance
265where the job was started. This only works when v:servername is not empty.
266If needed you can set it with: >
267 call remote_startserver('vim-server')
268
269In the job you can then do something like: >
270 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
271This will open the file "some_file.c" and put the cursor on line 123.
272
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200273
274MS-Windows ~
275
Bram Moolenaar8a773062017-07-24 22:29:21 +0200276On MS-Windows winpty is used to make it possible to run all kind of commands.
277Obviously, they must be commands that run in a terminal, not open their own
278window.
279
280You need the following two files from winpty:
281
282 winpty.dll
283 winpty-agent.exe
284
285You can download them from the following page:
286
287 https://github.com/rprichard/winpty
288
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200289Just put the files somewhere in your PATH. You can set the 'winptydll' option
290to point to the right file, if needed. If you have both the 32-bit and 64-bit
291version, rename to winpty32.dll and winpty64.dll to match the way Vim was
292build.
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200293
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200294==============================================================================
2952. Remote testing *terminal-testing*
296
297Most Vim tests execute a script inside Vim. For some tests this does not
298work, running the test interferes with the code being tested. To avoid this
299Vim is executed in a terminal window. The test sends keystrokes to it and
300inspects the resulting screen state.
301
302Functions ~
303
304term_sendkeys() send keystrokes to a terminal
305term_wait() wait for screen to be updated
306term_scrape() inspect terminal screen
307
308
309==============================================================================
3103. Debugging *terminal-debug*
311
312The Terminal debugging plugin can be used to debug a program with gdb and view
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200313the source code in a Vim window. Since this is completely contained inside
314Vim this also works remotely over an ssh connection.
315
316
317Starting ~
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200318
Bram Moolenaarc572da52017-08-27 16:52:01 +0200319Load the plugin with this command: >
320 packadd termdebug
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200321< *:Termdebug*
Bram Moolenaarc572da52017-08-27 16:52:01 +0200322To start debugging use `:TermDebug` folowed by the command name, for example: >
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200323 :TermDebug vim
324
Bram Moolenaarc572da52017-08-27 16:52:01 +0200325This opens two windows:
Bram Moolenaar45d5f262017-09-10 19:14:31 +0200326gdb window A terminal window in which "gdb vim" is executed. Here you
327 can directly interact with gdb. The buffer name is "!gdb".
328program window A terminal window for the executed program. When "run" is
329 used in gdb the program I/O will happen in this window, so
330 that it does not interfere with controlling gdb. The buffer
331 name is "gdb program".
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200332
333The current window is used to show the source code. When gdb pauses the
334source file location will be displayed, if possible. A sign is used to
335highlight the current position (using highlight group debugPC).
336
337If the buffer in the current window is modified, another window will be opened
338to display the current gdb position.
339
340Focus the terminal of the executed program to interact with it. This works
341the same as any command running in a terminal window.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200342
Bram Moolenaar45d5f262017-09-10 19:14:31 +0200343When the debugger ends, typically by typing "quit" in the gdb window, the two
344opened windows are closed.
Bram Moolenaarc572da52017-08-27 16:52:01 +0200345
346
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200347Stepping through code ~
348
349Put focus on the gdb window to type commands there. Some common ones are:
350- CTRL-C interrupt the program
351- next execute the current line and stop at the next line
352- step execute the current line and stop at the next statement, entering
353 functions
354- finish execute until leaving the current function
355- where show the stack
356- frame N go to the Nth stack frame
357- continue continue execution
358
Bram Moolenaar45d5f262017-09-10 19:14:31 +0200359In the window showing the source code some commands can used to control gdb:
360 :Break set a breakpoint at the current line; a sign will be displayed
361 :Delete delete a breakpoint at the current line
362 :Step execute the gdb "step" command
363 :Over execute the gdb "next" command (:Next is a Vim command)
364 :Finish execute the gdb "finish" command
365 :Continue execute the gdb "continue" command
366
367
368Inspecting variables ~
369
370 :Evaluate evaluate the expression under the cursor
371 K same
372 :Evaluate {expr} evaluate {expr}
373 :'<,'>Evaluate evaluate the Visually selected text
374
375This is similar to using "print" in the gdb window.
376
377
378Other commands ~
379
380 :Gdb jump to the gdb window
381 :Program jump to the window with the running program
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200382
383
384Communication ~
385
386There is another, hidden, buffer, which is used for Vim to communicate with
387gdb. The buffer name is "gdb communication". Do not delete this buffer, it
388will break the debugger.
389
390
Bram Moolenaarc572da52017-08-27 16:52:01 +0200391Customizing ~
392
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200393To change the name of the gdb command, set the "termdebugger" variable before
394invoking `:Termdebug`: >
395 let termdebugger = "mygdb"
396Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI
397interface.
398
399The color of the signs can be adjusted with these highlight groups:
400- debugPC the current position
401- debugBreakpoint a breakpoint
402
403The defaults are, when 'background' is "light":
404 hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
405 hi debugBreakpoint term=reverse ctermbg=red guibg=red
406
407When 'background' is "dark":
408 hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
409 hi debugBreakpoint term=reverse ctermbg=red guibg=red
Bram Moolenaarc572da52017-08-27 16:52:01 +0200410
Bram Moolenaar38baa3e2017-09-14 16:10:38 +0200411To change the width of the Vim window when debugging starts, and use a
412vertical split: >
413 let g:termdebug_wide = 163
414This will set &columns to 163 when :Termdebug is used. The value is restored
415when quitting the debugger.
416
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200417
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200418
419 vim:tw=78:ts=8:ft=help:norl: