blob: 2ca2d4be6f2c51b216f55d66bc7aa5e53c870d52 [file] [log] [blame]
Dimitry Ishenkoc4bca1d2025-07-08 23:13:14 +02001*terminal.txt* For Vim version 9.1. Last change: 2025 Jul 08
Bram Moolenaare4f25e42017-07-07 11:54:15 +02002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
Bram Moolenaarb1c91982018-05-17 17:04:55 +02007Terminal window support *terminal* *terminal-window*
Bram Moolenaare4f25e42017-07-07 11:54:15 +02008
9
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +020010The terminal feature is optional, use this to check if your Vim has it: >
11 echo has('terminal')
12If the result is "1" you have it.
13
Bram Moolenaare4f25e42017-07-07 11:54:15 +020014
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200151. Basic use |terminal-use|
16 Typing |terminal-typing|
17 Size and color |terminal-size-color|
18 Command syntax |:terminal|
19 Resizing |terminal-resizing|
20 Terminal Modes |Terminal-mode|
21 Cursor style |terminal-cursor-style|
22 Session |terminal-session|
23 Special keys |terminal-special-keys|
24 Unix |terminal-unix|
25 MS-Windows |terminal-ms-windows|
262. Terminal functions |terminal-function-details|
273. Terminal communication |terminal-communication|
28 Vim to job: term_sendkeys() |terminal-to-job|
29 Job to Vim: JSON API |terminal-api|
30 Using the client-server feature |terminal-client-server|
314. Remote testing |terminal-testing|
325. Diffing screen dumps |terminal-diff|
Bram Moolenaar938ae282023-02-20 20:44:55 +000033 Writing a screen dump test for Vim |terminal-dumptest|
34 Creating a screen dump |terminal-screendump|
35 Comparing screen dumps |terminal-diffscreendump|
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200366. Debugging |terminal-debug|
37 Starting |termdebug-starting|
38 Example session |termdebug-example|
39 Stepping through code |termdebug-stepping|
40 Inspecting variables |termdebug-variables|
Sean Dewar3d3a9152023-08-23 17:14:49 +010041 Navigating stack frames |termdebug-frames|
Bram Moolenaar6bf2c622019-07-04 17:12:09 +020042 Other commands |termdebug-commands|
Bram Moolenaar2f0936c2022-01-08 21:51:59 +000043 Events |termdebug-events|
Bram Moolenaar6bf2c622019-07-04 17:12:09 +020044 Prompt mode |termdebug-prompt|
shane.xb.qian7fbbd7f2023-11-08 21:44:48 +010045 Mappings |termdebug-mappings|
Bram Moolenaar6bf2c622019-07-04 17:12:09 +020046 Communication |termdebug-communication|
47 Customizing |termdebug-customizing|
Bram Moolenaare4f25e42017-07-07 11:54:15 +020048
Bram Moolenaarc572da52017-08-27 16:52:01 +020049{only available when compiled with the |+terminal| feature}
Bram Moolenaar4c92e752019-02-17 21:18:32 +010050The terminal feature requires the |+job| and |+channel| features.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020051
52==============================================================================
531. Basic use *terminal-use*
54
55This feature is for running a terminal emulator in a Vim window. A job can be
56started connected to the terminal emulator. For example, to run a shell: >
57 :term bash
58
Bram Moolenaare09ba7b2017-09-09 22:19:47 +020059Or to run build command: >
60 :term make myprogram
Bram Moolenaare4f25e42017-07-07 11:54:15 +020061
62The job runs asynchronously from Vim, the window will be updated to show
Bram Moolenaare09ba7b2017-09-09 22:19:47 +020063output from the job, also while editing in another window.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020064
Bram Moolenaar423802d2017-07-30 16:52:24 +020065
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020066Typing ~
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +020067 *terminal-typing*
Bram Moolenaardd693ce2017-08-10 23:15:19 +020068When the keyboard focus is in the terminal window, typed keys will be sent to
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020069the job. This uses a pty when possible. You can click outside of the
70terminal window to move keyboard focus elsewhere.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020071
Bram Moolenaar26967612019-03-17 17:13:16 +010072 *t_CTRL-W_CTRL-W* *t_CTRL-W_:*
Bram Moolenaar423802d2017-07-30 16:52:24 +020073CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
Bram Moolenaar60e73f22017-11-12 18:02:06 +010074 CTRL-W CTRL-W move focus to the next window
Bram Moolenaar423802d2017-07-30 16:52:24 +020075 CTRL-W : enter an Ex command
76See |CTRL-W| for more commands.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020077
Bram Moolenaar664f3cf2019-12-07 16:03:51 +010078Special in the terminal window: *t_CTRL-W_.* *t_CTRL-W_N*
Bram Moolenaar423802d2017-07-30 16:52:24 +020079 CTRL-W . send a CTRL-W to the job in the terminal
Bram Moolenaarb59118d2018-04-13 22:11:56 +020080 CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal
Bram Moolenaardd693ce2017-08-10 23:15:19 +020081 CTRL-W N go to Terminal-Normal mode, see |Terminal-mode|
82 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode|
Bram Moolenaar26967612019-03-17 17:13:16 +010083 CTRL-W " {reg} paste register {reg} *t_CTRL-W_quote*
Bram Moolenaarf55e4c82017-08-01 20:44:53 +020084 Also works with the = register to insert the result of
85 evaluating an expression.
Bram Moolenaar8e539c52017-08-18 22:57:06 +020086 CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C|
Bram Moolenaar26967612019-03-17 17:13:16 +010087 CTRL-W gt go to next tabpage, same as `gt` *t_CTRL-W_gt*
88 CTRL-W gT go to previous tabpage, same as `gT` *t_CTRL-W_gT*
Bram Moolenaar423802d2017-07-30 16:52:24 +020089
Bram Moolenaar7dda86f2018-04-20 22:36:41 +020090See option 'termwinkey' for specifying another key instead of CTRL-W that
91will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey'
92to the job. For example:
93 'termwinkey' CTRL-W move focus to the next window
94 'termwinkey' : enter an Ex command
95 'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal
Bram Moolenaardcdeaaf2018-06-17 22:19:12 +020096 'termwinkey' . send 'termwinkey' to the job in the terminal
97 'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +020098 'termwinkey' N go to terminal Normal mode, see below
Bram Moolenaar26967612019-03-17 17:13:16 +010099 'termwinkey' CTRL-N same as CTRL-W N |t_CTRL-W_N|
100 'termwinkey' CTRL-C same as CTRL-W CTRL-C |t_CTRL-W_CTRL-C|
Bram Moolenaar69198192017-08-05 14:10:48 +0200101 *t_CTRL-\_CTRL-N*
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200102The special key combination CTRL-\ CTRL-N can be used to switch to Normal
103mode, just like this works in any other mode.
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200104 *t_CTRL-W_CTRL-C*
105CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a
Bram Moolenaar63f32602022-06-09 20:45:54 +0100106CTRL-Break will also kill the job.
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200107
108If you type CTRL-C the effect depends on what the pty has been configured to
109do. For simple commands this causes a SIGINT to be sent to the job, which
110would end it. Other commands may ignore the SIGINT or handle the CTRL-C
111themselves (like Vim does).
Bram Moolenaar423802d2017-07-30 16:52:24 +0200112
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200113To change the keys you type use terminal mode mappings, see |:tmap|.
114These are defined like any mapping, but apply only when typing keys that are
Bram Moolenaar98ef2332018-03-18 14:44:37 +0100115sent to the job running in the terminal. For example, to make F1 switch
Bram Moolenaar24a98a02017-09-27 22:23:55 +0200116to Terminal-Normal mode: >
Bram Moolenaar98ef2332018-03-18 14:44:37 +0100117 tnoremap <F1> <C-W>N
118You can use Esc, but you need to make sure it won't cause other keys to
Bram Moolenaaracc22402020-06-07 21:07:18 +0200119break (cursor keys start with an Esc, so they may break), this probably only
120works in the GUI: >
Bram Moolenaar24a98a02017-09-27 22:23:55 +0200121 tnoremap <Esc> <C-W>N
Bram Moolenaar98ef2332018-03-18 14:44:37 +0100122 set notimeout ttimeout timeoutlen=100
123
Bram Moolenaar4c5d8152018-10-19 22:36:53 +0200124You can also create menus similar to terminal mode mappings, but you have to
125use |:tlmenu| instead of |:tmenu|.
126
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200127 *options-in-terminal*
Bram Moolenaar24a98a02017-09-27 22:23:55 +0200128After opening the terminal window and setting 'buftype' to "terminal" the
Bram Moolenaar23515b42020-11-29 14:36:24 +0100129|TerminalWinOpen| autocommand event is triggered. This makes it possible to set
130options specifically for the terminal window and buffer. Example: >
131 au TerminalWinOpen * setlocal bufhidden=hide
Bram Moolenaar942db232021-02-13 18:14:48 +0100132This only works properly if the terminal is not hidden.
Bram Moolenaar23515b42020-11-29 14:36:24 +0100133
Bram Moolenaar942db232021-02-13 18:14:48 +0100134For both hidden and non-hidden terminals this works, both for buffer-local and
135window-local options: >
136 au TerminalWinOpen,BufWinEnter * if &buftype == 'terminal'
137 \ | setlocal bufhidden=hide colorcolumn=123
138 \ | endif
139Note that for a hidden terminal the options are not set until the terminal is
140no longer hidden.
141
142There is also the |TerminalOpen| event. Keep in mind this may be triggered
143for a hidden terminal, then the current window and buffer are not that of the
144new terminal.
Bram Moolenaar23515b42020-11-29 14:36:24 +0100145You need to use <abuf>, which is set to the terminal buffer. Example: >
Bram Moolenaar942db232021-02-13 18:14:48 +0100146 au TerminalOpen * call setbufvar(expand('<abuf>')->str2nr(),
147 \ '&termwinscroll', 1000)
148For a window-local option, you need to delay setting the option until the
149terminal window has been created (this only works for a hidden terminal): >
150 au TerminalOpen * exe printf(
151 \ 'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d',
152 \ expand('<abuf>')->str2nr(), 123)
153For a non-hidden terminal use |TerminalWinOpen|.
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200154
Bram Moolenaar52dbb5e2017-11-21 18:11:27 +0100155Mouse events (click and drag) are passed to the terminal. Mouse move events
156are only passed when Vim itself is receiving them. For a terminal that is
157when 'balloonevalterm' is enabled.
158
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +0200159
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200160Size and color ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +0100161 *terminal-size-color*
Bram Moolenaar7dda86f2018-04-20 22:36:41 +0200162See option 'termwinsize' for controlling the size of the terminal window.
Bram Moolenaar74675a62017-07-15 13:53:23 +0200163(TODO: scrolling when the terminal is larger than the window)
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200164
Bram Moolenaar38baa3e2017-09-14 16:10:38 +0200165The job running in the terminal can change the colors. The default foreground
166and background colors are taken from Vim, the Normal highlight group.
167
168For a color terminal the 'background' option is used to decide whether the
169terminal window will start with a white or black background.
170
Bram Moolenaardf980db2017-12-24 13:22:00 +0100171To use a different color the Terminal highlight group can be used, for
172example: >
Bram Moolenaar38baa3e2017-09-14 16:10:38 +0200173 hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
Bram Moolenaar83d47902020-03-26 20:34:00 +0100174Instead of Terminal another group can be specified with the "term_highlight"
175option for `term_start()`.
176
Bram Moolenaarf59c6e82018-04-10 15:59:11 +0200177 *g:terminal_ansi_colors*
Bram Moolenaar7dda86f2018-04-20 22:36:41 +0200178In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new
Bram Moolenaarf59c6e82018-04-10 15:59:11 +0200179terminal windows may be configured using the variable
180`g:terminal_ansi_colors`, which should be a list of 16 color names or
181hexadecimal color codes, similar to those accepted by |highlight-guifg|. When
182not using GUI colors, the terminal window always uses the 16 ANSI colors of
183the underlying terminal.
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200184When using `term_start()` the colors can be set with the "ansi_colors" option.
Bram Moolenaarf59c6e82018-04-10 15:59:11 +0200185The |term_setansicolors()| function can be used to change the colors, and
186|term_getansicolors()| to get the currently used colors.
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200187
Bram Moolenaar423802d2017-07-30 16:52:24 +0200188
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200189Command syntax ~
Bram Moolenaar8a773062017-07-24 22:29:21 +0200190
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200191:[range]ter[minal] [options] [command] *:ter* *:terminal*
Bram Moolenaar8a773062017-07-24 22:29:21 +0200192 Open a new terminal window.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200193
194 If [command] is provided run it as a job and connect
195 the input and output to the terminal.
196 If [command] is not given the 'shell' option is used.
Bram Moolenaarc572da52017-08-27 16:52:01 +0200197 if [command] is NONE no job is started, the pty of the
198 terminal can be used by a command like gdb.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200199
Christian Brabandt6de71912024-12-30 10:20:17 +0100200 If [command] outputs NUL bytes, those will be
201 converted to new lines |NL-used-for-Nul|.
202
matveyta01148d2024-11-23 14:19:58 +0100203 *terminal-nospecial*
204 Vim itself only recognizes |cmdline-special|
205 characters inside [command]. Everything else will be
206 passed untouched. When needed to expand wildcards,
207 environment variables or other shell specials consider
208 |term++shell| option.
209
Bram Moolenaar1dd98332018-03-16 22:54:53 +0100210 If [command] is missing the default behavior is to
211 close the terminal when the shell exits. This can be
212 changed with the ++noclose argument.
213 If [command] is present the default behavior is to
214 keep the terminal open in Terminal-Normal mode. This
215 can be changed with the ++close argument.
216
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200217 No Vim command can follow, any | is included in
218 [command]. Use `:execute` if you must have a Vim
219 command following in the same line.
220
Christian Brabandtec9c3262024-02-21 20:40:05 +0100221 *terminal-bufname*
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200222 A new buffer will be created, using [command] or
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200223 'shell' as the name, prefixed with a "!". If a buffer
224 by this name already exists a number is added in
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200225 parentheses. E.g. if "gdb" exists the second terminal
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200226 buffer will use "!gdb (1)".
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200227
Bram Moolenaarb2412082017-08-20 18:09:14 +0200228 If [range] is given the specified lines are used as
229 input for the job. It will not be possible to type
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200230 keys in the terminal window. For MS-Windows see the
231 ++eof argument below.
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200232
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200233 *term++close* *term++open*
234 Supported [options] are:
235 ++close The terminal window will close
236 automatically when the job terminates.
Bram Moolenaar4d14bac2019-10-20 21:15:15 +0200237 |terminal-close|
Bram Moolenaar1dd98332018-03-16 22:54:53 +0100238 ++noclose The terminal window will NOT close
239 automatically when the job terminates.
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200240 ++open When the job terminates and no window
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200241 shows it, a window will be opened.
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200242 Note that this can be interruptive.
Bram Moolenaar1dd98332018-03-16 22:54:53 +0100243 The last of ++close, ++noclose and ++open
244 matters and rules out earlier arguments.
245
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200246 ++curwin Open the terminal in the current
247 window, do not split the current
248 window. Fails if the current buffer
249 cannot be |abandon|ed.
250 ++hidden Open the terminal in a hidden buffer,
251 no window will be used.
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100252 ++norestore Do not include this terminal window
253 in a session file.
matveyta01148d2024-11-23 14:19:58 +0100254
255 *term++shell*
Bram Moolenaar197c6b72019-11-03 23:37:12 +0100256 ++shell Instead of executing {command}
257 directly, use a shell, like with
Bram Moolenaar938ae282023-02-20 20:44:55 +0000258 `:!command` *E279*
Bram Moolenaar519cc552021-11-16 19:18:26 +0000259 {only works on Unix and MS-Windows}
matveyta01148d2024-11-23 14:19:58 +0100260 The resulting command will look like
261 'shell' 'shellcmdflag' [command]
262 Other options related to `:!command`
263 have no effect.
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +0100264 ++kill={how} When trying to close the terminal
265 window kill the job with {how}. See
266 |term_setkill()| for the values.
Bram Moolenaarb2412082017-08-20 18:09:14 +0200267 ++rows={height} Use {height} for the terminal window
Bram Moolenaar40962ec2018-01-28 22:47:25 +0100268 height. If the terminal uses the full
269 Vim height (no window above or below
Bram Moolenaar0b0f0992018-05-22 21:41:30 +0200270 the terminal window) the command line
Bram Moolenaar40962ec2018-01-28 22:47:25 +0100271 height will be reduced as needed.
Bram Moolenaarb2412082017-08-20 18:09:14 +0200272 ++cols={width} Use {width} for the terminal window
Bram Moolenaar40962ec2018-01-28 22:47:25 +0100273 width. If the terminal uses the full
274 Vim width (no window left or right of
275 the terminal window) this value is
276 ignored.
Bram Moolenaard2842ea2019-09-26 23:08:54 +0200277 ++eof={text} When using [range]: text to send after
Bram Moolenaare09ba7b2017-09-09 22:19:47 +0200278 the last line was written. Cannot
279 contain white space. A CR is
280 appended. For MS-Windows the default
281 is to send CTRL-D.
Bram Moolenaaref68e4f2017-09-02 16:28:36 +0200282 E.g. for a shell use "++eof=exit" and
283 for Python "++eof=exit()". Special
284 codes can be used like with `:map`,
285 e.g. "<C-Z>" for CTRL-Z.
Bram Moolenaarc6ddce32019-02-08 12:47:03 +0100286 ++type={pty} (MS-Windows only): Use {pty} as the
287 virtual console. See 'termwintype'
288 for the values.
Bram Moolenaard2842ea2019-09-26 23:08:54 +0200289 ++api={expr} Permit the function name starting with
290 {expr} to be called as |terminal-api|
291 function. If {expr} is empty then no
292 function can be called.
Bram Moolenaarc6ddce32019-02-08 12:47:03 +0100293
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200294 If you want to use more options use the |term_start()|
295 function.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +0200296 If you want to split the window vertically, use: >
297 :vertical terminal
298< Or short: >
299 :vert ter
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200300
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +0100301When the buffer associated with the terminal is forcibly unloaded or wiped out
302the job is killed, similar to calling `job_stop(job, "kill")` .
303Closing the window normally results in |E947|. When a kill method was set
304with "++kill={how}" or |term_setkill()| then closing the window will use that
305way to kill or interrupt the job. For example: >
306 :term ++kill=term tail -f /tmp/log
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200307
Bram Moolenaare561a7e2017-08-29 22:44:59 +0200308So long as the job is running the window behaves like it contains a modified
Bram Moolenaaref68e4f2017-09-02 16:28:36 +0200309buffer. Trying to close the window with `CTRL-W :quit` fails. When using
Yee Cheng Chin42826332022-10-10 11:46:16 +0100310`CTRL-W :quit!` the job is ended. The text in the window is lost, the buffer
311is deleted. With `CTRL-W :bunload!` the buffer remains but will be empty.
Bram Moolenaaref68e4f2017-09-02 16:28:36 +0200312
313Trying to close the window with `CTRL-W :close` also fails. Using
314`CTRL-W :close!` will close the window and make the buffer hidden.
Bram Moolenaare561a7e2017-08-29 22:44:59 +0200315
316You can use `CTRL-W :hide` to close the terminal window and make the buffer
317hidden, the job keeps running. The `:buffer` command can be used to turn the
318current window into a terminal window. If there are unsaved changes this
Bram Moolenaar0b0f0992018-05-22 21:41:30 +0200319fails, use ! to force, as usual.
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200320
Bram Moolenaar4d14bac2019-10-20 21:15:15 +0200321 *terminal-close*
Christian Brabandt0e17f7e2024-03-17 20:14:25 +0100322When the terminal job finishes and no [command] was given (e.g. the 'shell'
323command was executed), the terminal window will be closed by default (unless
324the buffer in next window receiving the space has the 'nobuflisted' option set,
325in which case the terminal window would not be closed automatically, but a new
326empty buffer would be opened in that window).
327
Bram Moolenaar4d14bac2019-10-20 21:15:15 +0200328When the terminal window is closed, e.g. when the shell exits and "++close"
329argument was used, and this is the last normal Vim window, then Vim will exit.
330This is like using |:quit| in a normal window. Help and preview windows are
331not counted.
332
Bram Moolenaar8cad9302017-08-12 14:32:32 +0200333To have a background job run without a window, and open the window when it's
334done, use options like this: >
335 :term ++hidden ++open make
336Note that the window will open at an unexpected moment, this will interrupt
337what you are doing.
338
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200339 *E947* *E948*
Bram Moolenaar78712a72017-08-05 14:50:12 +0200340So long as the job is running, the buffer is considered modified and Vim
341cannot be quit easily, see |abandon|.
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200342
343When the job has finished and no changes were made to the buffer: closing the
344window will wipe out the buffer.
345
346Before changes can be made to a terminal buffer, the 'modifiable' option must
347be set. This is only possible when the job has finished. At the first change
348the buffer will become a normal buffer and the highlighting is removed.
349You may want to change the buffer name with |:file| to be able to write, since
350the buffer name will still be set to the command.
351
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200352
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200353Resizing ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +0100354 *terminal-resizing*
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200355The size of the terminal can be in one of three modes:
356
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02003571. The 'termwinsize' option is empty: The terminal size follows the window
358 size. The minimal size is 2 screen lines with 10 cells.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200359
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02003602. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number
361 of screen rows and "cols" is the minimal number of cells.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200362
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02003633. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower
364 case). The terminal size is fixed to the specified number of screen lines
365 and cells. If the window is bigger there will be unused empty space.
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200366
367If the window is smaller than the terminal size, only part of the terminal can
368be seen (the lower-left part).
369
370The |term_getsize()| function can be used to get the current size of the
371terminal. |term_setsize()| can be used only when in the first or second mode,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +0200372not when 'termwinsize' is "rowsXcols".
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200373
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200374
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200375Terminal-Job and Terminal-Normal mode ~
Bram Moolenaar8c041b62018-04-14 18:14:06 +0200376 *Terminal-mode* *Terminal-Job*
Bram Moolenaar423802d2017-07-30 16:52:24 +0200377When the job is running the contents of the terminal is under control of the
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200378job. That includes the cursor position. Typed keys are sent to the job.
379The terminal contents can change at any time. This is called Terminal-Job
380mode.
Bram Moolenaar423802d2017-07-30 16:52:24 +0200381
Bram Moolenaar7dda86f2018-04-20 22:36:41 +0200382Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200383contents of the terminal window is under control of Vim, the job output is
384suspended. CTRL-\ CTRL-N does the same.
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200385
Bram Moolenaar1b9645d2017-09-17 23:03:31 +0200386Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200387|term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are.
388
Bram Moolenaar8c041b62018-04-14 18:14:06 +0200389It is not possible to enter Insert mode from Terminal-Job mode.
390
391 *Terminal-Normal* *E946*
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200392In Terminal-Normal mode you can move the cursor around with the usual Vim
393commands, Visually mark text, yank text, etc. But you cannot change the
394contents of the buffer. The commands that would start insert mode, such as
395'i' and 'a', return to Terminal-Job mode. The window will be updated to show
Bram Moolenaar1b9645d2017-09-17 23:03:31 +0200396the contents of the terminal. |:startinsert| is ineffective.
Bram Moolenaar423802d2017-07-30 16:52:24 +0200397
Bram Moolenaardd693ce2017-08-10 23:15:19 +0200398In Terminal-Normal mode the statusline and window title show "(Terminal)". If
399the job ends while in Terminal-Normal mode this changes to
400"(Terminal-finished)".
Bram Moolenaar423802d2017-07-30 16:52:24 +0200401
Bram Moolenaar8c041b62018-04-14 18:14:06 +0200402When the job outputs lines in the terminal, such that the contents scrolls off
403the top, those lines are remembered and can be seen in Terminal-Normal mode.
Bram Moolenaar7dda86f2018-04-20 22:36:41 +0200404The number of lines is limited by the 'termwinscroll' option. When going over
Bram Moolenaar7db25fe2018-05-13 00:02:36 +0200405this limit, the first 10% of the scrolled lines are deleted and are lost.
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200406
Bram Moolenaar423802d2017-07-30 16:52:24 +0200407
Bram Moolenaarc572da52017-08-27 16:52:01 +0200408Cursor style ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +0100409 *terminal-cursor-style*
Bram Moolenaarc572da52017-08-27 16:52:01 +0200410By default the cursor in the terminal window uses a not blinking block. The
411normal xterm escape sequences can be used to change the blinking state and the
412shape. Once focus leaves the terminal window Vim will restore the original
413cursor.
414
415An exception is when xterm is started with the "-bc" argument, or another way
416that causes the cursor to blink. This actually means that the blinking flag
417is inverted. Since Vim cannot detect this, the terminal window cursor
418blinking will also be inverted.
419
420
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100421Session ~
422 *terminal-session*
423A terminal window will be restored when using a session file, if possible and
424wanted.
425
426If "terminal" was removed from 'sessionoptions' then no terminal windows will
427be restored.
428
429If the job in the terminal was finished the window will not be restored.
430
431If the terminal can be restored, the command that was used to open it will be
432used again. To change this use the |term_setrestore()| function. This can
433also be used to not restore a specific terminal by setting the command to
434"NONE".
435
436
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +0100437Special keys ~
438 *terminal-special-keys*
439Since the terminal emulator simulates an xterm, only escape sequences that
440both Vim and xterm recognize will be available in the terminal window. If you
441want to pass on other escape sequences to the job running in the terminal you
442need to set up forwarding. Example: >
443 tmap <expr> <Esc>]b SendToTerm("\<Esc>]b")
Bram Moolenaar60e73f22017-11-12 18:02:06 +0100444 func SendToTerm(what)
445 call term_sendkeys('', a:what)
446 return ''
447 endfunc
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200448
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +0100449
450Unix ~
451 *terminal-unix*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200452On Unix a pty is used to make it possible to run all kinds of commands. You
453can even run Vim in the terminal! That's used for debugging, see below.
454
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200455Environment variables are used to pass information to the running job:
Bram Moolenaar9a993e32018-04-05 22:15:22 +0200456 TERM the name of the terminal, from the 'term' option or
457 $TERM in the GUI; falls back to "xterm" if it does not
458 start with "xterm"
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200459 ROWS number of rows in the terminal initially
460 LINES same as ROWS
461 COLUMNS number of columns in the terminal initially
462 COLORS number of colors, 't_Co' (256*256*256 in the GUI)
463 VIM_SERVERNAME v:servername
Bram Moolenaard7a137f2018-06-12 18:05:24 +0200464 VIM_TERMINAL v:version
Bram Moolenaarf55e4c82017-08-01 20:44:53 +0200465
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200466
467MS-Windows ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +0100468 *terminal-ms-windows*
Bram Moolenaar8a773062017-07-24 22:29:21 +0200469On MS-Windows winpty is used to make it possible to run all kind of commands.
470Obviously, they must be commands that run in a terminal, not open their own
471window.
472
473You need the following two files from winpty:
474
475 winpty.dll
476 winpty-agent.exe
477
478You can download them from the following page:
479
480 https://github.com/rprichard/winpty
481
Bram Moolenaar8e539c52017-08-18 22:57:06 +0200482Just put the files somewhere in your PATH. You can set the 'winptydll' option
483to point to the right file, if needed. If you have both the 32-bit and 64-bit
484version, rename to winpty32.dll and winpty64.dll to match the way Vim was
485build.
Bram Moolenaar5acd9872019-02-16 13:35:13 +0100486 *ConPTY* *E982*
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +0100487On more recent versions of MS-Windows 10 (beginning with the "October 2018
488Update"), winpty is no longer required. On those versions, |:terminal| will use
489Windows' built-in support for hosting terminal applications, "ConPTY". When
490ConPTY is in use, there may be rendering artifacts regarding ambiguous-width
Bram Moolenaar5acd9872019-02-16 13:35:13 +0100491characters. If you encounter any such issues, install "winpty". Until the
492ConPTY problems have been fixed "winpty" will be preferred.
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200493
Bram Moolenaar52dbb5e2017-11-21 18:11:27 +0100494Environment variables are used to pass information to the running job:
495 VIM_SERVERNAME v:servername
496
Aliaksei Budavei5eaacef2025-01-11 17:10:06 +0100497 *git-vimdumps*
498There exists a git-difftool extension called `git-vimdumps` that can be used
499to conveniently inspect screendump files and diff them. Please see in the Vim
500Repository the file `src/testdir/commondumps.vim` on how to create and use
501this git extension.
502
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200503==============================================================================
Bram Moolenaar6bf2c622019-07-04 17:12:09 +02005042. Terminal functions *terminal-function-details*
505
506 *term_dumpdiff()*
507term_dumpdiff({filename}, {filename} [, {options}])
508 Open a new window displaying the difference between the two
509 files. The files must have been created with
510 |term_dumpwrite()|.
511 Returns the buffer number or zero when the diff fails.
512 Also see |terminal-diff|.
513 NOTE: this does not work with double-width characters yet.
514
515 The top part of the buffer contains the contents of the first
516 file, the bottom part of the buffer contains the contents of
517 the second file. The middle part shows the differences.
518 The parts are separated by a line of equals.
519
520 If the {options} argument is present, it must be a Dict with
521 these possible members:
522 "term_name" name to use for the buffer name, instead
523 of the first file name.
524 "term_rows" vertical size to use for the terminal,
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200525 instead of using 'termwinsize', but
526 respecting the minimal size
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200527 "term_cols" horizontal size to use for the terminal,
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200528 instead of using 'termwinsize', but
529 respecting the minimal size
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200530 "vertical" split the window vertically
531 "curwin" use the current window, do not split the
532 window; fails if the current buffer
533 cannot be |abandon|ed
534 "bufnr" do not create a new buffer, use the
535 existing buffer "bufnr". This buffer
536 must have been previously created with
537 term_dumpdiff() or term_dumpload() and
538 visible in a window.
539 "norestore" do not add the terminal window to a
540 session file
541
542 Each character in the middle part indicates a difference. If
543 there are multiple differences only the first in this list is
544 used:
545 X different character
546 w different width
547 f different foreground color
548 b different background color
549 a different attribute
550 + missing position in first file
551 - missing position in second file
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100552 > cursor position in first file, not in second
Bram Moolenaar23515b42020-11-29 14:36:24 +0100553 < cursor position in second file, not in first
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200554
555 Using the "s" key the top and bottom parts are swapped. This
556 makes it easy to spot a difference.
557
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200558 Can also be used as a |method|: >
559 GetFilename()->term_dumpdiff(otherfile)
560<
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200561 Return type: |Number|
562
563
564term_dumpload({filename} [, {options}]) *term_dumpload()*
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200565 Open a new window displaying the contents of {filename}
566 The file must have been created with |term_dumpwrite()|.
567 Returns the buffer number or zero when it fails.
568 Also see |terminal-diff|.
569
570 For {options} see |term_dumpdiff()|.
571
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200572 Can also be used as a |method|: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200573 GetFilename()->term_dumpload()
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200574<
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200575 Return type: |Number|
576
577
578term_dumpwrite({buf}, {filename} [, {options}]) *term_dumpwrite()*
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200579 Dump the contents of the terminal screen of {buf} in the file
580 {filename}. This uses a format that can be used with
581 |term_dumpload()| and |term_dumpdiff()|.
582 If the job in the terminal already finished an error is given:
583 *E958*
584 If {filename} already exists an error is given: *E953*
585 Also see |terminal-diff|.
586
587 {options} is a dictionary with these optional entries:
588 "rows" maximum number of rows to dump
589 "columns" maximum number of columns to dump
590
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200591 Can also be used as a |method|, the base is used for the file
592 name: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +0200593 GetFilename()->term_dumpwrite(bufnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200594<
595 Return type: |Number|
596
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200597
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200598term_getaltscreen({buf}) *term_getaltscreen()*
599 Returns 1 if the terminal of {buf} is using the alternate
600 screen.
601 {buf} is used as with |term_getsize()|.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200602
603 Can also be used as a |method|: >
604 GetBufnr()->term_getaltscreen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200605<
606 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200607
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200608
609term_getansicolors({buf}) *term_getansicolors()*
610 Get the ANSI color palette in use by terminal {buf}.
611 Returns a List of length 16 where each element is a String
612 representing a color in hexadecimal "#rrggbb" format.
613 Also see |term_setansicolors()| and |g:terminal_ansi_colors|.
614 If neither was used returns the default colors.
615
616 {buf} is used as with |term_getsize()|. If the buffer does not
617 exist or is not a terminal window, an empty list is returned.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200618
619 Can also be used as a |method|: >
620 GetBufnr()->term_getansicolors()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200621<
622 Return type: list<string> or list<any>
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200623
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200624 {only available when compiled with GUI enabled and/or the
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200625 |+termguicolors| feature}
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200626
627term_getattr({attr}, {what}) *term_getattr()*
628 Given {attr}, a value returned by term_scrape() in the "attr"
629 item, return whether {what} is on. {what} can be one of:
630 bold
631 italic
632 underline
633 strike
634 reverse
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200635
636 Can also be used as a |method|: >
637 GetAttr()->term_getattr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200638<
639 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200640
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200641
642term_getcursor({buf}) *term_getcursor()*
643 Get the cursor position of terminal {buf}. Returns a list with
644 two numbers and a dictionary: [row, col, dict].
645
646 "row" and "col" are one based, the first screen cell is row
647 1, column 1. This is the cursor position of the terminal
648 itself, not of the Vim window.
649
650 "dict" can have these members:
651 "visible" one when the cursor is visible, zero when it
652 is hidden.
653 "blink" one when the cursor is blinking, zero when it
654 is not blinking.
655 "shape" 1 for a block cursor, 2 for underline and 3
656 for a vertical bar.
657 "color" color of the cursor, e.g. "green"
658
659 {buf} must be the buffer number of a terminal window. If the
660 buffer does not exist or is not a terminal window, an empty
661 list is returned.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200662
663 Can also be used as a |method|: >
664 GetBufnr()->term_getcursor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200665<
666 Return type: list<any>
667
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200668
669term_getjob({buf}) *term_getjob()*
670 Get the Job associated with terminal window {buf}.
671 {buf} is used as with |term_getsize()|.
Ernie Raela78eb252024-06-13 17:24:54 +0200672 Returns |v:null| when there is no job. In Vim9 script, return
h-east84ac2122024-06-17 18:12:30 +0200673 |null_job| when there is no job.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200674
675 Can also be used as a |method|: >
676 GetBufnr()->term_getjob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200677<
678 Return type: |job|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200679
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200680
681term_getline({buf}, {row}) *term_getline()*
682 Get a line of text from the terminal window of {buf}.
683 {buf} is used as with |term_getsize()|.
684
685 The first line has {row} one. When {row} is "." the cursor
686 line is used. When {row} is invalid an empty string is
687 returned.
688
689 To get attributes of each character use |term_scrape()|.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200690
691 Can also be used as a |method|: >
692 GetBufnr()->term_getline(row)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200693<
694 Return type: |String|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200695
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200696
697term_getscrolled({buf}) *term_getscrolled()*
698 Return the number of lines that scrolled to above the top of
699 terminal {buf}. This is the offset between the row number
700 used for |term_getline()| and |getline()|, so that: >
701 term_getline(buf, N)
702< is equal to: >
703 getline(N + term_getscrolled(buf))
704< (if that line exists).
705
706 {buf} is used as with |term_getsize()|.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200707
708 Can also be used as a |method|: >
709 GetBufnr()->term_getscrolled()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200710<
711 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200712
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200713
714term_getsize({buf}) *term_getsize()*
715 Get the size of terminal {buf}. Returns a list with two
716 numbers: [rows, cols]. This is the size of the terminal, not
717 the window containing the terminal.
718
719 {buf} must be the buffer number of a terminal window. Use an
720 empty string for the current buffer. If the buffer does not
721 exist or is not a terminal window, an empty list is returned.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200722
723 Can also be used as a |method|: >
724 GetBufnr()->term_getsize()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200725<
726 Return type: list<number> or list<any>
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200727
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200728
729term_getstatus({buf}) *term_getstatus()*
Bram Moolenaar29634562020-01-09 21:46:04 +0100730 Get the status of terminal {buf}. This returns a String with
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +0100731 a comma-separated list of these items:
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200732 running job is running
733 finished job has finished
734 normal in Terminal-Normal mode
735 One of "running" or "finished" is always present.
736
737 {buf} must be the buffer number of a terminal window. If the
738 buffer does not exist or is not a terminal window, an empty
739 string is returned.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200740
741 Can also be used as a |method|: >
742 GetBufnr()->term_getstatus()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200743<
744 Return type: |String|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200745
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200746
747term_gettitle({buf}) *term_gettitle()*
748 Get the title of terminal {buf}. This is the title that the
749 job in the terminal has set.
750
751 {buf} must be the buffer number of a terminal window. If the
752 buffer does not exist or is not a terminal window, an empty
753 string is returned.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200754
755 Can also be used as a |method|: >
756 GetBufnr()->term_gettitle()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200757<
758 Return type: |String|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200759
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200760
761term_gettty({buf} [, {input}]) *term_gettty()*
762 Get the name of the controlling terminal associated with
763 terminal window {buf}. {buf} is used as with |term_getsize()|.
764
765 When {input} is omitted or 0, return the name for writing
766 (stdout). When {input} is 1 return the name for reading
767 (stdin). On UNIX, both return same name.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200768
769 Can also be used as a |method|: >
770 GetBufnr()->term_gettty()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200771<
772 Return type: |String|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200773
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200774
775term_list() *term_list()*
776 Return a list with the buffer numbers of all buffers for
777 terminal windows.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200778
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200779 Return type: list<number> or list<any>
780
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200781
782term_scrape({buf}, {row}) *term_scrape()*
783 Get the contents of {row} of terminal screen of {buf}.
784 For {buf} see |term_getsize()|.
785
786 The first line has {row} one. When {row} is "." the cursor
787 line is used. When {row} is invalid an empty string is
788 returned.
789
790 Return a List containing a Dict for each screen cell:
791 "chars" character(s) at the cell
792 "fg" foreground color as #rrggbb
793 "bg" background color as #rrggbb
794 "attr" attributes of the cell, use |term_getattr()|
795 to get the individual flags
796 "width" cell width: 1 or 2
Bram Moolenaar942db232021-02-13 18:14:48 +0100797 For a double-width cell there is one item, thus the list can
798 be shorter than the width of the terminal.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200799
800 Can also be used as a |method|: >
801 GetBufnr()->term_scrape(row)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200802<
803 Return type: list<dict<any>> or list<any>
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200804
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200805
806term_sendkeys({buf}, {keys}) *term_sendkeys()*
807 Send keystrokes {keys} to terminal {buf}.
808 {buf} is used as with |term_getsize()|.
809
810 {keys} are translated as key sequences. For example, "\<c-x>"
811 means the character CTRL-X.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200812
813 Can also be used as a |method|: >
814 GetBufnr()->term_sendkeys(keys)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200815<
816 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200817
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200818
819term_setansicolors({buf}, {colors}) *term_setansicolors()*
820 Set the ANSI color palette used by terminal {buf}.
821 {colors} must be a List of 16 valid color names or hexadecimal
822 color codes, like those accepted by |highlight-guifg|.
823 Also see |term_getansicolors()| and |g:terminal_ansi_colors|.
824
825 The colors normally are:
826 0 black
827 1 dark red
828 2 dark green
829 3 brown
830 4 dark blue
831 5 dark magenta
832 6 dark cyan
833 7 light grey
834 8 dark grey
835 9 red
836 10 green
837 11 yellow
838 12 blue
839 13 magenta
840 14 cyan
841 15 white
842
843 These colors are used in the GUI and in the terminal when
844 'termguicolors' is set. When not using GUI colors (GUI mode
845 or 'termguicolors'), the terminal window always uses the 16
846 ANSI colors of the underlying terminal.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200847
848 Can also be used as a |method|: >
849 GetBufnr()->term_setansicolors(colors)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200850<
851 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200852
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200853 {only available with GUI enabled and/or the |+termguicolors|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200854 feature}
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200855
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200856
857term_setapi({buf}, {expr}) *term_setapi()*
858 Set the function name prefix to be used for the |terminal-api|
859 function in terminal {buf}. For example: >
860 :call term_setapi(buf, "Myapi_")
861 :call term_setapi(buf, "")
862<
863 The default is "Tapi_". When {expr} is an empty string then
864 no |terminal-api| function can be used for {buf}.
865
866 When used as a method the base is used for {buf}: >
867 GetBufnr()->term_setapi({expr})
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200868<
869 Return type: |Number|
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200870
871
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200872term_setkill({buf}, {how}) *term_setkill()*
873 When exiting Vim or trying to close the terminal window in
874 another way, {how} defines whether the job in the terminal can
875 be stopped.
876 When {how} is empty (the default), the job will not be
877 stopped, trying to exit will result in |E947|.
878 Otherwise, {how} specifies what signal to send to the job.
879 See |job_stop()| for the values.
880
881 After sending the signal Vim will wait for up to a second to
882 check that the job actually stopped.
883
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200884 Can also be used as a |method|: >
885 GetBufnr()->term_setkill(how)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200886<
887 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200888
889
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200890term_setrestore({buf}, {command}) *term_setrestore()*
891 Set the command to write in a session file to restore the job
892 in this terminal. The line written in the session file is: >
893 terminal ++curwin ++cols=%d ++rows=%d {command}
894< Make sure to escape the command properly.
895
896 Use an empty {command} to run 'shell'.
897 Use "NONE" to not restore this window.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200898
899 Can also be used as a |method|: >
900 GetBufnr()->term_setrestore(command)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200901<
902 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200903
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200904
905term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955*
906 Set the size of terminal {buf}. The size of the window
907 containing the terminal will also be adjusted, if possible.
908 If {rows} or {cols} is zero or negative, that dimension is not
909 changed.
910
911 {buf} must be the buffer number of a terminal window. Use an
912 empty string for the current buffer. If the buffer does not
913 exist or is not a terminal window, an error is given.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200914
915 Can also be used as a |method|: >
916 GetBufnr()->term_setsize(rows, cols)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200917<
918 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200919
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200920
921term_start({cmd} [, {options}]) *term_start()*
922 Open a terminal window and run {cmd} in it.
923
924 {cmd} can be a string or a List, like with |job_start()|. The
925 string "NONE" can be used to open a terminal window without
926 starting a job, the pty of the terminal can be used by a
927 command like gdb.
928
929 Returns the buffer number of the terminal window. If {cmd}
930 cannot be executed the window does open and shows an error
931 message.
932 If opening the window fails zero is returned.
933
934 {options} are similar to what is used for |job_start()|, see
935 |job-options|. However, not all options can be used. These
936 are supported:
937 all timeout options
938 "stoponexit", "cwd", "env"
939 "callback", "out_cb", "err_cb", "exit_cb", "close_cb"
940 "in_io", "in_top", "in_bot", "in_name", "in_buf"
941 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
942 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
943 However, at least one of stdin, stdout or stderr must be
944 connected to the terminal. When I/O is connected to the
945 terminal then the callback function for that part is not used.
946
947 There are extra options:
948 "term_name" name to use for the buffer name, instead
949 of the command name.
950 "term_rows" vertical size to use for the terminal,
Bram Moolenaar5300be62021-11-13 10:27:40 +0000951 instead of using 'termwinsize'; valid
952 range is from zero to 1000
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200953 "term_cols" horizontal size to use for the terminal,
954 instead of using 'termwinsize'
955 "vertical" split the window vertically; note that
956 other window position can be defined with
957 command modifiers, such as |:belowright|.
958 "curwin" use the current window, do not split the
959 window; fails if the current buffer
960 cannot be |abandon|ed
961 "hidden" do not open a window
962 "norestore" do not add the terminal window to a
963 session file
964 "term_kill" what to do when trying to close the
965 terminal window, see |term_setkill()|
966 "term_finish" What to do when the job is finished:
967 "close": close any windows
968 "open": open window if needed
969 Note that "open" can be interruptive.
970 See |term++close| and |term++open|.
971 "term_opencmd" command to use for opening the window when
972 "open" is used for "term_finish"; must
973 have "%d" where the buffer number goes,
974 e.g. "10split|buffer %d"; when not
975 specified "botright sbuf %d" is used
Bram Moolenaar83d47902020-03-26 20:34:00 +0100976 "term_highlight" highlight group to use instead of
977 "Terminal"
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200978 "eof_chars" Text to send after all buffer lines were
979 written to the terminal. When not set
980 CTRL-D is used on MS-Windows. For Python
981 use CTRL-Z or "exit()". For a shell use
982 "exit". A CR is always added.
983 "ansi_colors" A list of 16 color names or hex codes
984 defining the ANSI palette used in GUI
985 color modes. See |g:terminal_ansi_colors|.
986 "tty_type" (MS-Windows only): Specify which pty to
987 use. See 'termwintype' for the values.
Bram Moolenaard2842ea2019-09-26 23:08:54 +0200988 "term_api" function name prefix for the
989 |terminal-api| function. See
990 |term_setapi()|.
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200991
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200992 Can also be used as a |method|: >
993 GetCommand()->term_start()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200994<
995 Return type: |Number|
Bram Moolenaar7ee80f72019-09-08 20:55:06 +0200996
Bram Moolenaar6bf2c622019-07-04 17:12:09 +0200997
998term_wait({buf} [, {time}]) *term_wait()*
999 Wait for pending updates of {buf} to be handled.
1000 {buf} is used as with |term_getsize()|.
1001 {time} is how long to wait for updates to arrive in msec. If
Yee Cheng Chine70587d2025-02-13 20:55:45 +01001002 not set then 10 msec will be used. Queued messages will also
1003 be processed similar to |:sleep|.
Bram Moolenaar7ee80f72019-09-08 20:55:06 +02001004
1005 Can also be used as a |method|: >
1006 GetBufnr()->term_wait()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001007<
1008 Return type: |Number|
Bram Moolenaar6bf2c622019-07-04 17:12:09 +02001009
1010==============================================================================
10113. Terminal communication *terminal-communication*
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001012
1013There are several ways to communicate with the job running in a terminal:
1014- Use |term_sendkeys()| to send text and escape sequences from Vim to the job.
1015- Use the JSON API to send encoded commands from the job to Vim.
1016- Use the |client-server| mechanism. This works on machines with an X server
1017 and on MS-Windows.
1018
1019
1020Vim to job: term_sendkeys() ~
1021 *terminal-to-job*
1022This allows for remote controlling the job running in the terminal. It is a
1023one-way mechanism. The job can update the display to signal back to Vim.
1024For example, if a shell is running in a terminal, you can do: >
1025 call term_sendkeys(buf, "ls *.java\<CR>")
1026
1027This requires for the job to be in the right state where it will do the right
1028thing when receiving the keys. For the above example, the shell must be
1029waiting for a command to be typed.
1030
1031For a job that was written for the purpose, you can use the JSON API escape
1032sequence in the other direction. E.g.: >
1033 call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")
1034
1035
1036Job to Vim: JSON API ~
1037 *terminal-api*
1038The job can send JSON to Vim, using a special escape sequence. The JSON
1039encodes a command that Vim understands. Example of such a message: >
1040 <Esc>]51;["drop", "README.md"]<07>
1041
1042The body is always a list, making it easy to find the end: ]<07>.
1043The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
1044similar to what we are doing here.
1045
1046Currently supported commands:
1047
1048 call {funcname} {argument}
1049
Bram Moolenaar2a77d212018-03-26 21:38:52 +02001050 Call a user defined function with {argument}.
1051 The function is called with two arguments: the buffer number
Bram Moolenaar664f3cf2019-12-07 16:03:51 +01001052 of the terminal and {argument}, the decoded JSON argument.
Bram Moolenaard2842ea2019-09-26 23:08:54 +02001053 By default, the function name must start with "Tapi_" to avoid
Bram Moolenaar2a77d212018-03-26 21:38:52 +02001054 accidentally calling a function not meant to be used for the
Bram Moolenaard2842ea2019-09-26 23:08:54 +02001055 terminal API. This can be changed with |term_setapi()|.
Bram Moolenaar2a77d212018-03-26 21:38:52 +02001056 The user function should sanity check the argument.
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001057 The function can use |term_sendkeys()| to send back a reply.
1058 Example in JSON: >
Bram Moolenaar2a77d212018-03-26 21:38:52 +02001059 ["call", "Tapi_Impression", ["play", 14]]
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001060< Calls a function defined like this: >
Bram Moolenaar2a77d212018-03-26 21:38:52 +02001061 function Tapi_Impression(bufnum, arglist)
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001062 if len(a:arglist) == 2
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001063 echomsg "impression " .. a:arglist[0]
1064 echomsg "count " .. a:arglist[1]
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001065 endif
1066 endfunc
Bram Moolenaar2a77d212018-03-26 21:38:52 +02001067< Output from `:echo` may be erased by a redraw, use `:echomsg`
1068 to be able to see it with `:messages`.
1069
Bram Moolenaar333b80a2018-04-04 22:57:29 +02001070 drop {filename} [options]
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001071
1072 Let Vim open a file, like the `:drop` command. If {filename}
1073 is already open in a window, switch to that window. Otherwise
1074 open a new window to edit {filename}.
Bram Moolenaar85eee132018-05-06 17:57:30 +02001075 Note that both the job and Vim may change the current
1076 directory, thus it's best to use the full path.
Bram Moolenaar333b80a2018-04-04 22:57:29 +02001077
1078 [options] is only used when opening a new window. If present,
Bram Moolenaard1caa942020-04-10 22:10:56 +02001079 it must be a Dict. Similarly to |++opt|, these entries are
Bram Moolenaar68e65602019-05-26 21:33:31 +02001080 recognized:
Bram Moolenaar333b80a2018-04-04 22:57:29 +02001081 "ff" file format: "dos", "mac" or "unix"
1082 "fileformat" idem
1083 "enc" overrides 'fileencoding'
1084 "encoding" idem
1085 "bin" sets 'binary'
1086 "binary" idem
1087 "nobin" resets 'binary'
1088 "nobinary" idem
1089 "bad" specifies behavior for bad characters, see
1090 |++bad|
1091
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001092 Example in JSON: >
1093 ["drop", "path/file.txt", {"ff": "dos"}]
1094
Christian Brabandt14e82082025-02-22 13:35:15 +01001095You can use |echoraw()| to make Vim send this escape sequence: >
1096 call echoraw("\<ESC>]51;[\"call\", \"Tapi_TryThis\", [\"hello\", 123]]\x07")
1097 call echoraw("\<Esc>]51;[\"drop\", \"README.md\"]\x07")
1098Note: JSON requires double quotes around string values, hence those have to be
1099escaped.
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001100
1101Rationale: Why not allow for any command or expression? Because that might
1102create a security problem.
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +01001103 *terminal-autoshelldir*
1104This can be used to pass the current directory from a shell to Vim.
1105Put this in your .vimrc: >
Bram Moolenaarfd999452022-08-24 18:30:14 +01001106 def g:Tapi_lcd(_, path: string)
1107 if isdirectory(path)
zeertzjqd086b8f2024-02-25 15:42:52 +08001108 execute 'silent lcd ' .. fnameescape(path)
1109 endif
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +01001110 enddef
1111<
1112And, in a bash init file: >
zeertzjqd086b8f2024-02-25 15:42:52 +08001113 if [[ -n "$VIM_TERMINAL" ]]; then
1114 PROMPT_COMMAND='_vim_sync_PWD'
1115 function _vim_sync_PWD() {
1116 printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD"
1117 }
1118 fi
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +01001119<
1120Or, for zsh: >
1121 if [[ -n "$VIM_TERMINAL" ]]; then
1122 autoload -Uz add-zsh-hook
1123 add-zsh-hook -Uz chpwd _vim_sync_PWD
1124 function _vim_sync_PWD() {
1125 printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD"
1126 }
1127 fi
1128<
1129Or, for fish: >
1130 if test -n "$VIM_TERMINAL"
1131 function _vim_sync_PWD --on-variable=PWD
1132 printf '\033]51;["call", "Tapi_lcd", "%s"]\007' "$PWD"
1133 end
1134 end
Bram Moolenaar8fbaeb12018-03-25 18:20:17 +02001135
1136
1137Using the client-server feature ~
1138 *terminal-client-server*
1139This only works when v:servername is not empty. If needed you can set it,
1140before opening the terminal, with: >
1141 call remote_startserver('vim-server')
1142
1143$VIM_SERVERNAME is set in the terminal to pass on the server name.
1144
1145In the job you can then do something like: >
1146 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
1147This will open the file "some_file.c" and put the cursor on line 123.
1148
1149==============================================================================
Bram Moolenaar6bf2c622019-07-04 17:12:09 +020011504. Remote testing *terminal-testing*
Bram Moolenaare4f25e42017-07-07 11:54:15 +02001151
1152Most Vim tests execute a script inside Vim. For some tests this does not
1153work, running the test interferes with the code being tested. To avoid this
1154Vim is executed in a terminal window. The test sends keystrokes to it and
1155inspects the resulting screen state.
1156
1157Functions ~
1158
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02001159|term_sendkeys()| send keystrokes to a terminal (not subject to tmap)
1160|term_wait()| wait for screen to be updated
1161|term_scrape()| inspect terminal screen
Bram Moolenaare4f25e42017-07-07 11:54:15 +02001162
1163
1164==============================================================================
Bram Moolenaar6bf2c622019-07-04 17:12:09 +020011655. Diffing screen dumps *terminal-diff*
Bram Moolenaarda650582018-02-20 15:51:40 +01001166
1167In some cases it can be bothersome to test that Vim displays the right
1168characters on the screen. E.g. with syntax highlighting. To make this
1169simpler it is possible to take a screen dump of a terminal and compare it to
1170an expected screen dump.
1171
1172Vim uses the window size, text, color and other attributes as displayed. The
1173Vim screen size, font and other properties do not matter. Therefore this
Bram Moolenaar98ef2332018-03-18 14:44:37 +01001174mechanism is portable across systems. A conventional screenshot would reflect
Bram Moolenaarda650582018-02-20 15:51:40 +01001175all differences, including font size and family.
1176
1177
1178Writing a screen dump test for Vim ~
1179 *terminal-dumptest*
1180For an example see the Test_syntax_c() function in
1181src/testdir/test_syntax.vim. The main parts are:
1182- Write a file you want to test with. This is useful for testing syntax
Bram Moolenaar560979e2020-02-04 22:53:05 +01001183 highlighting. You can also start Vim with an empty buffer.
Bram Moolenaarda650582018-02-20 15:51:40 +01001184- Run Vim in a terminal with a specific size. The default is 20 lines of 75
1185 characters. This makes sure the dump is always this size. The function
1186 RunVimInTerminal() takes care of this. Pass it the arguments for the Vim
1187 command.
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02001188- Send any commands to Vim using |term_sendkeys()|. For example: >
Bram Moolenaarda650582018-02-20 15:51:40 +01001189 call term_sendkeys(buf, ":echo &lines &columns\<CR>")
1190- Check that the screen is now in the expected state, using
1191 VerifyScreenDump(). This expects the reference screen dump to be in the
1192 src/testdir/dumps/ directory. Pass the name without ".dump". It is
1193 recommended to use the name of the test function and a sequence number, so
1194 that we know what test is using the file.
1195- Repeat sending commands and checking the state.
1196- Finally stop Vim by calling StopVimInTerminal().
1197
1198The first time you do this you won't have a screen dump yet. Create an empty
1199file for now, e.g.: >
1200 touch src/testdir/dumps/Test_function_name_01.dump
1201
1202The test will then fail, giving you the command to compare the reference dump
1203and the failed dump, e.g.: >
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01001204 call term_dumpdiff("failed/Test_func.dump", "dumps/Test_func.dump")
Bram Moolenaarda650582018-02-20 15:51:40 +01001205
1206Use this command in Vim, with the current directory set to src/testdir.
1207Once you are satisfied with the test, move the failed dump in place of the
1208reference: >
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01001209 :!mv failed/Test_func.dump dumps/Test_func.dump
Bram Moolenaarda650582018-02-20 15:51:40 +01001210
1211
1212Creating a screen dump ~
1213 *terminal-screendump*
Bram Moolenaarda650582018-02-20 15:51:40 +01001214To create the screen dump, run Vim (or any other program) in a terminal and
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02001215make it show the desired state. Then use the |term_dumpwrite()| function to
Bram Moolenaarda650582018-02-20 15:51:40 +01001216create a screen dump file. For example: >
1217 :call term_dumpwrite(77, "mysyntax.dump")
1218
1219Here "77" is the buffer number of the terminal. Use `:ls!` to see it.
1220
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02001221You can view the screen dump with |term_dumpload()|: >
Bram Moolenaarda650582018-02-20 15:51:40 +01001222 :call term_dumpload("mysyntax.dump")
1223
1224To verify that Vim still shows exactly the same screen, run Vim again with
1225exactly the same way to show the desired state. Then create a screen dump
1226again, using a different file name: >
1227 :call term_dumpwrite(88, "test.dump")
1228
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02001229To assert that the files are exactly the same use |assert_equalfile()|: >
Bram Moolenaarda650582018-02-20 15:51:40 +01001230 call assert_equalfile("mysyntax.dump", "test.dump")
1231
1232If there are differences then v:errors will contain the error message.
1233
1234
1235Comparing screen dumps ~
1236 *terminal-diffscreendump*
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02001237|assert_equalfile()| does not make it easy to see what is different.
1238To spot the problem use |term_dumpdiff()|: >
Bram Moolenaarda650582018-02-20 15:51:40 +01001239 call term_dumpdiff("mysyntax.dump", "test.dump")
1240
1241This will open a window consisting of three parts:
12421. The contents of the first dump
12432. The difference between the first and second dump
12443. The contents of the second dump
1245
1246You can usually see what differs in the second part. Use the 'ruler' to
Bram Moolenaar93a1df22018-09-10 11:51:50 +02001247relate it to the position in the first or second dump. Letters indicate the
1248kind of difference:
1249 X different character
1250 > cursor in first but not in second
1251 < cursor in second but not in first
1252 w character width differs (single vs double width)
1253 f foreground color differs
1254 b background color differs
1255 a attribute differs (bold, underline, reverse, etc.)
1256 ? character missing in both
1257 + character missing in first
1258 - character missing in second
Bram Moolenaarda650582018-02-20 15:51:40 +01001259
Bram Moolenaar98ef2332018-03-18 14:44:37 +01001260Alternatively, press "s" to swap the first and second dump. Do this several
Bram Moolenaarda650582018-02-20 15:51:40 +01001261times so that you can spot the difference in the context of the text.
1262
1263==============================================================================
Christian Brabandt9598a632025-01-11 10:14:24 +010012646. Debugging *terminal-debug* *terminal-debugger* *package-termdebug*
Bram Moolenaare4f25e42017-07-07 11:54:15 +02001265
1266The Terminal debugging plugin can be used to debug a program with gdb and view
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001267the source code in a Vim window. Since this is completely contained inside
1268Vim this also works remotely over an ssh connection.
1269
Bram Moolenaarb3307b52018-06-17 21:34:11 +02001270When the |+terminal| feature is missing, the plugin will use the "prompt"
1271buffer type, if possible. The running program will then use a newly opened
1272terminal window. See |termdebug-prompt| below for details.
1273
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001274
1275Starting ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +01001276 *termdebug-starting*
Bram Moolenaarc572da52017-08-27 16:52:01 +02001277Load the plugin with this command: >
1278 packadd termdebug
h-east52e7cc22024-07-28 17:03:29 +02001279When loading the plugin from the |.vimrc| file, add the "!" attribute: >
Christian Brabandt27c55982024-07-14 10:41:08 +02001280 packadd! termdebug
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001281< *:Termdebug*
Bram Moolenaard473c8c2018-08-11 18:00:22 +02001282To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001283command name, for example: >
Bram Moolenaar24a98a02017-09-27 22:23:55 +02001284 :Termdebug vim
Bram Moolenaare4f25e42017-07-07 11:54:15 +02001285
Bram Moolenaarc572da52017-08-27 16:52:01 +02001286This opens two windows:
Bram Moolenaarf0b03c42017-12-17 17:17:07 +01001287
Bram Moolenaar45d5f262017-09-10 19:14:31 +02001288gdb window A terminal window in which "gdb vim" is executed. Here you
1289 can directly interact with gdb. The buffer name is "!gdb".
Bram Moolenaarf0b03c42017-12-17 17:17:07 +01001290
Bram Moolenaar45d5f262017-09-10 19:14:31 +02001291program window A terminal window for the executed program. When "run" is
1292 used in gdb the program I/O will happen in this window, so
1293 that it does not interfere with controlling gdb. The buffer
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001294 name is "debugged program".
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001295
1296The current window is used to show the source code. When gdb pauses the
1297source file location will be displayed, if possible. A sign is used to
Bram Moolenaar664f3cf2019-12-07 16:03:51 +01001298highlight the current position, using highlight group debugPC.
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001299
1300If the buffer in the current window is modified, another window will be opened
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001301to display the current gdb position. You can use `:Winbar` to add a window
1302toolbar there.
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001303
1304Focus the terminal of the executed program to interact with it. This works
1305the same as any command running in a terminal window.
Bram Moolenaare4f25e42017-07-07 11:54:15 +02001306
Bram Moolenaar45d5f262017-09-10 19:14:31 +02001307When the debugger ends, typically by typing "quit" in the gdb window, the two
1308opened windows are closed.
Bram Moolenaarc572da52017-08-27 16:52:01 +02001309
Bram Moolenaarb3623a32018-04-14 18:59:50 +02001310Only one debugger can be active at a time.
Ubaldo Tiberif7f8f0b2024-06-20 22:17:34 +02001311
1312 *termdebug-timeout*
1313Depending on how gdb is launched, termdebug startup time may vary.
1314To avoid termdebug to get stuck if the startup process of gdb takes too long,
1315a configurable timeout is included. Such time out is configurable in terms of
1316multiple of 10ms: >
1317 let g:termdebug_config['timeout'] = 500 # 500 * 10ms = 5 seconds.
1318
1319The default timeout is 3000 ms.
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001320 *:TermdebugCommand*
1321If you want to give specific commands to the command being debugged, you can
1322use the `:TermdebugCommand` command followed by the command name and
1323additional parameters. >
1324 :TermdebugCommand vim --clean -c ':set nu'
Bram Moolenaarb3623a32018-04-14 18:59:50 +02001325
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001326Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang
1327argument to start the command right away, without pausing at the gdb window
1328(and cursor will be in the debugged window). For example: >
1329 :TermdebugCommand! vim --clean
1330
1331To attach gdb to an already running executable or use a core file, pass extra
Bram Moolenaarb3623a32018-04-14 18:59:50 +02001332arguments. E.g.: >
1333 :Termdebug vim core
1334 :Termdebug vim 98343
1335
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001336If no argument is given, you'll end up in a gdb window, in which you need to
1337specify which command to run using e.g. the gdb `file` command.
1338
Bram Moolenaarc572da52017-08-27 16:52:01 +02001339
Bram Moolenaar24a98a02017-09-27 22:23:55 +02001340Example session ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +01001341 *termdebug-example*
Bram Moolenaar24a98a02017-09-27 22:23:55 +02001342Start in the Vim "src" directory and build Vim: >
1343 % make
Bram Moolenaar1ff14ba2019-11-02 14:09:23 +01001344Make sure that debug symbols are present, usually that means that $CFLAGS
1345includes "-g".
1346
Bram Moolenaar24a98a02017-09-27 22:23:55 +02001347Start Vim: >
1348 % ./vim
Bram Moolenaar1ff14ba2019-11-02 14:09:23 +01001349
Bram Moolenaar24a98a02017-09-27 22:23:55 +02001350Load the termdebug plugin and start debugging Vim: >
1351 :packadd termdebug
1352 :Termdebug vim
1353You should now have three windows:
1354 source - where you started, has a window toolbar with buttons
1355 gdb - you can type gdb commands here
1356 program - the executed program will use this window
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001357
Bram Moolenaar24a98a02017-09-27 22:23:55 +02001358You can use CTRL-W CTRL-W or the mouse to move focus between windows.
1359Put focus on the gdb window and type: >
1360 break ex_help
1361 run
1362Vim will start running in the program window. Put focus there and type: >
1363 :help gui
Bram Moolenaar664f3cf2019-12-07 16:03:51 +01001364Gdb will run into the ex_help breakpoint. The source window now shows the
Bram Moolenaarde1a8312018-06-19 16:59:54 +02001365ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the
1366breakpoint was set. The line where the debugger stopped is highlighted. You
1367can now step through the program. Let's use the mouse: click on the "Next"
1368button in the window toolbar. You will see the highlighting move as the
1369debugger executes a line of source code.
Bram Moolenaar24a98a02017-09-27 22:23:55 +02001370
1371Click "Next" a few times until the for loop is highlighted. Put the cursor on
1372the end of "eap->arg", then click "Eval" in the toolbar. You will see this
1373displayed:
1374 "eap->arg": 0x555555e68855 "gui" ~
1375This way you can inspect the value of local variables. You can also focus the
1376gdb window and use a "print" command, e.g.: >
1377 print *eap
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001378If mouse pointer movements are working, Vim will also show a balloon when the
1379mouse rests on text that can be evaluated by gdb.
Bram Moolenaar24a98a02017-09-27 22:23:55 +02001380
1381Now go back to the source window and put the cursor on the first line after
1382the for loop, then type: >
1383 :Break
1384You will see a ">>" marker appear, this indicates the new breakpoint. Now
1385click "Cont" in the toolbar and the code until the breakpoint will be
1386executed.
1387
1388You can type more advanced commands in the gdb window. For example, type: >
1389 watch curbuf
1390Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
1391will now continue until the value of "curbuf" changes, which is in do_ecmd().
1392To remove this watchpoint again type in the gdb window: >
1393 delete 3
1394
1395You can see the stack by typing in the gdb window: >
1396 where
1397Move through the stack frames, e.g. with: >
1398 frame 3
1399The source window will show the code, at the point where the call was made to
1400a deeper level.
1401
1402
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001403Stepping through code ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +01001404 *termdebug-stepping*
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001405Put focus on the gdb window to type commands there. Some common ones are:
Bram Moolenaar60e73f22017-11-12 18:02:06 +01001406- CTRL-C interrupt the program
1407- next execute the current line and stop at the next line
1408- step execute the current line and stop at the next statement,
1409 entering functions
Bram Moolenaar75ab5902022-04-18 15:36:40 +01001410- until execute until past the current cursor line or past a specified
1411 position or the current stack frame returns
Bram Moolenaar60e73f22017-11-12 18:02:06 +01001412- finish execute until leaving the current function
1413- where show the stack
1414- frame N go to the Nth stack frame
1415- continue continue execution
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001416
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001417 *:Run* *:Arguments*
1418In the window showing the source code these commands can be used to control
1419gdb:
Christian Brabandtc52a8562024-06-17 05:29:37 +02001420 `:Run` [args] run the program with [args] or the previous arguments
1421 `:Arguments` {args} set arguments for the next `:Run`
Bram Moolenaar60e73f22017-11-12 18:02:06 +01001422
Bram Moolenaar589edb32019-09-20 14:38:13 +02001423 *:Break* set a breakpoint at the cursor position
1424 :Break {position}
Bram Moolenaar2e693a82019-10-16 22:35:02 +02001425 set a breakpoint at the specified position
iam28th323dda12023-12-14 20:30:26 +01001426 *:Tbreak* set a temporary breakpoint at the cursor position
1427 :Tbreak {position}
1428 set a temporary breakpoint at the specified position
Bram Moolenaar589edb32019-09-20 14:38:13 +02001429 *:Clear* delete the breakpoint at the cursor position
Bram Moolenaar60e73f22017-11-12 18:02:06 +01001430
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001431 *:Step* execute the gdb "step" command
1432 *:Over* execute the gdb "next" command (`:Next` is a Vim command)
Bram Moolenaar75ab5902022-04-18 15:36:40 +01001433 *:Until* execute the gdb "until" command
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001434 *:Finish* execute the gdb "finish" command
1435 *:Continue* execute the gdb "continue" command
1436 *:Stop* interrupt the program
Bram Moolenaar45d5f262017-09-10 19:14:31 +02001437
Bram Moolenaarf0b03c42017-12-17 17:17:07 +01001438If 'mouse' is set the plugin adds a window toolbar with these entries:
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001439 Step `:Step`
1440 Next `:Over`
1441 Finish `:Finish`
1442 Cont `:Continue`
1443 Stop `:Stop`
1444 Eval `:Evaluate`
Bram Moolenaarf0b03c42017-12-17 17:17:07 +01001445This way you can use the mouse to perform the most common commands. You need
1446to have the 'mouse' option set to enable mouse clicks.
Bram Moolenaard13166e2022-11-18 21:49:57 +00001447See |termdebug_winbar| for configuring this toolbar.
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001448 *:Winbar*
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001449You can add the window toolbar in other windows you open with: >
1450 :Winbar
1451
Bram Moolenaarc4b533e2018-04-06 22:26:25 +02001452If gdb stops at a source line and there is no window currently showing the
1453source code, a new window will be created for the source code. This also
1454happens if the buffer in the source code window has been modified and can't be
1455abandoned.
1456
Bram Moolenaarde1a8312018-06-19 16:59:54 +02001457Gdb gives each breakpoint a number. In Vim the number shows up in the sign
1458column, with a red background. You can use these gdb commands:
1459- info break list breakpoints
1460- delete N delete breakpoint N
1461You can also use the `:Clear` command if the cursor is in the line with the
1462breakpoint, or use the "Clear breakpoint" right-click menu entry.
1463
Bram Moolenaar45d5f262017-09-10 19:14:31 +02001464
1465Inspecting variables ~
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001466 *termdebug-variables* *:Evaluate*
Christian Brabandtc52a8562024-06-17 05:29:37 +02001467 `:Evaluate` evaluate the expression under the cursor
1468 `K` same (see |termdebug_map_K| to disable)
1469 `:Evaluate` {expr} evaluate {expr}
1470 `:'<,'>Evaluate` evaluate the Visually selected text
Bram Moolenaar45d5f262017-09-10 19:14:31 +02001471
1472This is similar to using "print" in the gdb window.
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001473You can usually shorten `:Evaluate` to `:Ev`.
Bram Moolenaar45d5f262017-09-10 19:14:31 +02001474
1475
Sean Dewar3d3a9152023-08-23 17:14:49 +01001476Navigating stack frames ~
1477 *termdebug-frames* *:Frame* *:Up* *:Down*
Christian Brabandtc52a8562024-06-17 05:29:37 +02001478 `:Frame` [frame] select frame [frame], which is a frame number,
Sean Dewar3d3a9152023-08-23 17:14:49 +01001479 address, or function name (default: current frame)
Christian Brabandtc52a8562024-06-17 05:29:37 +02001480 `:Up` [count] go up [count] frames (default: 1; the frame that
Sean Dewar3d3a9152023-08-23 17:14:49 +01001481 called the current)
Christian Brabandtc52a8562024-06-17 05:29:37 +02001482 `+` same (see |termdebug_map_plus| to disable)
1483 `:Down` [count] go down [count] frames (default: 1; the frame called
Sean Dewar3d3a9152023-08-23 17:14:49 +01001484 by the current)
Christian Brabandtc52a8562024-06-17 05:29:37 +02001485 `-` same (see |termdebug_map_minus| to disable)
Simon Sobisch2ae7ffe2023-08-22 22:19:14 +02001486
1487
Bram Moolenaar45d5f262017-09-10 19:14:31 +02001488Other commands ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +01001489 *termdebug-commands*
Bram Moolenaar32c67ba2018-04-16 16:21:49 +02001490 *:Gdb* jump to the gdb window
1491 *:Program* jump to the window with the running program
1492 *:Source* jump to the window with the source code, create it if there
Bram Moolenaarc4b533e2018-04-06 22:26:25 +02001493 isn't one
Bram Moolenaar82be4842021-01-11 19:40:15 +01001494 *:Asm* jump to the window with the disassembly, create it if there
1495 isn't one
laburnumT9f296212023-05-13 16:29:15 +02001496 *:Var* jump to the window with the local and argument variables,
zeertzjqd086b8f2024-02-25 15:42:52 +08001497 create it if there isn't one. This window updates whenever the
1498 program is stopped
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001499
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001500Events ~
1501 *termdebug-events*
1502Four autocommands can be used: >
1503 au User TermdebugStartPre echomsg 'debugging starting'
1504 au User TermdebugStartPost echomsg 'debugging started'
1505 au User TermdebugStopPre echomsg 'debugging stopping'
1506 au User TermdebugStopPost echomsg 'debugging stopped'
1507<
1508 *TermdebugStartPre*
1509TermdebugStartPre Before starting debugging.
1510 Not triggered if the debugger is already
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001511 running or the debugger command cannot be
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001512 executed.
1513 *TermdebugStartPost*
1514TermdebugStartPost After debugging has initialized.
1515 If a "!" bang is passed to `:Termdebug` or
1516 `:TermdebugCommand` the event is triggered
1517 before running the provided command in gdb.
1518 *TermdebugStopPre*
1519TermdebugStopPre Before debugging ends, when gdb is terminated,
1520 most likely after issuing a "quit" command in
1521 the gdb window.
1522 *TermdebugStopPost*
1523TermdebugStopPost After debugging has ended, gdb-related windows
1524 are closed, debug buffers wiped out and
1525 the state before the debugging was restored.
1526
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001527
Bram Moolenaard13166e2022-11-18 21:49:57 +00001528Customizing ~
1529 *termdebug-customizing* *g:termdebug_config*
1530In the past several global variables were used for configuration. These are
1531deprecated and using the g:termdebug_config dictionary is preferred. When
1532g:termdebug_config exists the other global variables will NOT be used.
1533The recommended way is to start with an empty dictionary: >
1534 let g:termdebug_config = {}
1535
1536Then you can add entries to the dictionary as mentioned below. The
1537deprecated global variable names are mentioned for completeness. If you are
1538switching over to using g:termdebug_config you can find the old variable name
1539and take over the value, then delete the deprecated variable.
1540
1541
Bram Moolenaarb3307b52018-06-17 21:34:11 +02001542Prompt mode ~
1543 *termdebug-prompt*
1544When the |+terminal| feature is not supported and on MS-Windows, gdb will run
1545in a buffer with 'buftype' set to "prompt". This works slightly differently:
1546- The gdb window will be in Insert mode while typing commands. Go to Normal
1547 mode with <Esc>, then you can move around in the buffer, copy/paste, etc.
1548 Go back to editing the gdb command with any command that starts Insert mode,
1549 such as `a` or `i`.
1550- The program being debugged will run in a separate window. On MS-Windows
1551 this is a new console window. On Unix, if the |+terminal| feature is
1552 available a Terminal window will be opened to run the debugged program in.
1553
1554 *termdebug_use_prompt*
1555Prompt mode can be used even when the |+terminal| feature is present with: >
Ubaldo Tiberia90b0b42024-07-20 12:00:44 +02001556 let g:termdebug_config['use_prompt'] = v:true
Bram Moolenaard13166e2022-11-18 21:49:57 +00001557If there is no g:termdebug_config you can use: >
Ubaldo Tiberia90b0b42024-07-20 12:00:44 +02001558 let g:termdebug_use_prompt = v:true
Ubaldo Tiberie54fd3f2024-07-04 17:14:03 +02001559
Bram Moolenaar388a5d42020-05-26 21:20:45 +02001560<
Ubaldo Tiberie54fd3f2024-07-04 17:14:03 +02001561However, the latter form will be deprecated in future releases.
1562
Peter Wolf8f1d0982024-10-27 21:51:14 +01001563
shane.xb.qian7fbbd7f2023-11-08 21:44:48 +01001564Mappings ~
Ubaldo Tiberia48637c2024-06-18 20:18:20 +02001565The termdebug plugin enables a few default mappings. All those mappings
1566are reset to their original values once the termdebug session concludes.
1567
shane.xb.qian7fbbd7f2023-11-08 21:44:48 +01001568 *termdebug_map_K* *termdebug-mappings*
zeertzjq20a94f42023-11-09 15:21:58 +08001569The K key is normally mapped to |:Evaluate| unless a buffer local (|:map-local|)
1570mapping to K already exists. If you do not want this use: >
Ubaldo Tiberia90b0b42024-07-20 12:00:44 +02001571 let g:termdebug_config['map_K'] = v:false
Bram Moolenaard13166e2022-11-18 21:49:57 +00001572If there is no g:termdebug_config you can use: >
Ubaldo Tiberia90b0b42024-07-20 12:00:44 +02001573 let g:termdebug_map_K = v:false
Bram Moolenaar82be4842021-01-11 19:40:15 +01001574<
Ubaldo Tiberie54fd3f2024-07-04 17:14:03 +02001575However, the latter form will be deprecated in future releases.
1576
Simon Sobisch2ae7ffe2023-08-22 22:19:14 +02001577 *termdebug_map_minus*
zeertzjq20a94f42023-11-09 15:21:58 +08001578The - key is normally mapped to |:Down| unless a buffer local mapping to the -
1579key already exists. If you do not want this use: >
Ubaldo Tiberia90b0b42024-07-20 12:00:44 +02001580 let g:termdebug_config['map_minus'] = v:false
Simon Sobisch2ae7ffe2023-08-22 22:19:14 +02001581<
1582 *termdebug_map_plus*
zeertzjq20a94f42023-11-09 15:21:58 +08001583The + key is normally mapped to |:Up| unless a buffer local mapping to the +
1584key already exists. If you do not want this use: >
Ubaldo Tiberia90b0b42024-07-20 12:00:44 +02001585 let g:termdebug_config['map_plus'] = v:false
Simon Sobisch2ae7ffe2023-08-22 22:19:14 +02001586<
Bram Moolenaar82be4842021-01-11 19:40:15 +01001587 *termdebug_disasm_window*
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001588If you want the Asm window shown by default, set the "disasm_window" flag to
15891. The "disasm_window_height" entry can be used to set the window height: >
Ubaldo Tiberia90b0b42024-07-20 12:00:44 +02001590 let g:termdebug_config['disasm_window'] = v:true
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001591 let g:termdebug_config['disasm_window_height'] = 15
Bram Moolenaard13166e2022-11-18 21:49:57 +00001592If there is no g:termdebug_config you can use: >
Bram Moolenaar82be4842021-01-11 19:40:15 +01001593 let g:termdebug_disasm_window = 15
Ubaldo Tiberie54fd3f2024-07-04 17:14:03 +02001594
1595However, the latter form will be deprecated in future releases.
1596
zeertzjq20a94f42023-11-09 15:21:58 +08001597Any value greater than 1 will set the Asm window height to that value.
shane.xb.qianca482022023-11-08 21:59:15 +01001598If the current window has enough horizontal space, it will be vertically split
1599and the Asm window will be shown side by side with the source code window (and
1600the height option won't be used).
Bram Moolenaarb3307b52018-06-17 21:34:11 +02001601
laburnumT9f296212023-05-13 16:29:15 +02001602 *termdebug_variables_window*
h_east59858792023-10-25 22:47:05 +09001603If you want the Var window shown by default, set the "variables_window" flag
1604to 1. The "variables_window_height" entry can be used to set the window
1605height: >
Ubaldo Tiberia90b0b42024-07-20 12:00:44 +02001606 let g:termdebug_config['variables_window'] = v:true
laburnumT9f296212023-05-13 16:29:15 +02001607 let g:termdebug_config['variables_window_height'] = 15
1608If there is no g:termdebug_config you can use: >
1609 let g:termdebug_variables_window = 15
Ubaldo Tiberie54fd3f2024-07-04 17:14:03 +02001610
1611However, the latter form will be deprecated in future releases.
1612
laburnumT9f296212023-05-13 16:29:15 +02001613Any value greater than 1 will set the Var window height to that value.
shane.xb.qianca482022023-11-08 21:59:15 +01001614If the current window has enough horizontal space, it will be vertically split
1615and the Var window will be shown side by side with the source code window (and
1616the height options won't be used).
laburnumT9f296212023-05-13 16:29:15 +02001617
Peter Wolf8f1d0982024-10-27 21:51:14 +01001618
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001619Communication ~
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +01001620 *termdebug-communication*
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001621There is another, hidden, buffer, which is used for Vim to communicate with
1622gdb. The buffer name is "gdb communication". Do not delete this buffer, it
1623will break the debugger.
1624
Bram Moolenaarde1a8312018-06-19 16:59:54 +02001625Gdb has some weird behavior, the plugin does its best to work around that.
1626For example, after typing "continue" in the gdb window a CTRL-C can be used to
1627interrupt the running program. But after using the MI command
1628"-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see
1629"continue" being used for the `:Continue` command, instead of using the
1630communication channel.
1631
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001632
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001633GDB command ~
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001634 *g:termdebugger*
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001635To change the name of the gdb command, set "debugger" entry in
1636g:termdebug_config or the "g:termdebugger" variable before invoking
1637`:Termdebug`: >
1638 let g:termdebug_config['command'] = "mygdb"
Bram Moolenaard13166e2022-11-18 21:49:57 +00001639If there is no g:termdebug_config you can use: >
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001640 let g:termdebugger = "mygdb"
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001641
Ubaldo Tiberie54fd3f2024-07-04 17:14:03 +02001642However, the latter form will be deprecated in future releases.
1643
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001644If the command needs an argument use a List: >
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001645 let g:termdebug_config['command'] = ['rr', 'replay', '--']
Bram Moolenaard13166e2022-11-18 21:49:57 +00001646If there is no g:termdebug_config you can use: >
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001647 let g:termdebugger = ['rr', 'replay', '--']
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001648
1649Several arguments will be added to make gdb work well for the debugger.
1650If you want to modify them, add a function to filter the argument list: >
1651 let g:termdebug_config['command_filter'] = MyDebugFilter
1652
1653If you do not want the arguments to be added, but you do need to set the
1654"pty", use a function to add the necessary arguments: >
1655 let g:termdebug_config['command_add_args'] = MyAddArguments
1656The function will be called with the list of arguments so far, and a second
1657argument that is the name of the pty.
1658 *gdb-version*
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001659Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI
Dominique Pellé960822a2023-09-24 23:07:39 +02001660interface. The "new-ui" command requires gdb version 7.12 or later. If you
Bram Moolenaar98ef2332018-03-18 14:44:37 +01001661get this error:
Bram Moolenaar01164a62017-11-02 22:58:42 +01001662 Undefined command: "new-ui". Try "help".~
1663Then your gdb is too old.
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001664
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001665
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01001666Colors ~
Bram Moolenaard13166e2022-11-18 21:49:57 +00001667 *hl-debugPC* *hl-debugBreakpoint*
Bram Moolenaare09ba7b2017-09-09 22:19:47 +02001668The color of the signs can be adjusted with these highlight groups:
1669- debugPC the current position
1670- debugBreakpoint a breakpoint
1671
1672The defaults are, when 'background' is "light":
1673 hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
1674 hi debugBreakpoint term=reverse ctermbg=red guibg=red
1675
1676When 'background' is "dark":
1677 hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
1678 hi debugBreakpoint term=reverse ctermbg=red guibg=red
Bram Moolenaarc572da52017-08-27 16:52:01 +02001679
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001680
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01001681Shortcuts ~
1682 *termdebug_shortcuts*
Bram Moolenaarb3307b52018-06-17 21:34:11 +02001683You can define your own shortcuts (mappings) to control gdb, that can work in
1684any window, using the TermDebugSendCommand() function. Example: >
1685 map ,w :call TermDebugSendCommand('where')<CR>
1686The argument is the gdb command.
1687
1688
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01001689Popup menu ~
1690 *termdebug_popup*
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001691By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds
1692these entries to the popup menu:
1693 Set breakpoint `:Break`
1694 Clear breakpoint `:Clear`
1695 Evaluate `:Evaluate`
1696If you don't want this then disable it with: >
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001697 let g:termdebug_config['popup'] = 0
Bram Moolenaard13166e2022-11-18 21:49:57 +00001698If there is no g:termdebug_config you can use: >
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001699 let g:termdebug_popup = 0
1700
Ubaldo Tiberie54fd3f2024-07-04 17:14:03 +02001701However, the latter form will be deprecated in future releases.
Bram Moolenaar71137fe2018-03-03 20:47:21 +01001702
Peter Wolf8f1d0982024-10-27 21:51:14 +01001703
skywind3000e7d9ca22023-06-28 23:27:28 +01001704Change default signs ~
1705 *termdebug_signs*
Shane-XB-Qian2dd613f2023-11-12 23:53:39 +08001706Termdebug uses the hex number of the breakpoint ID in the signcolumn to
Peter Wolf8f1d0982024-10-27 21:51:14 +01001707represent breakpoints. If it is greater than "0xFF", then it will be displayed
Shane-XB-Qian2dd613f2023-11-12 23:53:39 +08001708as "F+", due to we really only have two screen cells for the sign.
Ella Moss5e7f43b2024-11-09 11:32:15 +01001709You may also use decimal breakpoint signs instead, in which case IDs greater
1710than 99 will be displayed as "9+".
skywind3000e7d9ca22023-06-28 23:27:28 +01001711
Ella Moss5e7f43b2024-11-09 11:32:15 +01001712If you want to customize the breakpoint signs to show `>>` in the signcolumn: >
skywind3000e7d9ca22023-06-28 23:27:28 +01001713 let g:termdebug_config['sign'] = '>>'
Dimitry Ishenkoc4bca1d2025-07-08 23:13:14 +02001714You can also specify individual signs for the first several breakpoints: >
1715 let g:termdebug_config['signs'] = ['>1', '>2', '>3', '>4', '>5', '>6', '>7', '>8', '>9']
1716 let g:termdebug_config['sign'] = '>>'
Ella Moss5e7f43b2024-11-09 11:32:15 +01001717If you would like to use decimal (base 10) breakpoint signs: >
1718 let g:termdebug_config['sign_decimal'] = 1
zeertzjq060107c2024-11-10 14:08:56 +01001719If the variable g:termdebug_config does not yet exist, you can use: >
skywind3000e7d9ca22023-06-28 23:27:28 +01001720 let g:termdebug_config = {'sign': '>>'}
Ella Moss5e7f43b2024-11-09 11:32:15 +01001721Likewise, to enable decimal signs: >
1722 let g:termdebug_config = {'sign_decimal': 1}
skywind3000e7d9ca22023-06-28 23:27:28 +01001723
1724
Bram Moolenaard13166e2022-11-18 21:49:57 +00001725Window toolbar ~
1726 *termdebug_winbar*
1727By default the Termdebug plugin creates a window toolbar if the mouse is
1728enabled (see |:Winbar|). If you don't want this then disable it with: >
1729 let g:termdebug_config['winbar'] = 0
1730
1731
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01001732Vim window width ~
1733 *termdebug_wide*
Bram Moolenaar4466ad62020-11-21 13:16:30 +01001734To change the width of the Vim window when debugging starts and use a vertical
1735split: >
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001736 let g:termdebug_config['wide'] = 163
Bram Moolenaard13166e2022-11-18 21:49:57 +00001737If there is no g:termdebug_config you can use: >
Bram Moolenaar4466ad62020-11-21 13:16:30 +01001738 let g:termdebug_wide = 163
Bram Moolenaar38baa3e2017-09-14 16:10:38 +02001739
Ubaldo Tiberie54fd3f2024-07-04 17:14:03 +02001740However, the latter form will be deprecated in future releases.
1741
Bram Moolenaar4466ad62020-11-21 13:16:30 +01001742This will set 'columns' to 163 when `:Termdebug` is used. The value is
1743restored when quitting the debugger.
1744
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001745If the wide value is set and 'columns' is already a greater value, then a
Bram Moolenaar4466ad62020-11-21 13:16:30 +01001746vertical split will be used without modifying 'columns'.
1747
Bram Moolenaarc9a431c2022-05-23 21:49:41 +01001748Set the wide value to 1 to use a vertical split without ever changing
Bram Moolenaar4466ad62020-11-21 13:16:30 +01001749'columns'. This is useful when the terminal can't be resized by Vim.
Bram Moolenaare4f25e42017-07-07 11:54:15 +02001750
Bram Moolenaare4f25e42017-07-07 11:54:15 +02001751
Peter Wolf8f1d0982024-10-27 21:51:14 +01001752Evaluate in Popup Window at Cursor ~
1753 *termdebug_evaluate_in_popup*
1754By default |:Evaluate| will simply echo its output. For larger entities this
1755might become difficult to read or even truncated.
1756Alternatively, the evaluation result may be output into a popup window at the
1757current cursor position: >
1758 let g:termdebug_config['evaluate_in_popup'] = v:true
1759This can also be used in a "one-shot" manner: >
1760 func OnCursorHold()
1761 let g:termdebug_config['evaluate_in_popup'] = v:true
1762 :Evaluate
1763 let g:termdebug_config['evaluate_in_popup'] = v:false
1764 endfunc
1765<
Ubaldo Tiberiae1c8b72024-11-19 22:32:30 +01001766
1767Contributing ~
1768 *termdebug_contributing*
1769Contributions for termdebug improvements are welcome.
1770However, it is fairly common that during the development process you need some
1771mechanisms like `echo` statements (or similar) to help you in your job.
1772For this reason, you can set: >
1773 let g:termdebug_config['debug'] = true
1774<
h-eastb534e802024-12-03 20:37:52 +01001775This sets the `DEBUG` variable to `true`, which can be referenced in the
1776source code. An example of its usage follows: >
Ubaldo Tiberiae1c8b72024-11-19 22:32:30 +01001777 if exists('g:termdebug_loaded')
1778 if DEBUG
1779 Echoerr('Termdebug already loaded.')
1780 endif
1781 finish
1782 endif
1783<
1784
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001785 vim:tw=78:ts=8:noet:ft=help:norl: