terminal.txt (75292B)
1 *terminal.txt* For Vim version 9.2. Last change: 2026 Aug 30 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Terminal window support *terminal* *terminal-window* 8 9 10 The terminal feature is optional, use this to check if your Vim has it: > 11 echo has('terminal') 12 If the result is "1" you have it. 13 14 15 1. 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| 26 2. Terminal functions |terminal-function-details| 27 3. 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| 31 4. Remote testing |terminal-testing| 32 5. Diffing screen dumps |terminal-diff| 33 Writing a screen dump test for Vim |terminal-dumptest| 34 Creating a screen dump |terminal-screendump| 35 Comparing screen dumps |terminal-diffscreendump| 36 6. Debugging |terminal-debug| 37 Starting |termdebug-starting| 38 Example session |termdebug-example| 39 Stepping through code |termdebug-stepping| 40 Inspecting variables |termdebug-variables| 41 Navigating stack frames |termdebug-frames| 42 Other commands |termdebug-commands| 43 Events |termdebug-events| 44 Prompt mode |termdebug-prompt| 45 Mappings |termdebug-mappings| 46 Communication |termdebug-communication| 47 Remote Debugging |termdebug-remote| 48 Customizing |termdebug-customizing| 49 50 {only available when compiled with the |+terminal| feature} 51 The terminal feature requires the |+job| and |+channel| features. 52 53 ============================================================================== 54 1. Basic use *terminal-use* 55 56 This feature is for running a terminal emulator in a Vim window. A job can be 57 started connected to the terminal emulator. For example, to run a shell: > 58 :term bash 59 60 Or to run build command: > 61 :term make myprogram 62 63 The job runs asynchronously from Vim, the window will be updated to show 64 output from the job, also while editing in another window. 65 66 67 Typing ~ 68 *terminal-typing* 69 When the keyboard focus is in the terminal window, typed keys will be sent to 70 the job. This uses a pty when possible. You can click outside of the 71 terminal window to move keyboard focus elsewhere. 72 73 *t_CTRL-W_CTRL-W* *t_CTRL-W_:* 74 CTRL-W can be used to navigate between windows and other CTRL-W commands, 75 e.g.: 76 CTRL-W CTRL-W move focus to the next window 77 CTRL-W : enter an Ex command 78 See |CTRL-W| for more commands. 79 80 Special in the terminal window: *t_CTRL-W_.* *t_CTRL-W_N* 81 CTRL-W . send a CTRL-W to the job in the terminal 82 CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal 83 CTRL-W N go to Terminal-Normal mode, see |Terminal-mode| 84 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| 85 CTRL-W " {reg} paste register {reg} *t_CTRL-W_quote* 86 Also works with the = register to insert the result of 87 evaluating an expression. 88 CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C| 89 CTRL-W gt go to next tabpage, same as `gt` *t_CTRL-W_gt* 90 CTRL-W gT go to previous tabpage, same as `gT` *t_CTRL-W_gT* 91 92 See option 'termwinkey' for specifying another key instead of CTRL-W that 93 will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey' 94 to the job. For example: 95 'termwinkey' CTRL-W move focus to the next window 96 'termwinkey' : enter an Ex command 97 'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal 98 'termwinkey' . send 'termwinkey' to the job in the terminal 99 'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal 100 'termwinkey' N go to terminal Normal mode, see below 101 'termwinkey' CTRL-N same as CTRL-W N |t_CTRL-W_N| 102 'termwinkey' CTRL-C same as CTRL-W CTRL-C |t_CTRL-W_CTRL-C| 103 *t_CTRL-\_CTRL-N* 104 The special key combination CTRL-\ CTRL-N can be used to switch to Normal 105 mode, just like this works in any other mode. 106 *t_CTRL-W_CTRL-C* 107 CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a 108 CTRL-Break will also kill the job. 109 110 If you type CTRL-C the effect depends on what the pty has been configured to 111 do. For simple commands this causes a SIGINT to be sent to the job, which 112 would end it. Other commands may ignore the SIGINT or handle the CTRL-C 113 themselves (like Vim does). 114 115 To change the keys you type use terminal mode mappings, see |:tmap|. 116 These are defined like any mapping, but apply only when typing keys that are 117 sent to the job running in the terminal. For example, to make F1 switch 118 to Terminal-Normal mode: > 119 tnoremap <F1> <C-W>N 120 You can use Esc, but you need to make sure it won't cause other keys to 121 break (cursor keys start with an Esc, so they may break), this probably only 122 works in the GUI: > 123 tnoremap <Esc> <C-W>N 124 set notimeout ttimeout timeoutlen=100 125 126 You can also create menus similar to terminal mode mappings, but you have to 127 use |:tlmenu| instead of |:tmenu|. 128 129 *options-in-terminal* 130 After opening the terminal window and setting 'buftype' to "terminal" the 131 |TerminalWinOpen| autocommand event is triggered. This makes it possible to set 132 options specifically for the terminal window and buffer. Example: > 133 au TerminalWinOpen * setlocal bufhidden=hide 134 This only works properly if the terminal is not hidden. 135 136 For both hidden and non-hidden terminals this works, both for buffer-local and 137 window-local options: > 138 au TerminalWinOpen,BufWinEnter * if &buftype == 'terminal' 139 \ | setlocal bufhidden=hide colorcolumn=123 140 \ | endif 141 Note that for a hidden terminal the options are not set until the terminal is 142 no longer hidden. 143 144 There is also the |TerminalOpen| event. Keep in mind this may be triggered 145 for a hidden terminal, then the current window and buffer are not that of the 146 new terminal. 147 You need to use <abuf>, which is set to the terminal buffer. Example: > 148 au TerminalOpen * call setbufvar(expand('<abuf>')->str2nr(), 149 \ '&termwinscroll', 1000) 150 For a window-local option, you need to delay setting the option until the 151 terminal window has been created (this only works for a hidden terminal): > 152 au TerminalOpen * exe printf( 153 \ 'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d', 154 \ expand('<abuf>')->str2nr(), 123) 155 For a non-hidden terminal use |TerminalWinOpen|. 156 157 Mouse events (click and drag) are passed to the terminal. Mouse move events 158 are only passed when Vim itself is receiving them. For a terminal that is 159 when 'balloonevalterm' is enabled. 160 161 162 Size and color ~ 163 *terminal-size-color* 164 See option 'termwinsize' for controlling the size of the terminal window. 165 (TODO: scrolling when the terminal is larger than the window) 166 167 The job running in the terminal can change the colors. The default foreground 168 and background colors are taken from Vim, the Normal highlight group. 169 170 For a color terminal the 'background' option is used to decide whether the 171 terminal window will start with a white or black background. 172 173 To use a different color the Terminal highlight group can be used, for 174 example: > 175 hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue 176 Instead of Terminal another group can be specified with the "term_highlight" 177 option for `term_start()`. 178 179 *g:terminal_ansi_colors* 180 In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new 181 terminal windows may be configured using the variable 182 `g:terminal_ansi_colors`, which should be a list of 16 color names or 183 hexadecimal color codes, similar to those accepted by |highlight-guifg|. When 184 not using GUI colors, the terminal window always uses the 16 ANSI colors of 185 the underlying terminal. 186 When using `term_start()` the colors can be set with the "ansi_colors" option. 187 The |term_setansicolors()| function can be used to change the colors, and 188 |term_getansicolors()| to get the currently used colors. 189 190 191 Command syntax ~ 192 193 :[range]ter[minal] [options] [command] *:ter* *:terminal* 194 Open a new terminal window. 195 196 If [command] is provided run it as a job and connect 197 the input and output to the terminal. 198 If [command] is not given the 'shell' option is used. 199 if [command] is NONE no job is started, the pty of the 200 terminal can be used by a command like gdb. 201 202 If [command] outputs NUL bytes, those will be 203 converted to new lines |NL-used-for-Nul|. 204 205 *terminal-nospecial* 206 Vim itself only recognizes |cmdline-special| 207 characters inside [command]. Everything else will be 208 passed untouched. When needed to expand wildcards, 209 environment variables or other shell specials consider 210 |term++shell| option. 211 212 If [command] is missing the default behavior is to 213 close the terminal when the shell exits. This can be 214 changed with the ++noclose argument. 215 If [command] is present the default behavior is to 216 keep the terminal open in Terminal-Normal mode. This 217 can be changed with the ++close argument. 218 219 No Vim command can follow, any | is included in 220 [command]. Use `:execute` if you must have a Vim 221 command following in the same line. 222 223 *terminal-bufname* 224 A new buffer will be created, using [command] or 225 'shell' as the name, prefixed with a "!". If a buffer 226 by this name already exists a number is added in 227 parentheses. E.g. if "gdb" exists the second terminal 228 buffer will use "!gdb (1)". 229 230 If [range] is given the specified lines are used as 231 input for the job. It will not be possible to type 232 keys in the terminal window. For MS-Windows see the 233 ++eof argument below. 234 235 *term++close* *term++noclose* *term++open* 236 Supported [options] are: 237 ++close The terminal window will close 238 automatically when the job terminates. 239 |terminal-close| 240 ++noclose The terminal window will NOT close 241 automatically when the job terminates. 242 ++open When the job terminates and no window 243 shows it, a window will be opened. 244 Note that this can be interruptive. 245 The last of ++close, ++noclose and ++open 246 matters and rules out earlier arguments. 247 248 ++curwin Open the terminal in the current 249 window, do not split the current 250 window. Fails if the current buffer 251 cannot be |abandon|ed. 252 ++hidden Open the terminal in a hidden buffer, 253 no window will be used. 254 ++norestore Do not include this terminal window 255 in a session file. 256 257 *term++shell* 258 ++shell Instead of executing {command} 259 directly, use a shell, like with 260 `:!command` *E279* 261 {only works on Unix and MS-Windows} 262 The resulting command will look like 263 'shell' 'shellcmdflag' [command] 264 Other options related to `:!command` 265 have no effect. 266 ++kill={how} When trying to close the terminal 267 window kill the job with {how}. See 268 |term_setkill()| for the values. 269 ++rows={height} Use {height} for the terminal window 270 height. If the terminal uses the full 271 Vim height (no window above or below 272 the terminal window) the command line 273 height will be reduced as needed. 274 ++cols={width} Use {width} for the terminal window 275 width. If the terminal uses the full 276 Vim width (no window left or right of 277 the terminal window) this value is 278 ignored. 279 ++eof={text} When using [range]: text to send after 280 the last line was written. Cannot 281 contain white space. A CR is 282 appended. For MS-Windows the default 283 is to send CTRL-D. 284 E.g. for a shell use "++eof=exit" and 285 for Python "++eof=exit()". Special 286 codes can be used like with `:map`, 287 e.g. "<C-Z>" for CTRL-Z. 288 ++type={pty} (MS-Windows only): Use {pty} as the 289 virtual console. See 'termwintype' 290 for the values. 291 ++api={expr} Permit the function name starting with 292 {expr} to be called as |terminal-api| 293 function. If {expr} is empty then no 294 function can be called. 295 296 If you want to use more options use the |term_start()| 297 function. 298 If you want to split the window vertically, use: > 299 :vertical terminal 300 < Or short: > 301 :vert ter 302 303 When the buffer associated with the terminal is forcibly unloaded or wiped out 304 the job is killed, similar to calling `job_stop(job, "kill")` . 305 Closing the window normally results in |E947|. When a kill method was set 306 with "++kill={how}" or |term_setkill()| then closing the window will use that 307 way to kill or interrupt the job. For example: > 308 :term ++kill=term tail -f /tmp/log 309 310 So long as the job is running the window behaves like it contains a modified 311 buffer. Trying to close the window with `CTRL-W :quit` fails. When using 312 `CTRL-W :quit!` the job is ended. The text in the window is lost, the buffer 313 is deleted. With `CTRL-W :bunload!` the buffer remains but will be empty. 314 315 Trying to close the window with `CTRL-W :close` also fails. Using 316 `CTRL-W :close!` will close the window and make the buffer hidden. 317 318 You can use `CTRL-W :hide` to close the terminal window and make the buffer 319 hidden, the job keeps running. The `:buffer` command can be used to turn the 320 current window into a terminal window. If there are unsaved changes this 321 fails, use ! to force, as usual. 322 323 *terminal-close* 324 When the terminal job finishes and no [command] was given (e.g. the 'shell' 325 command was executed), the terminal window will be closed by default (unless 326 the buffer in next window receiving the space has the 'nobuflisted' option 327 set, in which case the terminal window would not be closed automatically, but 328 a new empty buffer would be opened in that window). 329 330 When the terminal window is closed, e.g. when the shell exits and "++close" 331 argument was used, and this is the last normal Vim window, then Vim will exit. 332 This is like using |:quit| in a normal window. Help and preview windows are 333 not counted. 334 335 To have a background job run without a window, and open the window when it's 336 done, use options like this: > 337 :term ++hidden ++open make 338 Note that the window will open at an unexpected moment, this will interrupt 339 what you are doing. 340 341 *E947* *E948* 342 So long as the job is running, the buffer is considered modified and Vim 343 cannot be quit easily, see |abandon|. 344 345 When the job has finished and no changes were made to the buffer: closing the 346 window will wipe out the buffer. 347 348 Before changes can be made to a terminal buffer, the 'modifiable' option must 349 be set. This is only possible when the job has finished. At the first change 350 the buffer will become a normal buffer and the highlighting is removed. 351 You may want to change the buffer name with |:file| to be able to write, since 352 the buffer name will still be set to the command. 353 354 355 Resizing ~ 356 *terminal-resizing* 357 The size of the terminal can be in one of three modes: 358 359 1. The 'termwinsize' option is empty: The terminal size follows the window 360 size. The minimal size is 2 screen lines with 10 cells. 361 362 2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number 363 of screen rows and "cols" is the minimal number of cells. 364 365 3. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower 366 case). The terminal size is fixed to the specified number of screen lines 367 and cells. If the window is bigger there will be unused empty space. 368 369 If the window is smaller than the terminal size, only part of the terminal can 370 be seen (the lower-left part). 371 372 The |term_getsize()| function can be used to get the current size of the 373 terminal. |term_setsize()| can be used only when in the first or second mode, 374 not when 'termwinsize' is "rowsXcols". 375 376 377 Terminal-Job and Terminal-Normal mode ~ 378 *Terminal-mode* *Terminal-Job* 379 When the job is running the contents of the terminal is under control of the 380 job. That includes the cursor position. Typed keys are sent to the job. 381 The terminal contents can change at any time. This is called Terminal-Job 382 mode. 383 384 In Terminal-Job mode the cursor position you see belongs to the terminal job, 385 not to Vim. The window's cursor position is only updated when Vim takes over 386 in |Terminal-Normal| mode, so the 'ruler' and the 'statusline' show a stale 387 cursor position. 388 389 Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the 390 contents of the terminal window is under control of Vim, the job output is 391 suspended. CTRL-\ CTRL-N does the same. 392 393 Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by 394 |term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are. 395 396 It is not possible to enter Insert mode from Terminal-Job mode. 397 398 *Terminal-Normal* *E946* 399 In Terminal-Normal mode you can move the cursor around with the usual Vim 400 commands, Visually mark text, yank text, etc. But you cannot change the 401 contents of the buffer. The commands that would start insert mode, such as 402 'i' and 'a', return to Terminal-Job mode. The window will be updated to show 403 the contents of the terminal. |:startinsert| is ineffective. 404 405 In Terminal-Normal mode the statusline and window title show "(Terminal)". If 406 the job ends while in Terminal-Normal mode this changes to 407 "(Terminal-finished)". 408 409 When the job outputs lines in the terminal, such that the contents scrolls off 410 the top, those lines are remembered and can be seen in Terminal-Normal mode. 411 The number of lines is limited by the 'termwinscroll' option. When going over 412 this limit, the first 10% of the scrolled lines are deleted and are lost. 413 414 415 Cursor style ~ 416 *terminal-cursor-style* 417 By default the cursor in the terminal window uses a not blinking block. The 418 normal xterm escape sequences can be used to change the blinking state and the 419 shape. Once focus leaves the terminal window Vim will restore the original 420 cursor. 421 422 An exception is when xterm is started with the "-bc" argument, or another way 423 that causes the cursor to blink. This actually means that the blinking flag 424 is inverted. Since Vim cannot detect this, the terminal window cursor 425 blinking will also be inverted. 426 427 428 Session ~ 429 *terminal-session* 430 A terminal window will be restored when using a session file, if possible and 431 wanted. 432 433 If "terminal" was removed from 'sessionoptions' then no terminal windows will 434 be restored. 435 436 If the job in the terminal was finished the window will not be restored. 437 438 If the terminal can be restored, the command that was used to open it will be 439 used again. To change this use the |term_setrestore()| function. This can 440 also be used to not restore a specific terminal by setting the command to 441 "NONE". 442 443 444 Special keys ~ 445 *terminal-special-keys* 446 Since the terminal emulator simulates an xterm, only escape sequences that 447 both Vim and xterm recognize will be available in the terminal window. If you 448 want to pass on other escape sequences to the job running in the terminal you 449 need to set up forwarding. Example: > 450 tmap <expr> <Esc>]b SendToTerm("\<Esc>]b") 451 func SendToTerm(what) 452 call term_sendkeys('', a:what) 453 return '' 454 endfunc 455 456 457 Unix ~ 458 *terminal-unix* 459 On Unix a pty is used to make it possible to run all kinds of commands. You 460 can even run Vim in the terminal! That's used for debugging, see below. 461 462 Environment variables are used to pass information to the running job: 463 TERM the name of the terminal, from the 'term' option or 464 $TERM in the GUI; falls back to "xterm" if it does not 465 start with "xterm" 466 ROWS number of rows in the terminal initially 467 LINES same as ROWS 468 COLUMNS number of columns in the terminal initially 469 COLORS number of colors, 't_Co' (256*256*256 in the GUI) 470 VIM_SERVERNAME v:servername 471 VIM_TERMINAL v:version 472 473 474 MS-Windows ~ 475 *terminal-ms-windows* 476 On MS-Windows winpty is used to make it possible to run all kind of commands. 477 Obviously, they must be commands that run in a terminal, not open their own 478 window. 479 480 You need the following two files from winpty: 481 482 winpty.dll 483 winpty-agent.exe 484 485 You can download them from the following page: 486 487 https://github.com/rprichard/winpty 488 489 Just put the files somewhere in your PATH. You can set the 'winptydll' option 490 to point to the right file, if needed. If you have both the 32-bit and 64-bit 491 version, rename to winpty32.dll and winpty64.dll to match the way Vim was 492 build. 493 *ConPTY* *E982* 494 On more recent versions of MS-Windows 10 (beginning with the "October 2018 495 Update"), winpty is no longer required. On those versions, |:terminal| will use 496 Windows' built-in support for hosting terminal applications, "ConPTY". When 497 ConPTY is in use, there may be rendering artifacts regarding ambiguous-width 498 characters. If you encounter any such issues, install "winpty". ConPTY 499 support is considered stable with the first release of Windows 11. 500 501 Environment variables are used to pass information to the running job: 502 VIM_SERVERNAME v:servername 503 504 *git-vimdumps* 505 There exists a git-difftool extension called `git-vimdumps` that can be used 506 to conveniently inspect screendump files and diff them. Please see in the Vim 507 Repository the file `src/testdir/commondumps.vim` on how to create and use 508 this git extension. 509 510 ============================================================================== 511 2. Terminal functions *terminal-function-details* 512 513 *term_dumpdiff()* 514 term_dumpdiff({filename}, {filename} [, {options}]) 515 Open a new window displaying the difference between the two 516 files. The files must have been created with 517 |term_dumpwrite()|. 518 Returns the buffer number or zero when the diff fails. 519 Also see |terminal-diff|. 520 NOTE: this does not work with double-width characters yet. 521 522 The top part of the buffer contains the contents of the first 523 file, the bottom part of the buffer contains the contents of 524 the second file. The middle part shows the differences. 525 The parts are separated by a line of equals. 526 527 If the {options} argument is present, it must be a Dict with 528 these possible members: 529 "term_name" name to use for the buffer name, instead 530 of the first file name. 531 "term_rows" vertical size to use for the terminal, 532 instead of using 'termwinsize', but 533 respecting the minimal size; valid range 534 is from 0 to 1000 535 "term_cols" horizontal size to use for the terminal, 536 instead of using 'termwinsize', but 537 respecting the minimal size; valid range 538 is from 0 to 1000 539 "vertical" split the window vertically 540 "curwin" use the current window, do not split the 541 window; fails if the current buffer 542 cannot be |abandon|ed 543 "bufnr" do not create a new buffer, use the 544 existing buffer "bufnr". This buffer 545 must have been previously created with 546 term_dumpdiff() or term_dumpload() and 547 visible in a window. 548 "norestore" do not add the terminal window to a 549 session file 550 551 Each character in the middle part indicates a difference. If 552 there are multiple differences only the first in this list is 553 used: 554 X different character 555 w different width 556 f different foreground color 557 b different background color 558 a different attribute 559 + missing position in first file 560 - missing position in second file 561 > cursor position in first file, not in second 562 < cursor position in second file, not in first 563 564 Using the "s" key the top and bottom parts are swapped. This 565 makes it easy to spot a difference. 566 567 Can also be used as a |method|: > 568 GetFilename()->term_dumpdiff(otherfile) 569 < 570 Return type: |Number| 571 572 573 term_dumpload({filename} [, {options}]) *term_dumpload()* 574 Open a new window displaying the contents of {filename} 575 The file must have been created with |term_dumpwrite()|. 576 Returns the buffer number or zero when it fails. 577 Also see |terminal-diff|. 578 579 For {options} see |term_dumpdiff()|. 580 581 Can also be used as a |method|: > 582 GetFilename()->term_dumpload() 583 < 584 Return type: |Number| 585 586 587 term_dumpwrite({buf}, {filename} [, {options}]) *term_dumpwrite()* 588 Dump the contents of the terminal screen of {buf} in the file 589 {filename}. This uses a format that can be used with 590 |term_dumpload()| and |term_dumpdiff()|. 591 If the job in the terminal already finished an error is given: 592 *E958* 593 If {filename} already exists an error is given: *E953* 594 Also see |terminal-diff|. 595 596 {options} is a dictionary with these optional entries: 597 "rows" maximum number of rows to dump 598 "columns" maximum number of columns to dump 599 600 Can also be used as a |method|, the base is used for the file 601 name: > 602 GetFilename()->term_dumpwrite(bufnr) 603 < 604 Return type: void 605 606 607 term_getaltscreen({buf}) *term_getaltscreen()* 608 Returns 1 if the terminal of {buf} is using the alternate 609 screen. 610 {buf} is used as with |term_getsize()|. 611 612 Can also be used as a |method|: > 613 GetBufnr()->term_getaltscreen() 614 < 615 Return type: |Number| 616 617 618 term_getansicolors({buf}) *term_getansicolors()* 619 Get the ANSI color palette in use by terminal {buf}. 620 Returns a List of length 16 where each element is a String 621 representing a color in hexadecimal "#rrggbb" format. 622 Also see |term_setansicolors()| and |g:terminal_ansi_colors|. 623 If neither was used returns the default colors. 624 625 {buf} is used as with |term_getsize()|. If the buffer does not 626 exist or is not a terminal window, an empty list is returned. 627 628 Can also be used as a |method|: > 629 GetBufnr()->term_getansicolors() 630 < 631 Return type: list<string> or list<any> 632 633 {only available when compiled with GUI enabled and/or the 634 |+termguicolors| feature} 635 636 term_getattr({attr}, {what}) *term_getattr()* 637 Given {attr}, a value returned by term_scrape() in the "attr" 638 item, return whether {what} is on. {what} can be one of: 639 bold 640 italic 641 underline 642 strike 643 reverse 644 645 Can also be used as a |method|: > 646 GetAttr()->term_getattr() 647 < 648 Return type: |Number| 649 650 651 term_getcursor({buf}) *term_getcursor()* 652 Get the cursor position of terminal {buf}. Returns a list 653 with two numbers and a dictionary: [row, col, dict]. 654 655 "row" and "col" are one based, the first screen cell is row 656 1, column 1. This is the cursor position of the terminal 657 itself, not of the Vim window. 658 659 "dict" can have these members: 660 "visible" one when the cursor is visible, zero when it 661 is hidden. 662 "blink" one when the cursor is blinking, zero when it 663 is not blinking. 664 "shape" 1 for a block cursor, 2 for underline and 3 665 for a vertical bar. 666 "color" color of the cursor, e.g. "green" 667 668 {buf} must be the buffer number of a terminal window. If the 669 buffer does not exist or is not a terminal window, an empty 670 list is returned. 671 672 Can also be used as a |method|: > 673 GetBufnr()->term_getcursor() 674 < 675 Return type: list<any> 676 677 678 term_getjob({buf}) *term_getjob()* 679 Get the Job associated with terminal window {buf}. 680 {buf} is used as with |term_getsize()|. 681 Returns |v:null| when there is no job. In Vim9 script, return 682 |null_job| when there is no job. 683 684 Can also be used as a |method|: > 685 GetBufnr()->term_getjob() 686 < 687 Return type: |job| 688 689 690 term_getline({buf}, {row}) *term_getline()* 691 Get a line of text from the terminal window of {buf}. 692 {buf} is used as with |term_getsize()|. 693 694 The first line has {row} one. When {row} is "." the cursor 695 line is used. When {row} is invalid an empty string is 696 returned. 697 698 To get attributes of each character use |term_scrape()|. 699 700 Can also be used as a |method|: > 701 GetBufnr()->term_getline(row) 702 < 703 Return type: |String| 704 705 706 term_getscrolled({buf}) *term_getscrolled()* 707 Return the number of lines that scrolled to above the top of 708 terminal {buf}. This is the offset between the row number 709 used for |term_getline()| and |getline()|, so that: > 710 term_getline(buf, N) 711 < is equal to: > 712 getline(N + term_getscrolled(buf)) 713 < (if that line exists). 714 715 {buf} is used as with |term_getsize()|. 716 717 Can also be used as a |method|: > 718 GetBufnr()->term_getscrolled() 719 < 720 Return type: |Number| 721 722 723 term_getsize({buf}) *term_getsize()* 724 Get the size of terminal {buf}. Returns a list with two 725 numbers: [rows, cols]. This is the size of the terminal, not 726 the window containing the terminal. 727 728 {buf} must be the buffer number of a terminal window. Use an 729 empty string for the current buffer. If the buffer does not 730 exist or is not a terminal window, an empty list is returned. 731 732 Can also be used as a |method|: > 733 GetBufnr()->term_getsize() 734 < 735 Return type: list<number> or list<any> 736 737 738 term_getstatus({buf}) *term_getstatus()* 739 Get the status of terminal {buf}. This returns a String with 740 a comma-separated list of these items: 741 running job is running 742 finished job has finished 743 normal in Terminal-Normal mode 744 One of "running" or "finished" is always present. 745 746 {buf} must be the buffer number of a terminal window. If the 747 buffer does not exist or is not a terminal window, an empty 748 string is returned. 749 750 Can also be used as a |method|: > 751 GetBufnr()->term_getstatus() 752 < 753 Return type: |String| 754 755 756 term_gettitle({buf}) *term_gettitle()* 757 Get the title of terminal {buf}. This is the title that the 758 job in the terminal has set. 759 760 {buf} must be the buffer number of a terminal window. If the 761 buffer does not exist or is not a terminal window, an empty 762 string is returned. 763 764 Can also be used as a |method|: > 765 GetBufnr()->term_gettitle() 766 < 767 Return type: |String| 768 769 770 term_gettty({buf} [, {input}]) *term_gettty()* 771 Get the name of the controlling terminal associated with 772 terminal window {buf}. {buf} is used as with |term_getsize()|. 773 774 When {input} is omitted or 0, return the name for writing 775 (stdout). When {input} is 1 return the name for reading 776 (stdin). On UNIX, both return same name. 777 778 Can also be used as a |method|: > 779 GetBufnr()->term_gettty() 780 < 781 Return type: |String| 782 783 784 term_list() *term_list()* 785 Return a list with the buffer numbers of all buffers for 786 terminal windows. 787 788 Return type: list<number> or list<any> 789 790 791 term_scrape({buf}, {row}) *term_scrape()* 792 Get the contents of {row} of terminal screen of {buf}. 793 For {buf} see |term_getsize()|. 794 795 The first line has {row} one. When {row} is "." the cursor 796 line is used. When {row} is invalid an empty string is 797 returned. 798 799 Return a List containing a Dict for each screen cell: 800 "chars" character(s) at the cell 801 "fg" foreground color as #rrggbb 802 "bg" background color as #rrggbb 803 "attr" attributes of the cell, use |term_getattr()| 804 to get the individual flags 805 "width" cell width: 1 or 2 806 For a double-width cell there is one item, thus the list can 807 be shorter than the width of the terminal. 808 809 Can also be used as a |method|: > 810 GetBufnr()->term_scrape(row) 811 < 812 Return type: list<dict<any>> or list<any> 813 814 815 term_sendkeys({buf}, {keys}) *term_sendkeys()* 816 Send keystrokes {keys} to terminal {buf}. 817 {buf} is used as with |term_getsize()|. 818 819 {keys} are translated as key sequences. For example, "\<c-x>" 820 means the character CTRL-X. 821 822 Can also be used as a |method|: > 823 GetBufnr()->term_sendkeys(keys) 824 < 825 Return type: void 826 827 828 term_setansicolors({buf}, {colors}) *term_setansicolors()* 829 Set the ANSI color palette used by terminal {buf}. 830 {colors} must be a List of 16 valid color names or hexadecimal 831 color codes, like those accepted by |highlight-guifg|. 832 Also see |term_getansicolors()| and |g:terminal_ansi_colors|. 833 834 The colors normally are: 835 0 black 836 1 dark red 837 2 dark green 838 3 brown 839 4 dark blue 840 5 dark magenta 841 6 dark cyan 842 7 light grey 843 8 dark grey 844 9 red 845 10 green 846 11 yellow 847 12 blue 848 13 magenta 849 14 cyan 850 15 white 851 852 These colors are used in the GUI and in the terminal when 853 'termguicolors' is set. When not using GUI colors (GUI mode 854 or 'termguicolors'), the terminal window always uses the 16 855 ANSI colors of the underlying terminal. 856 857 Can also be used as a |method|: > 858 GetBufnr()->term_setansicolors(colors) 859 < 860 Return type: void 861 862 {only available with GUI enabled and/or the |+termguicolors| 863 feature} 864 865 866 term_setapi({buf}, {expr}) *term_setapi()* 867 Set the function name prefix to be used for the |terminal-api| 868 function in terminal {buf}. For example: > 869 :call term_setapi(buf, "Myapi_") 870 :call term_setapi(buf, "") 871 < 872 The default is "Tapi_". When {expr} is an empty string then 873 no |terminal-api| function can be used for {buf}. 874 Setting the API only affects the "call" part, "drop" is always 875 allowed. 876 877 When used as a method the base is used for {buf}: > 878 GetBufnr()->term_setapi({expr}) 879 < 880 Return type: void 881 882 883 term_setkill({buf}, {how}) *term_setkill()* 884 When exiting Vim or trying to close the terminal window in 885 another way, {how} defines whether the job in the terminal can 886 be stopped. 887 When {how} is empty (the default), the job will not be 888 stopped, trying to exit will result in |E947|. 889 Otherwise, {how} specifies what signal to send to the job. 890 See |job_stop()| for the values. 891 892 After sending the signal Vim will wait for up to a second to 893 check that the job actually stopped. 894 895 Can also be used as a |method|: > 896 GetBufnr()->term_setkill(how) 897 < 898 Return type: void 899 900 901 term_setrestore({buf}, {command}) *term_setrestore()* 902 Set the command to write in a session file to restore the job 903 in this terminal. The line written in the session file is: > 904 terminal ++curwin ++cols=%d ++rows=%d {command} 905 < Make sure to escape the command properly. 906 907 Use an empty {command} to run 'shell'. 908 Use "NONE" to not restore this window. 909 910 Can also be used as a |method|: > 911 GetBufnr()->term_setrestore(command) 912 < 913 Return type: void 914 915 916 term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955* 917 Set the size of terminal {buf}. The size of the window 918 containing the terminal will also be adjusted, if possible. 919 If {rows} or {cols} is zero or negative, that dimension is not 920 changed. 921 922 {buf} must be the buffer number of a terminal window. Use an 923 empty string for the current buffer. If the buffer does not 924 exist or is not a terminal window, an error is given. 925 926 Can also be used as a |method|: > 927 GetBufnr()->term_setsize(rows, cols) 928 < 929 Return type: void 930 931 932 term_start({cmd} [, {options}]) *term_start()* 933 Open a terminal window and run {cmd} in it. 934 935 {cmd} can be a string or a List, like with |job_start()|. The 936 string "NONE" can be used to open a terminal window without 937 starting a job, the pty of the terminal can be used by a 938 command like gdb. 939 940 Returns the buffer number of the terminal window. If {cmd} 941 cannot be executed the window does open and shows an error 942 message. 943 If opening the window fails zero is returned. 944 945 {options} are similar to what is used for |job_start()|, see 946 |job-options|. However, not all options can be used. These 947 are supported: 948 all timeout options 949 "stoponexit", "cwd", "env" 950 "callback", "out_cb", "err_cb", "exit_cb", "close_cb" 951 "in_io", "in_top", "in_bot", "in_name", "in_buf" 952 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg" 953 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg" 954 On Unix: 955 stdin, stdout, and stderr are connected to a pty by default, 956 since bidirectional communication with the terminal is 957 required. Setting "out_cb" does not switch stdout from the 958 pty to a pipe. Only setting "err_cb" switches stderr to a 959 pipe. 960 Note: Since a pty is line-buffered and a pipe is 961 block-buffered, the order of output between stdout and stderr 962 may not be preserved. Without "err_cb", stderr uses the same 963 pty as stdout, so the output order is preserved but stdout and 964 stderr cannot be distinguished. 965 966 On MS-Windows with |ConPTY|: 967 stdin, stdout, and stderr are always connected through pipes 968 to the pseudo console, regardless of callback settings. 969 Since stdout and stderr share the same pipe, they cannot be 970 separated by "err_cb". 971 This is because the CreatePseudoConsole() API only accepts one 972 input and one output handle, with no separate handle for 973 stderr. 974 975 Note: term_start() always uses RAW mode for its callbacks. 976 "out_cb" and "err_cb" receive the raw chunk of data as read 977 from the OS. A single callback invocation may contain 978 multiple lines separated by NL, and (for stdout via a pty) 979 each line may have a trailing CR from the line discipline 980 (ONLCR). If per-line handling is desired, the callback must 981 split "msg" on NL and strip the trailing CR itself. 982 Example: > 983 func Handle(ch, msg) 984 for line in split(a:msg, "\n") 985 echom substitute(line, '\r$', '', '') 986 endfor 987 endfunc 988 < 989 There are extra options: 990 "term_name" name to use for the buffer name, instead 991 of the command name. 992 "term_rows" vertical size to use for the terminal, 993 instead of using 'termwinsize'; valid 994 range is from 0 to 1000 995 "term_cols" horizontal size to use for the terminal, 996 instead of using 'termwinsize'; valid 997 range is from 0 to 1000 998 "vertical" split the window vertically; note that 999 other window position can be defined with 1000 command modifiers, such as |:belowright|. 1001 "curwin" use the current window, do not split the 1002 window; fails if the current buffer 1003 cannot be |abandon|ed 1004 "hidden" do not open a window 1005 "norestore" do not add the terminal window to a 1006 session file 1007 "term_kill" what to do when trying to close the 1008 terminal window, see |term_setkill()| 1009 "term_finish" What to do when the job is finished: 1010 "close": close any windows 1011 "noclose": window will not be closed 1012 "open": open window if needed 1013 Note that "open" can be interruptive. 1014 See |term++close|, |term++noclose| and 1015 |term++open|. 1016 "term_opencmd" command to use for opening the window 1017 when "open" is used for "term_finish"; 1018 must have "%d" where the buffer number 1019 goes, e.g. "10split|buffer %d"; when not 1020 specified "botright sbuf %d" is used 1021 "term_highlight" highlight group to use instead of 1022 "Terminal" 1023 "eof_chars" Text to send after all buffer lines were 1024 written to the terminal. When not set 1025 CTRL-D is used on MS-Windows. For Python 1026 use CTRL-Z or "exit()". For a shell use 1027 "exit". A CR is always added. 1028 "ansi_colors" A list of 16 color names or hex codes 1029 defining the ANSI palette used in GUI 1030 color modes. See |g:terminal_ansi_colors|. 1031 "tty_type" (MS-Windows only): Specify which pty to 1032 use. See 'termwintype' for the values. 1033 "term_api" function name prefix for the 1034 |terminal-api| function. See 1035 |term_setapi()|. 1036 1037 Can also be used as a |method|: > 1038 GetCommand()->term_start() 1039 < 1040 Return type: |Number| 1041 1042 1043 term_wait({buf} [, {time}]) *term_wait()* 1044 Wait for pending updates of {buf} to be handled. 1045 {buf} is used as with |term_getsize()|. 1046 {time} is how long to wait for updates to arrive in msec. If 1047 not set then 10 msec will be used. Queued messages will also 1048 be processed similar to |:sleep|. 1049 1050 Can also be used as a |method|: > 1051 GetBufnr()->term_wait() 1052 < 1053 Return type: void 1054 1055 ============================================================================== 1056 3. Terminal communication *terminal-communication* 1057 1058 There are several ways to communicate with the job running in a terminal: 1059 - Use |term_sendkeys()| to send text and escape sequences from Vim to the job. 1060 - Use the JSON API to send encoded commands from the job to Vim. 1061 - Use the |client-server| mechanism. This works on machines with an X server 1062 and on MS-Windows. 1063 1064 1065 Vim to job: term_sendkeys() ~ 1066 *terminal-to-job* 1067 This allows for remote controlling the job running in the terminal. It is a 1068 one-way mechanism. The job can update the display to signal back to Vim. 1069 For example, if a shell is running in a terminal, you can do: > 1070 call term_sendkeys(buf, "ls *.java\<CR>") 1071 1072 This requires for the job to be in the right state where it will do the right 1073 thing when receiving the keys. For the above example, the shell must be 1074 waiting for a command to be typed. 1075 1076 For a job that was written for the purpose, you can use the JSON API escape 1077 sequence in the other direction. E.g.: > 1078 call term_sendkeys(buf, "\<Esc>]51;["response"]\x07") 1079 1080 1081 Job to Vim: JSON API ~ 1082 *terminal-api* 1083 The job can send JSON to Vim, using a special escape sequence. The JSON 1084 encodes a command that Vim understands. Example of such a message: > 1085 <Esc>]51;["drop", "README.md"]<07> 1086 1087 The body is always a list, making it easy to find the end: ]<07>. 1088 The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is 1089 similar to what we are doing here. 1090 1091 Note that any output appearing in a terminal window is checked for this 1092 escape sequence, thus the job can make Vim open a file with the "drop" 1093 command below. |term_setapi()| only restricts which functions the "call" 1094 command may use, it does not affect the "drop" API. 1095 1096 Currently supported commands: 1097 1098 call {funcname} {argument} 1099 1100 Call a user defined function with {argument}. 1101 The function is called with two arguments: the buffer number 1102 of the terminal and {argument}, the decoded JSON argument. 1103 By default, the function name must start with "Tapi_" to avoid 1104 accidentally calling a function not meant to be used for the 1105 terminal API. This can be changed with |term_setapi()|. 1106 The user function should sanity check the argument. 1107 The function can use |term_sendkeys()| to send back a reply. 1108 Example in JSON: > 1109 ["call", "Tapi_Impression", ["play", 14]] 1110 < Calls a function defined like this: > 1111 function Tapi_Impression(bufnum, arglist) 1112 if len(a:arglist) == 2 1113 echomsg "impression " .. a:arglist[0] 1114 echomsg "count " .. a:arglist[1] 1115 endif 1116 endfunc 1117 < Output from `:echo` may be erased by a redraw, use `:echomsg` 1118 to be able to see it with `:messages`. 1119 1120 drop {filename} [options] 1121 1122 Let Vim open a file, like the `:drop` command. If {filename} 1123 is already open in a window, switch to that window. Otherwise 1124 open a new window to edit {filename}. 1125 Note that both the job and Vim may change the current 1126 directory, thus it's best to use the full path. 1127 1128 [options] is only used when opening a new window. If present, 1129 it must be a Dict. Similarly to |++opt|, these entries are 1130 recognized: 1131 "ff" file format: "dos", "mac" or "unix" 1132 "fileformat" idem 1133 "enc" overrides 'fileencoding' 1134 "encoding" idem 1135 "bin" sets 'binary' 1136 "binary" idem 1137 "nobin" resets 'binary' 1138 "nobinary" idem 1139 "bad" specifies behavior for bad characters, see 1140 |++bad| 1141 1142 Example in JSON: > 1143 ["drop", "path/file.txt", {"ff": "dos"}] 1144 1145 You can use |echoraw()| to make Vim send this escape sequence: > 1146 call echoraw("\<ESC>]51;[\"call\", \"Tapi_TryThis\", [\"hello\", 123]]\x07") 1147 call echoraw("\<Esc>]51;[\"drop\", \"README.md\"]\x07") 1148 Note: JSON requires double quotes around string values, hence those have to be 1149 escaped. 1150 1151 Rationale: Why not allow for any command or expression? Because that might 1152 create a security problem. 1153 *terminal-autoshelldir* 1154 This can be used to pass the current directory from a shell to Vim. 1155 Put this in your .vimrc: > 1156 def g:Tapi_lcd(_, path: string) 1157 if isdirectory(path) 1158 execute 'silent lcd ' .. fnameescape(path) 1159 endif 1160 enddef 1161 < 1162 And, in a bash init file: > 1163 if [[ -n "$VIM_TERMINAL" ]]; then 1164 PROMPT_COMMAND='_vim_sync_PWD' 1165 function _vim_sync_PWD() { 1166 printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD" 1167 } 1168 fi 1169 < 1170 Or, for zsh: > 1171 if [[ -n "$VIM_TERMINAL" ]]; then 1172 autoload -Uz add-zsh-hook 1173 add-zsh-hook -Uz chpwd _vim_sync_PWD 1174 function _vim_sync_PWD() { 1175 printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD" 1176 } 1177 fi 1178 < 1179 Or, for fish: > 1180 if test -n "$VIM_TERMINAL" 1181 function _vim_sync_PWD --on-variable=PWD 1182 printf '\033]51;["call", "Tapi_lcd", "%s"]\007' "$PWD" 1183 end 1184 end 1185 1186 1187 Using the client-server feature ~ 1188 *terminal-client-server* 1189 This only works when v:servername is not empty. If needed you can set it, 1190 before opening the terminal, with: > 1191 call remote_startserver('vim-server') 1192 1193 $VIM_SERVERNAME is set in the terminal to pass on the server name. 1194 1195 In the job you can then do something like: > 1196 vim --servername $VIM_SERVERNAME --remote +123 some_file.c 1197 This will open the file "some_file.c" and put the cursor on line 123. 1198 1199 ============================================================================== 1200 4. Remote testing *terminal-testing* 1201 1202 Most Vim tests execute a script inside Vim. For some tests this does not 1203 work, running the test interferes with the code being tested. To avoid this 1204 Vim is executed in a terminal window. The test sends keystrokes to it and 1205 inspects the resulting screen state. 1206 1207 Functions ~ 1208 1209 |term_sendkeys()| send keystrokes to a terminal (not subject to tmap) 1210 |term_wait()| wait for screen to be updated 1211 |term_scrape()| inspect terminal screen 1212 1213 1214 ============================================================================== 1215 5. Diffing screen dumps *terminal-diff* 1216 1217 In some cases it can be bothersome to test that Vim displays the right 1218 characters on the screen. E.g. with syntax highlighting. To make this 1219 simpler it is possible to take a screen dump of a terminal and compare it to 1220 an expected screen dump. 1221 1222 Vim uses the window size, text, color and other attributes as displayed. The 1223 Vim screen size, font and other properties do not matter. Therefore this 1224 mechanism is portable across systems. A conventional screenshot would reflect 1225 all differences, including font size and family. 1226 1227 1228 Writing a screen dump test for Vim ~ 1229 *terminal-dumptest* 1230 For an example see the Test_syntax_c() function in 1231 src/testdir/test_syntax.vim. The main parts are: 1232 - Write a file you want to test with. This is useful for testing syntax 1233 highlighting. You can also start Vim with an empty buffer. 1234 - Run Vim in a terminal with a specific size. The default is 20 lines of 75 1235 characters. This makes sure the dump is always this size. The function 1236 RunVimInTerminal() takes care of this. Pass it the arguments for the Vim 1237 command. 1238 - Send any commands to Vim using |term_sendkeys()|. For example: > 1239 call term_sendkeys(buf, ":echo &lines &columns\<CR>") 1240 - Check that the screen is now in the expected state, using 1241 VerifyScreenDump(). This expects the reference screen dump to be in the 1242 src/testdir/dumps/ directory. Pass the name without ".dump". It is 1243 recommended to use the name of the test function and a sequence number, so 1244 that we know what test is using the file. 1245 - Repeat sending commands and checking the state. 1246 - Finally stop Vim by calling StopVimInTerminal(). 1247 1248 The first time you do this you won't have a screen dump yet. Create an empty 1249 file for now, e.g.: > 1250 touch src/testdir/dumps/Test_function_name_01.dump 1251 1252 The test will then fail, giving you the command to compare the reference dump 1253 and the failed dump, e.g.: > 1254 call term_dumpdiff("failed/Test_func.dump", "dumps/Test_func.dump") 1255 1256 Use this command in Vim, with the current directory set to src/testdir. 1257 Once you are satisfied with the test, move the failed dump in place of the 1258 reference: > 1259 :!mv failed/Test_func.dump dumps/Test_func.dump 1260 1261 1262 Creating a screen dump ~ 1263 *terminal-screendump* 1264 To create the screen dump, run Vim (or any other program) in a terminal and 1265 make it show the desired state. Then use the |term_dumpwrite()| function to 1266 create a screen dump file. For example: > 1267 :call term_dumpwrite(77, "mysyntax.dump") 1268 1269 Here "77" is the buffer number of the terminal. Use `:ls!` to see it. 1270 1271 You can view the screen dump with |term_dumpload()|: > 1272 :call term_dumpload("mysyntax.dump") 1273 1274 To verify that Vim still shows exactly the same screen, run Vim again with 1275 exactly the same way to show the desired state. Then create a screen dump 1276 again, using a different file name: > 1277 :call term_dumpwrite(88, "test.dump") 1278 1279 To assert that the files are exactly the same use |assert_equalfile()|: > 1280 call assert_equalfile("mysyntax.dump", "test.dump") 1281 1282 If there are differences then v:errors will contain the error message. 1283 1284 1285 Comparing screen dumps ~ 1286 *terminal-diffscreendump* 1287 |assert_equalfile()| does not make it easy to see what is different. 1288 To spot the problem use |term_dumpdiff()|: > 1289 call term_dumpdiff("mysyntax.dump", "test.dump") 1290 1291 This will open a window consisting of three parts: 1292 1. The contents of the first dump 1293 2. The difference between the first and second dump 1294 3. The contents of the second dump 1295 1296 You can usually see what differs in the second part. Use the 'ruler' to 1297 relate it to the position in the first or second dump. Letters indicate the 1298 kind of difference: 1299 X different character 1300 > cursor in first but not in second 1301 < cursor in second but not in first 1302 w character width differs (single vs double width) 1303 f foreground color differs 1304 b background color differs 1305 a attribute differs (bold, underline, reverse, etc.) 1306 ? character missing in both 1307 + character missing in first 1308 - character missing in second 1309 1310 Alternatively, press "s" to swap the first and second dump. Do this several 1311 times so that you can spot the difference in the context of the text. 1312 1313 ============================================================================== 1314 6. Debugging *terminal-debug* *terminal-debugger* 1315 *package-termdebug* *termdebug* 1316 1317 The Terminal debugging plugin can be used to debug a program with gdb and view 1318 the source code in a Vim window. Since this is completely contained inside 1319 Vim this also works remotely over an ssh connection. 1320 1321 When the |+terminal| feature is missing, the plugin will use the "prompt" 1322 buffer type, if possible. The running program will then use a newly opened 1323 terminal window. See |termdebug-prompt| below for details. 1324 1325 1326 Starting ~ 1327 *termdebug-starting* 1328 Load the plugin with this command: > 1329 packadd termdebug 1330 When loading the plugin from the |.vimrc| file, add the "!" attribute: > 1331 packadd! termdebug 1332 < *:Termdebug* 1333 To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the 1334 command name, for example: > 1335 :Termdebug vim 1336 1337 This opens two windows: 1338 1339 gdb window A terminal window in which "gdb vim" is executed. Here you 1340 can directly interact with gdb. The buffer name is "!gdb". 1341 1342 program window A terminal window for the executed program. When "run" is 1343 used in gdb the program I/O will happen in this window, so 1344 that it does not interfere with controlling gdb. The buffer 1345 name is "debugged program". 1346 1347 The current window is used to show the source code. When gdb pauses the 1348 source file location will be displayed, if possible. A sign is used to 1349 highlight the current position, using highlight group debugPC. 1350 1351 If the buffer in the current window is modified, another window will be opened 1352 to display the current gdb position. You can use `:Winbar` to add a window 1353 toolbar there. 1354 1355 Focus the terminal of the executed program to interact with it. This works 1356 the same as any command running in a terminal window. 1357 1358 When the debugger ends, typically by typing "quit" in the gdb window, the two 1359 opened windows are closed. 1360 1361 Only one debugger can be active at a time. 1362 1363 *termdebug-timeout* 1364 Depending on how gdb is launched, termdebug startup time may vary. 1365 To avoid termdebug to get stuck if the startup process of gdb takes too long, 1366 a configurable timeout is included. Such time out is configurable in terms of 1367 multiple of 10ms: > 1368 let g:termdebug_config['timeout'] = 500 # 500 * 10ms = 5 seconds. 1369 1370 The default timeout is 3000 ms. 1371 *:TermdebugCommand* 1372 If you want to give specific commands to the command being debugged, you can 1373 use the `:TermdebugCommand` command followed by the command name and 1374 additional parameters. > 1375 :TermdebugCommand vim --clean -c ':set nu' 1376 1377 Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang 1378 argument to start the command right away, without pausing at the gdb window 1379 (and cursor will be in the debugged window). For example: > 1380 :TermdebugCommand! vim --clean 1381 1382 To attach gdb to an already running executable or use a core file, pass extra 1383 arguments. E.g.: > 1384 :Termdebug vim core 1385 :Termdebug vim 98343 1386 1387 If no argument is given, you'll end up in a gdb window, in which you need to 1388 specify which command to run using e.g. the gdb `file` command. 1389 1390 1391 Example session ~ 1392 *termdebug-example* 1393 Start in the Vim "src" directory and build Vim: > 1394 % make 1395 Make sure that debug symbols are present, usually that means that $CFLAGS 1396 includes "-g". 1397 1398 Start Vim: > 1399 % ./vim 1400 1401 Load the termdebug plugin and start debugging Vim: > 1402 :packadd termdebug 1403 :Termdebug vim 1404 You should now have three windows: 1405 source - where you started, has a window toolbar with buttons 1406 gdb - you can type gdb commands here 1407 program - the executed program will use this window 1408 1409 You can use CTRL-W CTRL-W or the mouse to move focus between windows. 1410 Put focus on the gdb window and type: > 1411 break ex_help 1412 run 1413 Vim will start running in the program window. Put focus there and type: > 1414 :help gui 1415 Gdb will run into the ex_help breakpoint. The source window now shows the 1416 ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the 1417 breakpoint was set. The line where the debugger stopped is highlighted. You 1418 can now step through the program. Let's use the mouse: click on the "Next" 1419 button in the window toolbar. You will see the highlighting move as the 1420 debugger executes a line of source code. 1421 1422 Click "Next" a few times until the for loop is highlighted. Put the cursor on 1423 the end of "eap->arg", then click "Eval" in the toolbar. You will see this 1424 displayed: 1425 "eap->arg": 0x555555e68855 "gui" ~ 1426 This way you can inspect the value of local variables. You can also focus the 1427 gdb window and use a "print" command, e.g.: > 1428 print *eap 1429 If mouse pointer movements are working, Vim will also show a balloon when the 1430 mouse rests on text that can be evaluated by gdb. 1431 1432 Now go back to the source window and put the cursor on the first line after 1433 the for loop, then type: > 1434 :Break 1435 You will see a ">>" marker appear, this indicates the new breakpoint. Now 1436 click "Cont" in the toolbar and the code until the breakpoint will be 1437 executed. 1438 1439 You can type more advanced commands in the gdb window. For example, type: > 1440 watch curbuf 1441 Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution 1442 will now continue until the value of "curbuf" changes, which is in do_ecmd(). 1443 To remove this watchpoint again type in the gdb window: > 1444 delete 3 1445 1446 You can see the stack by typing in the gdb window: > 1447 where 1448 Move through the stack frames, e.g. with: > 1449 frame 3 1450 The source window will show the code, at the point where the call was made to 1451 a deeper level. 1452 1453 1454 Stepping through code ~ 1455 *termdebug-stepping* 1456 Put focus on the gdb window to type commands there. Some common ones are: 1457 - CTRL-C interrupt the program 1458 - next execute the current line and stop at the next line 1459 - step execute the current line and stop at the next statement, 1460 entering functions 1461 - until execute until past the current cursor line or past a specified 1462 position or the current stack frame returns 1463 - finish execute until leaving the current function 1464 - where show the stack 1465 - frame N go to the Nth stack frame 1466 - continue continue execution 1467 1468 *:Run* *:Arguments* 1469 In the window showing the source code these commands can be used to control 1470 gdb: 1471 `:Run` [args] run the program with [args] or the previous arguments 1472 `:Arguments` {args} set arguments for the next `:Run` 1473 1474 *:Break* set a breakpoint at the cursor position 1475 :Break [{position}] [thread {nr}] [if {expr}] 1476 set a breakpoint at the specified position 1477 if {position} is omitted, use the current file and line 1478 thread {nr} limits the breakpoint to one thread 1479 if {expr} sets a conditional breakpoint 1480 Examples: > 1481 :Break if argc == 1 1482 :Break 42 thread 3 if x > 10 1483 :Break main 1484 < 1485 *:Tbreak* set a temporary breakpoint at the cursor position 1486 :Tbreak [{position}] [thread {nr}] [if {expr}] 1487 like `:Break`, but the breakpoint is deleted after 1488 it is hit once 1489 Examples: > 1490 :Tbreak if argc == 1 1491 :Tbreak 42 thread 3 if x > 10 1492 :Tbreak main 1493 < 1494 *:Clear* delete the breakpoint at the cursor position 1495 *:ToggleBreak* set a breakpoint at the cursor position or delete all 1496 breakpoints at the cursor position 1497 1498 *:Step* execute the gdb "step" command 1499 *:Over* execute the gdb "next" command (`:Next` is a Vim command) 1500 *:Until* execute the gdb "until" command 1501 *:Finish* execute the gdb "finish" command 1502 *:Continue* execute the gdb "continue" command 1503 *:RunOrContinue* execute the gdb "continue" command if program is running, 1504 otherwise run the program 1505 *:Stop* interrupt the program 1506 1507 If 'mouse' is set the plugin adds a window toolbar with these entries: 1508 Step `:Step` 1509 Next `:Over` 1510 Finish `:Finish` 1511 Cont `:Continue` 1512 Stop `:Stop` 1513 Eval `:Evaluate` 1514 This way you can use the mouse to perform the most common commands. You need 1515 to have the 'mouse' option set to enable mouse clicks. 1516 See |termdebug_winbar| for configuring this toolbar. 1517 *:Winbar* 1518 You can add the window toolbar in other windows you open with: > 1519 :Winbar 1520 1521 If gdb stops at a source line and there is no window currently showing the 1522 source code, a new window will be created for the source code. This also 1523 happens if the buffer in the source code window has been modified and can't be 1524 abandoned. 1525 1526 Gdb gives each breakpoint a number. In Vim the number shows up in the sign 1527 column, with a red background. You can use these gdb commands: 1528 - info break list breakpoints 1529 - delete N delete breakpoint N 1530 You can also use the `:Clear` command if the cursor is in the line with the 1531 breakpoint, or use the "Clear breakpoint" right-click menu entry. 1532 1533 1534 Inspecting variables ~ 1535 *termdebug-variables* *:Evaluate* 1536 `:Evaluate` evaluate the expression under the cursor 1537 `K` same (see |termdebug_map_K| to disable) 1538 `:Evaluate` {expr} evaluate {expr} 1539 `:'<,'>Evaluate` 1540 `{Visual}K` evaluate the Visually selected text 1541 1542 This is similar to using "print" in the gdb window. 1543 You can usually shorten `:Evaluate` to `:Ev`. 1544 1545 1546 Navigating stack frames ~ 1547 *termdebug-frames* *:Frame* *:Up* *:Down* 1548 `:Frame` [frame] select frame [frame], which is a frame number, 1549 address, or function name (default: current frame) 1550 `:Up` [count] go up [count] frames (default: 1; the frame that 1551 called the current) 1552 `+` same (see |termdebug_map_plus| to disable) 1553 `:Down` [count] go down [count] frames (default: 1; the frame called 1554 by the current) 1555 `-` same (see |termdebug_map_minus| to disable) 1556 1557 1558 Other commands ~ 1559 *termdebug-commands* 1560 *:Gdb* jump to the gdb window 1561 *:Program* jump to the window with the running program 1562 *:Source* jump to the window with the source code, create it if there 1563 isn't one 1564 *:Asm* jump to the window with the disassembly, create it if there 1565 isn't one 1566 *:Var* jump to the window with the local and argument variables, 1567 create it if there isn't one. This window updates whenever the 1568 program is stopped 1569 1570 Events ~ 1571 *termdebug-events* 1572 Four autocommands can be used: > 1573 au User TermdebugStartPre echomsg 'debugging starting' 1574 au User TermdebugStartPost echomsg 'debugging started' 1575 au User TermdebugStopPre echomsg 'debugging stopping' 1576 au User TermdebugStopPost echomsg 'debugging stopped' 1577 < 1578 *TermdebugStartPre* 1579 TermdebugStartPre Before starting debugging. 1580 Not triggered if the debugger is already 1581 running or the debugger command cannot be 1582 executed. 1583 *TermdebugStartPost* 1584 TermdebugStartPost After debugging has initialized. 1585 If a "!" bang is passed to `:Termdebug` or 1586 `:TermdebugCommand` the event is triggered 1587 before running the provided command in gdb. 1588 *TermdebugStopPre* 1589 TermdebugStopPre Before debugging ends, when gdb is terminated, 1590 most likely after issuing a "quit" command in 1591 the gdb window. 1592 *TermdebugStopPost* 1593 TermdebugStopPost After debugging has ended, gdb-related windows 1594 are closed, debug buffers wiped out and 1595 the state before the debugging was restored. 1596 1597 1598 Customizing ~ 1599 *termdebug-customizing* *g:termdebug_config* 1600 In the past several global variables were used for configuration. These are 1601 deprecated and using the g:termdebug_config dictionary is preferred. When 1602 g:termdebug_config exists the other global variables will NOT be used. 1603 The recommended way is to start with an empty dictionary: > 1604 let g:termdebug_config = {} 1605 1606 Then you can add entries to the dictionary as mentioned below. The 1607 deprecated global variable names are mentioned for completeness. If you are 1608 switching over to using g:termdebug_config you can find the old variable name 1609 and take over the value, then delete the deprecated variable. 1610 1611 1612 Prompt mode ~ 1613 *termdebug-prompt* 1614 When the |+terminal| feature is not supported and on MS-Windows, gdb will run 1615 in a buffer with 'buftype' set to "prompt". This works slightly differently: 1616 - The gdb window will be in Insert mode while typing commands. Go to Normal 1617 mode with <Esc>, then you can move around in the buffer, copy/paste, etc. 1618 Go back to editing the gdb command with any command that starts Insert mode, 1619 such as `a` or `i`. 1620 - The program being debugged will run in a separate window. On MS-Windows 1621 this is a new console window. On Unix, if the |+terminal| feature is 1622 available a Terminal window will be opened to run the debugged program in. 1623 1624 *termdebug_use_prompt* 1625 Prompt mode can be used even when the |+terminal| feature is present with: > 1626 let g:termdebug_config['use_prompt'] = v:true 1627 If there is no g:termdebug_config you can use: > 1628 let g:termdebug_use_prompt = v:true 1629 1630 < 1631 However, the latter form will be deprecated in future releases. 1632 1633 1634 Mappings ~ 1635 The termdebug plugin enables a few default mappings. All those mappings 1636 are reset to their original values once the termdebug session concludes. 1637 1638 *termdebug_map_K* *termdebug-mappings* 1639 The K key is normally mapped to |:Evaluate| unless a buffer local (|:map-local|) 1640 mapping to K already exists. If you do not want this use: > 1641 let g:termdebug_config['map_K'] = v:false 1642 If there is no g:termdebug_config you can use: > 1643 let g:termdebug_map_K = v:false 1644 < 1645 However, the latter form will be deprecated in future releases. 1646 1647 *termdebug_map_minus* 1648 The - key is normally mapped to |:Down| unless a buffer local mapping to the - 1649 key already exists. If you do not want this use: > 1650 let g:termdebug_config['map_minus'] = v:false 1651 < 1652 *termdebug_map_plus* 1653 The + key is normally mapped to |:Up| unless a buffer local mapping to the + 1654 key already exists. If you do not want this use: > 1655 let g:termdebug_config['map_plus'] = v:false 1656 < 1657 *termdebug_disasm_window* 1658 If you want the Asm window shown by default, set the "disasm_window" flag to 1659 1. The "disasm_window_height" entry can be used to set the window height: > 1660 let g:termdebug_config['disasm_window'] = v:true 1661 let g:termdebug_config['disasm_window_height'] = 15 1662 If there is no g:termdebug_config you can use: > 1663 let g:termdebug_disasm_window = 15 1664 1665 However, the latter form will be deprecated in future releases. 1666 1667 Any value greater than 1 will set the Asm window height to that value. 1668 If the current window has enough horizontal space, it will be vertically split 1669 and the Asm window will be shown side by side with the source code window (and 1670 the height option won't be used). 1671 1672 *termdebug_variables_window* 1673 If you want the Var window shown by default, set the "variables_window" flag 1674 to 1. The "variables_window_height" entry can be used to set the window 1675 height: > 1676 let g:termdebug_config['variables_window'] = v:true 1677 let g:termdebug_config['variables_window_height'] = 15 1678 If there is no g:termdebug_config you can use: > 1679 let g:termdebug_variables_window = 15 1680 1681 However, the latter form will be deprecated in future releases. 1682 1683 Any value greater than 1 will set the Var window height to that value. 1684 If the current window has enough horizontal space, it will be vertically split 1685 and the Var window will be shown side by side with the source code window (and 1686 the height options won't be used). 1687 1688 1689 Communication ~ 1690 *termdebug-communication* 1691 There is another, hidden, buffer, which is used for Vim to communicate with 1692 gdb. The buffer name is "gdb communication". Do not delete this buffer, it 1693 will break the debugger. 1694 1695 Gdb has some weird behavior, the plugin does its best to work around that. 1696 For example, after typing "continue" in the gdb window a CTRL-C can be used to 1697 interrupt the running program. But after using the MI command 1698 "-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see 1699 "continue" being used for the `:Continue` command, instead of using the 1700 communication channel. 1701 1702 1703 Remote debugging ~ 1704 *termdebug-remote* 1705 One of the main issues of remote debugging is the access to the debuggee's 1706 source files. The plugin can profit from system and vim's networking 1707 capabilities to workaround this. 1708 *termdebug-remote-example* 1709 The |termdebug-example| can be replicated by running the `gdb` debugger to 1710 debug Vim on a remote Linux machine accessible via `ssh`. 1711 1712 - Build Vim as explained in the local example. 1713 1714 - If "socat" is not available in the remote machine 'terminal' mode will not 1715 work properly. Fall back to |termdebug_use_prompt|: > 1716 :let g:termdebug_config = {} 1717 :let g:termdebug_config['use_prompt'] = v:true 1718 1719 - Specify the command line to run the remote `gdb` instance: > 1720 :let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb'] 1721 < Explaining `ssh` is beyond the scope of this example, but notice the 1722 command line can be greatly simplified by specifying the user, keys and 1723 other options into the `$HOME/.ssh/config` file. 1724 1725 - Provide a hint for translating remote paths into |netrw| paths: > 1726 :let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' } 1727 1728 - Load the termdebug plugin and start debugging Vim: > 1729 :packadd termdebug 1730 :Termdebug vim 1731 1732 You now have the same three windows of the local example and can follow the 1733 very same steps. The only difference is that the source windows displays a 1734 netrw buffer instead of a local one. 1735 1736 *termdebug-substitute-path* 1737 Use the `g:termdebug_config['substitute_path']` entry to map remote to local 1738 files using the same strategy that gdb's `substitute-path` command uses. 1739 For example: 1740 - Use |netrw| to access files remoting via ssh: > 1741 let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb'] 1742 let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' } 1743 < Note: that the key specifies the remote machine root path and the value 1744 the local one. 1745 - Use Windows' `UNC` paths to access `WSL2` sources: > 1746 let g:termdebug_config['command'] = ['wsl', 'gdb'] 1747 let g:termdebug_config['substitute_path'] = { 1748 \ '/': '\\wsl.localhost\Ubuntu-22.04\', 1749 \ '/mnt/c/': 'C:/' } 1750 < Note: that several mappings are required: one for each drive unit 1751 and one for the linux filesystem (queried via `wslpath`). 1752 1753 In this mode any `ssh` or `wsl` command would be detected and a similar 1754 command would be used to launch `socat` in a remote `tty` terminal session 1755 and connect it to `gdb`. 1756 If `socat` is not available a plain remote terminal would be used as 1757 fallback. 1758 The next session shows how to override this default behaviour. 1759 1760 *termdebug-remote-window* 1761 In order to use another remote terminal client, set "remote_window" entry 1762 in `g:termdebug_config` variable before invoking `:Termdebug`. For example: 1763 - Debugging inside a docker container using "prompt" mode: > 1764 let g:termdebug_config['use_prompt'] = v:true 1765 let g:termdebug_config['command'] = ['docker', 'run', '-i', 1766 \ '--rm', '--name', 'container-name', 'image-name', 'gdb'] 1767 let g:termdebug_config['remote_window'] = 1768 \ ['docker', 'exec', '-ti', 'container-name' 1769 \ ,'socat', '-dd', '-', 'PTY,raw,echo=0'] 1770 1771 - Debugging inside a docker container using a "terminal buffer". 1772 The container should be already running because unlike the previous 1773 case for `terminal mode` "program" and "communication" ptys are created 1774 before the gdb one: > 1775 $ docker run -ti --rm --name container-name immage-name 1776 1777 < Then, launch the debugger: > 1778 let g:termdebug_config['use_prompt'] = v:false " default 1779 let g:termdebug_config['command'] = 1780 \ ['docker', 'exec', '-ti', 'container-name', 'gdb'] 1781 let g:termdebug_config['remote_window'] = 1782 \ ['docker', 'exec', '-ti', 'container-name' 1783 \ ,'socat', '-dd', '-', 'PTY,raw,echo=0'] 1784 1785 Note: "command" cannot use `-t` on |termdebug-prompt| mode because prompt 1786 buffers cannot handle `tty` connections. 1787 The "remote_window" command must use `-t` because otherwise it will lack 1788 a `pty slave device` for gdb to connect. 1789 Note: "socat" must be available in the remote machine on "terminal" mode. 1790 Note: docker container sources can be accessible combining `volumes` 1791 with mappings (see |termdebug-substitute-path|). 1792 1793 GDB command ~ 1794 *g:termdebugger* 1795 To change the name of the gdb command, set "debugger" entry in 1796 g:termdebug_config or the "g:termdebugger" variable before invoking 1797 `:Termdebug`: > 1798 let g:termdebug_config['command'] = "mygdb" 1799 1800 If there is no g:termdebug_config you can use: > 1801 let g:termdebugger = "mygdb" 1802 1803 However, the latter form will be deprecated in future releases. 1804 1805 If the command needs an argument use a List: > 1806 let g:termdebug_config['command'] = ['rr', 'replay', '--'] 1807 1808 If there is no g:termdebug_config you can use: > 1809 let g:termdebugger = ['rr', 'replay', '--'] 1810 1811 Several arguments will be added to make gdb work well for the debugger. 1812 If you want to modify them, add a function to filter the argument list: > 1813 let g:termdebug_config['command_filter'] = MyDebugFilter 1814 1815 A "command_filter" scenario is solving escaping issues on remote debugging 1816 over "ssh". For convenience a default filter is provided for escaping 1817 whitespaces inside the arguments. It is automatically configured for "ssh", 1818 but can be employed in other use cases like this: > 1819 let g:termdebug_config['command_filter'] = 1820 / function('g:Termdebug_escape_whitespace') 1821 1822 If you do not want the arguments to be added, but you do need to set the 1823 "pty", use a function to add the necessary arguments: > 1824 let g:termdebug_config['command_add_args'] = MyAddArguments 1825 The function will be called with the list of arguments so far, and a second 1826 argument that is the name of the pty. 1827 *gdb-version* 1828 Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI 1829 interface. The "new-ui" command requires gdb version 7.12 or later. If you 1830 get this error: 1831 Undefined command: "new-ui". Try "help".~ 1832 Then your gdb is too old. 1833 1834 1835 Colors ~ 1836 *hl-debugPC* *hl-debugBreakpoint* 1837 The color of the signs can be adjusted with these highlight groups: 1838 - debugPC the current position 1839 - debugBreakpoint a breakpoint 1840 1841 The defaults are, when 'background' is "light": 1842 hi debugPC term=reverse ctermbg=lightblue guibg=lightblue 1843 hi debugBreakpoint term=reverse ctermbg=red guibg=red 1844 1845 When 'background' is "dark": 1846 hi debugPC term=reverse ctermbg=darkblue guibg=darkblue 1847 hi debugBreakpoint term=reverse ctermbg=red guibg=red 1848 1849 1850 Shortcuts ~ 1851 *termdebug_shortcuts* 1852 You can define your own shortcuts (mappings) to control gdb, that can work in 1853 any window, using the TermDebugSendCommand() function. Example: > 1854 map ,w :call TermDebugSendCommand('where')<CR> 1855 The argument is the gdb command. 1856 1857 1858 Popup menu ~ 1859 *termdebug_popup* 1860 By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds 1861 these entries to the popup menu: 1862 Set breakpoint `:Break` 1863 Clear breakpoint `:Clear` 1864 Evaluate `:Evaluate` 1865 If you don't want this then disable it with: > 1866 let g:termdebug_config['popup'] = 0 1867 If there is no g:termdebug_config you can use: > 1868 let g:termdebug_popup = 0 1869 1870 However, the latter form will be deprecated in future releases. 1871 1872 1873 Change default signs ~ 1874 *termdebug_signs* 1875 Termdebug uses the hex number of the breakpoint ID in the signcolumn to 1876 represent breakpoints. If it is greater than "0xFF", then it will be 1877 displayed as "F+", because there are only two screen cells available for the 1878 sign. You may also use decimal breakpoint signs instead, in which case IDs 1879 greater than 99 will be displayed as "9+". 1880 1881 If you want to customize the breakpoint signs to show `>>` in the signcolumn: > 1882 let g:termdebug_config['sign'] = '>>' 1883 You can also specify individual signs for the first several breakpoints: > 1884 let g:termdebug_config['signs'] = ['>1', '>2', '>3', '>4', '>5', 1885 \ '>6', '>7', '>8', '>9'] 1886 let g:termdebug_config['sign'] = '>>' 1887 If you would like to use decimal (base 10) breakpoint signs: > 1888 let g:termdebug_config['sign_decimal'] = 1 1889 If the variable g:termdebug_config does not yet exist, you can use: > 1890 let g:termdebug_config = {'sign': '>>'} 1891 Likewise, to enable decimal signs: > 1892 let g:termdebug_config = {'sign_decimal': 1} 1893 1894 1895 Window toolbar ~ 1896 *termdebug_winbar* 1897 By default the Termdebug plugin creates a window toolbar if the mouse is 1898 enabled (see |:Winbar|). If you don't want this then disable it with: > 1899 let g:termdebug_config['winbar'] = 0 1900 1901 1902 Vim window width ~ 1903 *termdebug_wide* 1904 To change the width of the Vim window when debugging starts and use a vertical 1905 split: > 1906 let g:termdebug_config['wide'] = 163 1907 If there is no g:termdebug_config you can use: > 1908 let g:termdebug_wide = 163 1909 1910 However, the latter form will be deprecated in future releases. 1911 1912 This will set 'columns' to 163 when `:Termdebug` is used. The value is 1913 restored when quitting the debugger. 1914 1915 If the wide value is set and 'columns' is already a greater value, then a 1916 vertical split will be used without modifying 'columns'. 1917 1918 Set the wide value to 1 to use a vertical split without ever changing 1919 'columns'. This is useful when the terminal can't be resized by Vim. 1920 1921 1922 Evaluate in Popup Window at Cursor ~ 1923 *termdebug_evaluate_in_popup* 1924 By default |:Evaluate| will simply echo its output. For larger entities this 1925 might become difficult to read or even truncated. 1926 Alternatively, the evaluation result may be output into a popup window at the 1927 current cursor position: > 1928 let g:termdebug_config['evaluate_in_popup'] = v:true 1929 This can also be used in a "one-shot" manner: > 1930 func OnCursorHold() 1931 let g:termdebug_config['evaluate_in_popup'] = v:true 1932 :Evaluate 1933 let g:termdebug_config['evaluate_in_popup'] = v:false 1934 endfunc 1935 < 1936 1937 Contributing ~ 1938 *termdebug_contributing* 1939 Contributions for termdebug improvements are welcome. 1940 However, it is fairly common that during the development process you need some 1941 mechanisms like `echo` statements (or similar) to help you in your job. 1942 For this reason, you can set: > 1943 let g:termdebug_config['debug'] = v:true 1944 < 1945 This sets the `DEBUG` variable to `true`, which can be referenced in the 1946 source code. An example of its usage follows: > 1947 if exists('g:termdebug_loaded') 1948 if DEBUG 1949 Echoerr('Termdebug already loaded.') 1950 endif 1951 finish 1952 endif 1953 < 1954 1955 vim:tw=78:ts=8:noet:ft=help:norl: