blob: 1f23deb7852ab3b1e962fbe66e074c62386d9b72 [file] [log] [blame]
Bram Moolenaar8cad9302017-08-12 14:32:32 +02001*terminal.txt* For Vim version 8.0. Last change: 2017 Aug 12
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}
22
23==============================================================================
241. Basic use *terminal-use*
25
26This feature is for running a terminal emulator in a Vim window. A job can be
27started connected to the terminal emulator. For example, to run a shell: >
28 :term bash
29
30Or to run a debugger: >
31 :term gdb vim
32
33The job runs asynchronously from Vim, the window will be updated to show
34output from the job, also while editing in any other window.
35
Bram Moolenaar423802d2017-07-30 16:52:24 +020036
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020037Typing ~
38
Bram Moolenaardd693ce2017-08-10 23:15:19 +020039When the keyboard focus is in the terminal window, typed keys will be sent to
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020040the job. This uses a pty when possible. You can click outside of the
41terminal window to move keyboard focus elsewhere.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020042
Bram Moolenaar423802d2017-07-30 16:52:24 +020043CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
44 CTRL-W CTRL-W move focus to the next window
45 CTRL-W : enter an Ex command
46See |CTRL-W| for more commands.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020047
Bram Moolenaar423802d2017-07-30 16:52:24 +020048Special in the terminal window: *CTRL-W_.* *CTRL-W_N*
49 CTRL-W . send a CTRL-W to the job in the terminal
Bram Moolenaardd693ce2017-08-10 23:15:19 +020050 CTRL-W N go to Terminal-Normal mode, see |Terminal-mode|
51 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode|
Bram Moolenaarf55e4c82017-08-01 20:44:53 +020052 CTRL-W " {reg} paste register {reg} *CTRL-W_quote*
53 Also works with the = register to insert the result of
54 evaluating an expression.
Bram Moolenaar8e539c52017-08-18 22:57:06 +020055 CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C|
Bram Moolenaar423802d2017-07-30 16:52:24 +020056
57See option 'termkey' for specifying another key instead of CTRL-W that
58will work like CTRL-W. However, typing 'termkey' twice sends 'termkey' to
59the job. For example:
60 'termkey' CTRL-W move focus to the next window
61 'termkey' : enter an Ex command
62 'termkey' 'termkey' send 'termkey' to the job in the terminal
63 'termkey' . send a CTRL-W to the job in the terminal
64 'termkey' N go to terminal Normal mode, see below
65 'termkey' CTRL-N same as CTRL-W N
Bram Moolenaar8e539c52017-08-18 22:57:06 +020066 'termkey' CTRL-C same as |t_CTRL-W_CTRL-C|
Bram Moolenaar69198192017-08-05 14:10:48 +020067 *t_CTRL-\_CTRL-N*
Bram Moolenaardd693ce2017-08-10 23:15:19 +020068The special key combination CTRL-\ CTRL-N can be used to switch to Normal
69mode, just like this works in any other mode.
Bram Moolenaar8e539c52017-08-18 22:57:06 +020070 *t_CTRL-W_CTRL-C*
71CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a
72CTRL-BREAK will also kill the job.
73
74If you type CTRL-C the effect depends on what the pty has been configured to
75do. For simple commands this causes a SIGINT to be sent to the job, which
76would end it. Other commands may ignore the SIGINT or handle the CTRL-C
77themselves (like Vim does).
Bram Moolenaar423802d2017-07-30 16:52:24 +020078
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020079
Bram Moolenaar8e539c52017-08-18 22:57:06 +020080Size and color ~
Bram Moolenaare4f25e42017-07-07 11:54:15 +020081
Bram Moolenaar74675a62017-07-15 13:53:23 +020082See option 'termsize' for controlling the size of the terminal window.
83(TODO: scrolling when the terminal is larger than the window)
Bram Moolenaare4f25e42017-07-07 11:54:15 +020084
Bram Moolenaar8e539c52017-08-18 22:57:06 +020085The terminal uses the 'background' option to decide whether the terminal
86window will start with a white or black background. The job running in the
87terminal can change the colors.
88
Bram Moolenaar423802d2017-07-30 16:52:24 +020089
Bram Moolenaare4f25e42017-07-07 11:54:15 +020090Syntax ~
Bram Moolenaar8a773062017-07-24 22:29:21 +020091
Bram Moolenaardd693ce2017-08-10 23:15:19 +020092:[range]ter[minal] [options] [command] *:ter* *:terminal*
Bram Moolenaar8a773062017-07-24 22:29:21 +020093 Open a new terminal window.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020094
95 If [command] is provided run it as a job and connect
96 the input and output to the terminal.
97 If [command] is not given the 'shell' option is used.
98
99 A new buffer will be created, using [command] or
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200100 'shell' as the name, prefixed with a "!". If a buffer
101 by this name already exists a number is added in
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200102 parentheses. E.g. if "gdb" exists the second terminal
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200103 buffer will use "!gdb (1)".
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200104
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200105 If [range] is given it is used for the terminal size.
106 One number specifies the number of rows. Unless the
107 "vertical" modifier is used, then it is the number of
108 columns.
109
110 Two comma separated numbers are used as "rows,cols".
111 E.g. `:24,80gdb` opens a terminal with 24 rows and 80
112 columns. However, if the terminal window spans the
113 Vim window with, there is no vertical split, the Vim
114 window width is used.
115 *term++close* *term++open*
116 Supported [options] are:
117 ++close The terminal window will close
118 automatically when the job terminates.
119 ++open When the job terminates and no window
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200120 shows it, a window will be opened.
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200121 Note that this can be interruptive.
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200122 ++curwin Open the terminal in the current
123 window, do not split the current
124 window. Fails if the current buffer
125 cannot be |abandon|ed.
126 ++hidden Open the terminal in a hidden buffer,
127 no window will be used.
128
129 If you want to use more options use the |term_start()|
130 function.
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200131
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200132When the buffer associated with the terminal is unloaded or wiped out the job
133is killed, similar to calling `job_stop(job, "kill")`
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200134
Bram Moolenaar78712a72017-08-05 14:50:12 +0200135By default the 'bufhidden' option of the buffer will be set to "hide".
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200136So long as the job is running: If the window is closed the buffer becomes
137hidden. The command will not be stopped. The `:buffer` command can be used
138to turn the current window into a terminal window. If there are unsaved
139changes this fails, use ! to force, as usual.
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200140
141To have a background job run without a window, and open the window when it's
142done, use options like this: >
143 :term ++hidden ++open make
144Note that the window will open at an unexpected moment, this will interrupt
145what you are doing.
146
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200147 *E947* *E948*
Bram Moolenaar78712a72017-08-05 14:50:12 +0200148So long as the job is running, the buffer is considered modified and Vim
149cannot be quit easily, see |abandon|.
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200150
151When the job has finished and no changes were made to the buffer: closing the
152window will wipe out the buffer.
153
154Before changes can be made to a terminal buffer, the 'modifiable' option must
155be set. This is only possible when the job has finished. At the first change
156the buffer will become a normal buffer and the highlighting is removed.
157You may want to change the buffer name with |:file| to be able to write, since
158the buffer name will still be set to the command.
159
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200160
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200161Resizing ~
162
163The size of the terminal can be in one of three modes:
164
1651. The 'termsize' option is empty: The terminal size follows the window size.
166 The minimal size is 2 screen lines with 10 cells.
167
1682. The 'termsize' option is "rows*cols", where "rows" is the minimal number of
Bram Moolenaar8a773062017-07-24 22:29:21 +0200169 screen rows and "cols" is the minimal number of cells.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200170
1713. The 'termsize' option is "rowsXcols" (where the x is upper or lower case).
172 The terminal size is fixed to the specified number of screen lines and
173 cells. If the window is bigger there will be unused empty space.
174
175If the window is smaller than the terminal size, only part of the terminal can
176be seen (the lower-left part).
177
178The |term_getsize()| function can be used to get the current size of the
179terminal. |term_setsize()| can be used only when in the first or second mode,
180not when 'termsize' is "rowsXcols".
181
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200182
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200183Terminal-Job and Terminal-Normal mode ~
Bram Moolenaar423802d2017-07-30 16:52:24 +0200184 *Terminal-mode*
185When the job is running the contents of the terminal is under control of the
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200186job. That includes the cursor position. Typed keys are sent to the job.
187The terminal contents can change at any time. This is called Terminal-Job
188mode.
Bram Moolenaar423802d2017-07-30 16:52:24 +0200189
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200190Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode. Now the
191contents of the terminal window is under control of Vim, the job output is
192suspended. CTRL-\ CTRL-N does the same.
Bram Moolenaar423802d2017-07-30 16:52:24 +0200193 *E946*
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200194In Terminal-Normal mode you can move the cursor around with the usual Vim
195commands, Visually mark text, yank text, etc. But you cannot change the
196contents of the buffer. The commands that would start insert mode, such as
197'i' and 'a', return to Terminal-Job mode. The window will be updated to show
198the contents of the terminal.
Bram Moolenaar423802d2017-07-30 16:52:24 +0200199
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200200In Terminal-Normal mode the statusline and window title show "(Terminal)". If
201the job ends while in Terminal-Normal mode this changes to
202"(Terminal-finished)".
Bram Moolenaar423802d2017-07-30 16:52:24 +0200203
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200204It is not possible to enter Insert mode from Terminal-Job mode.
205
Bram Moolenaar423802d2017-07-30 16:52:24 +0200206
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200207Unix ~
208
209On Unix a pty is used to make it possible to run all kinds of commands. You
210can even run Vim in the terminal! That's used for debugging, see below.
211
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200212Environment variables are used to pass information to the running job:
213 TERM name of the terminal, 'term'
214 ROWS number of rows in the terminal initially
215 LINES same as ROWS
216 COLUMNS number of columns in the terminal initially
217 COLORS number of colors, 't_Co' (256*256*256 in the GUI)
218 VIM_SERVERNAME v:servername
219
220The |client-server| feature can be used to communicate with the Vim instance
221where the job was started. This only works when v:servername is not empty.
222If needed you can set it with: >
223 call remote_startserver('vim-server')
224
225In the job you can then do something like: >
226 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
227This will open the file "some_file.c" and put the cursor on line 123.
228
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200229
230MS-Windows ~
231
Bram Moolenaar8a773062017-07-24 22:29:21 +0200232On MS-Windows winpty is used to make it possible to run all kind of commands.
233Obviously, they must be commands that run in a terminal, not open their own
234window.
235
236You need the following two files from winpty:
237
238 winpty.dll
239 winpty-agent.exe
240
241You can download them from the following page:
242
243 https://github.com/rprichard/winpty
244
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200245Just put the files somewhere in your PATH. You can set the 'winptydll' option
246to point to the right file, if needed. If you have both the 32-bit and 64-bit
247version, rename to winpty32.dll and winpty64.dll to match the way Vim was
248build.
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200249
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200250==============================================================================
2512. Remote testing *terminal-testing*
252
253Most Vim tests execute a script inside Vim. For some tests this does not
254work, running the test interferes with the code being tested. To avoid this
255Vim is executed in a terminal window. The test sends keystrokes to it and
256inspects the resulting screen state.
257
258Functions ~
259
260term_sendkeys() send keystrokes to a terminal
261term_wait() wait for screen to be updated
262term_scrape() inspect terminal screen
263
264
265==============================================================================
2663. Debugging *terminal-debug*
267
268The Terminal debugging plugin can be used to debug a program with gdb and view
269the source code in a Vim window. For example: >
270
271 :TermDebug vim
272
273This opens three windows:
274- A terminal window in which "gdb vim" is executed. Here you can directly
275 interact with gdb.
276- A terminal window for the executed program. When "run" is used in gdb the
277 program I/O will happen in this window, so that it does not interfere with
278 controlling gdb.
279- A normal Vim window used to show the source code. When gdb jumps to a
280 source file location this window will display the code, if possible. Values
281 of variables can be inspected, breakpoints set and cleared, etc.
282
283This uses two terminal windows. To open the gdb window: >
284 :term gdb [arguments]
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200285To open the terminal to run the tested program |term_start()| is used.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200286
287TODO
288
289
290 vim:tw=78:ts=8:ft=help:norl: