1*terminal.txt* For Vim version 8.2. Last change: 2021 Nov 13 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Terminal window support *terminal* *terminal-window* 8 9 10The 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 14 151. 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| 33 Writing a screen dump test for Vim |terminal-dumptest| 34 Creating a screen dump |terminal-screendump| 35 Comparing screen dumps |terminal-diffscreendump| 366. Debugging |terminal-debug| 37 Starting |termdebug-starting| 38 Example session |termdebug-example| 39 Stepping through code |termdebug-stepping| 40 Inspecting variables |termdebug-variables| 41 Other commands |termdebug-commands| 42 Prompt mode |termdebug-prompt| 43 Communication |termdebug-communication| 44 Customizing |termdebug-customizing| 45 46{only available when compiled with the |+terminal| feature} 47The terminal feature requires the |+job| and |+channel| features. 48 49============================================================================== 501. Basic use *terminal-use* 51 52This feature is for running a terminal emulator in a Vim window. A job can be 53started connected to the terminal emulator. For example, to run a shell: > 54 :term bash 55 56Or to run build command: > 57 :term make myprogram 58 59The job runs asynchronously from Vim, the window will be updated to show 60output from the job, also while editing in another window. 61 62 63Typing ~ 64 *terminal-typing* 65When the keyboard focus is in the terminal window, typed keys will be sent to 66the job. This uses a pty when possible. You can click outside of the 67terminal window to move keyboard focus elsewhere. 68 69 *t_CTRL-W_CTRL-W* *t_CTRL-W_:* 70CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.: 71 CTRL-W CTRL-W move focus to the next window 72 CTRL-W : enter an Ex command 73See |CTRL-W| for more commands. 74 75Special in the terminal window: *t_CTRL-W_.* *t_CTRL-W_N* 76 CTRL-W . send a CTRL-W to the job in the terminal 77 CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal 78 CTRL-W N go to Terminal-Normal mode, see |Terminal-mode| 79 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| 80 CTRL-W " {reg} paste register {reg} *t_CTRL-W_quote* 81 Also works with the = register to insert the result of 82 evaluating an expression. 83 CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C| 84 CTRL-W gt go to next tabpage, same as `gt` *t_CTRL-W_gt* 85 CTRL-W gT go to previous tabpage, same as `gT` *t_CTRL-W_gT* 86 87See option 'termwinkey' for specifying another key instead of CTRL-W that 88will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey' 89to the job. For example: 90 'termwinkey' CTRL-W move focus to the next window 91 'termwinkey' : enter an Ex command 92 'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal 93 'termwinkey' . send 'termwinkey' to the job in the terminal 94 'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal 95 'termwinkey' N go to terminal Normal mode, see below 96 'termwinkey' CTRL-N same as CTRL-W N |t_CTRL-W_N| 97 'termwinkey' CTRL-C same as CTRL-W CTRL-C |t_CTRL-W_CTRL-C| 98 *t_CTRL-\_CTRL-N* 99The special key combination CTRL-\ CTRL-N can be used to switch to Normal 100mode, just like this works in any other mode. 101 *t_CTRL-W_CTRL-C* 102CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a 103CTRL-BREAK will also kill the job. 104 105If you type CTRL-C the effect depends on what the pty has been configured to 106do. For simple commands this causes a SIGINT to be sent to the job, which 107would end it. Other commands may ignore the SIGINT or handle the CTRL-C 108themselves (like Vim does). 109 110To change the keys you type use terminal mode mappings, see |:tmap|. 111These are defined like any mapping, but apply only when typing keys that are 112sent to the job running in the terminal. For example, to make F1 switch 113to Terminal-Normal mode: > 114 tnoremap <F1> <C-W>N 115You can use Esc, but you need to make sure it won't cause other keys to 116break (cursor keys start with an Esc, so they may break), this probably only 117works in the GUI: > 118 tnoremap <Esc> <C-W>N 119 set notimeout ttimeout timeoutlen=100 120 121You can also create menus similar to terminal mode mappings, but you have to 122use |:tlmenu| instead of |:tmenu|. 123 124 *options-in-terminal* 125After opening the terminal window and setting 'buftype' to "terminal" the 126|TerminalWinOpen| autocommand event is triggered. This makes it possible to set 127options specifically for the terminal window and buffer. Example: > 128 au TerminalWinOpen * setlocal bufhidden=hide 129This only works properly if the terminal is not hidden. 130 131For both hidden and non-hidden terminals this works, both for buffer-local and 132window-local options: > 133 au TerminalWinOpen,BufWinEnter * if &buftype == 'terminal' 134 \ | setlocal bufhidden=hide colorcolumn=123 135 \ | endif 136Note that for a hidden terminal the options are not set until the terminal is 137no longer hidden. 138 139There is also the |TerminalOpen| event. Keep in mind this may be triggered 140for a hidden terminal, then the current window and buffer are not that of the 141new terminal. 142You need to use <abuf>, which is set to the terminal buffer. Example: > 143 au TerminalOpen * call setbufvar(expand('<abuf>')->str2nr(), 144 \ '&termwinscroll', 1000) 145For a window-local option, you need to delay setting the option until the 146terminal window has been created (this only works for a hidden terminal): > 147 au TerminalOpen * exe printf( 148 \ 'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d', 149 \ expand('<abuf>')->str2nr(), 123) 150For a non-hidden terminal use |TerminalWinOpen|. 151 152Mouse events (click and drag) are passed to the terminal. Mouse move events 153are only passed when Vim itself is receiving them. For a terminal that is 154when 'balloonevalterm' is enabled. 155 156 157Size and color ~ 158 *terminal-size-color* 159See option 'termwinsize' for controlling the size of the terminal window. 160(TODO: scrolling when the terminal is larger than the window) 161 162The job running in the terminal can change the colors. The default foreground 163and background colors are taken from Vim, the Normal highlight group. 164 165For a color terminal the 'background' option is used to decide whether the 166terminal window will start with a white or black background. 167 168To use a different color the Terminal highlight group can be used, for 169example: > 170 hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue 171Instead of Terminal another group can be specified with the "term_highlight" 172option for `term_start()`. 173 174 *g:terminal_ansi_colors* 175In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new 176terminal windows may be configured using the variable 177`g:terminal_ansi_colors`, which should be a list of 16 color names or 178hexadecimal color codes, similar to those accepted by |highlight-guifg|. When 179not using GUI colors, the terminal window always uses the 16 ANSI colors of 180the underlying terminal. 181When using `term_start()` the colors can be set with the "ansi_colors" option. 182The |term_setansicolors()| function can be used to change the colors, and 183|term_getansicolors()| to get the currently used colors. 184 185 186Command syntax ~ 187 188:[range]ter[minal] [options] [command] *:ter* *:terminal* 189 Open a new terminal window. 190 191 If [command] is provided run it as a job and connect 192 the input and output to the terminal. 193 If [command] is not given the 'shell' option is used. 194 if [command] is NONE no job is started, the pty of the 195 terminal can be used by a command like gdb. 196 197 If [command] is missing the default behavior is to 198 close the terminal when the shell exits. This can be 199 changed with the ++noclose argument. 200 If [command] is present the default behavior is to 201 keep the terminal open in Terminal-Normal mode. This 202 can be changed with the ++close argument. 203 204 No Vim command can follow, any | is included in 205 [command]. Use `:execute` if you must have a Vim 206 command following in the same line. 207 208 A new buffer will be created, using [command] or 209 'shell' as the name, prefixed with a "!". If a buffer 210 by this name already exists a number is added in 211 parentheses. E.g. if "gdb" exists the second terminal 212 buffer will use "!gdb (1)". 213 214 If [range] is given the specified lines are used as 215 input for the job. It will not be possible to type 216 keys in the terminal window. For MS-Windows see the 217 ++eof argument below. 218 219 *term++close* *term++open* 220 Supported [options] are: 221 ++close The terminal window will close 222 automatically when the job terminates. 223 |terminal-close| 224 ++noclose The terminal window will NOT close 225 automatically when the job terminates. 226 ++open When the job terminates and no window 227 shows it, a window will be opened. 228 Note that this can be interruptive. 229 The last of ++close, ++noclose and ++open 230 matters and rules out earlier arguments. 231 232 ++curwin Open the terminal in the current 233 window, do not split the current 234 window. Fails if the current buffer 235 cannot be |abandon|ed. 236 ++hidden Open the terminal in a hidden buffer, 237 no window will be used. 238 ++norestore Do not include this terminal window 239 in a session file. 240 ++shell Instead of executing {command} 241 directly, use a shell, like with 242 `:!command` *E279* 243 {only works on Unix and MS-Windows} 244 ++kill={how} When trying to close the terminal 245 window kill the job with {how}. See 246 |term_setkill()| for the values. 247 ++rows={height} Use {height} for the terminal window 248 height. If the terminal uses the full 249 Vim height (no window above or below 250 the terminal window) the command line 251 height will be reduced as needed. 252 ++cols={width} Use {width} for the terminal window 253 width. If the terminal uses the full 254 Vim width (no window left or right of 255 the terminal window) this value is 256 ignored. 257 ++eof={text} When using [range]: text to send after 258 the last line was written. Cannot 259 contain white space. A CR is 260 appended. For MS-Windows the default 261 is to send CTRL-D. 262 E.g. for a shell use "++eof=exit" and 263 for Python "++eof=exit()". Special 264 codes can be used like with `:map`, 265 e.g. "<C-Z>" for CTRL-Z. 266 ++type={pty} (MS-Windows only): Use {pty} as the 267 virtual console. See 'termwintype' 268 for the values. 269 ++api={expr} Permit the function name starting with 270 {expr} to be called as |terminal-api| 271 function. If {expr} is empty then no 272 function can be called. 273 274 If you want to use more options use the |term_start()| 275 function. 276 If you want to split the window vertically, use: > 277 :vertical terminal 278< Or short: > 279 :vert ter 280 281When the buffer associated with the terminal is forcibly unloaded or wiped out 282the job is killed, similar to calling `job_stop(job, "kill")` . 283Closing the window normally results in |E947|. When a kill method was set 284with "++kill={how}" or |term_setkill()| then closing the window will use that 285way to kill or interrupt the job. For example: > 286 :term ++kill=term tail -f /tmp/log 287 288So long as the job is running the window behaves like it contains a modified 289buffer. Trying to close the window with `CTRL-W :quit` fails. When using 290`CTRL-W :quit!` the job is ended. The text in the window is lost. The buffer 291still exists, but getting it in a window with `:buffer` will show an empty 292buffer. 293 294Trying to close the window with `CTRL-W :close` also fails. Using 295`CTRL-W :close!` will close the window and make the buffer hidden. 296 297You can use `CTRL-W :hide` to close the terminal window and make the buffer 298hidden, the job keeps running. The `:buffer` command can be used to turn the 299current window into a terminal window. If there are unsaved changes this 300fails, use ! to force, as usual. 301 302 *terminal-close* 303When the terminal window is closed, e.g. when the shell exits and "++close" 304argument was used, and this is the last normal Vim window, then Vim will exit. 305This is like using |:quit| in a normal window. Help and preview windows are 306not counted. 307 308To have a background job run without a window, and open the window when it's 309done, use options like this: > 310 :term ++hidden ++open make 311Note that the window will open at an unexpected moment, this will interrupt 312what you are doing. 313 314 *E947* *E948* 315So long as the job is running, the buffer is considered modified and Vim 316cannot be quit easily, see |abandon|. 317 318When the job has finished and no changes were made to the buffer: closing the 319window will wipe out the buffer. 320 321Before changes can be made to a terminal buffer, the 'modifiable' option must 322be set. This is only possible when the job has finished. At the first change 323the buffer will become a normal buffer and the highlighting is removed. 324You may want to change the buffer name with |:file| to be able to write, since 325the buffer name will still be set to the command. 326 327 328Resizing ~ 329 *terminal-resizing* 330The size of the terminal can be in one of three modes: 331 3321. The 'termwinsize' option is empty: The terminal size follows the window 333 size. The minimal size is 2 screen lines with 10 cells. 334 3352. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number 336 of screen rows and "cols" is the minimal number of cells. 337 3383. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower 339 case). The terminal size is fixed to the specified number of screen lines 340 and cells. If the window is bigger there will be unused empty space. 341 342If the window is smaller than the terminal size, only part of the terminal can 343be seen (the lower-left part). 344 345The |term_getsize()| function can be used to get the current size of the 346terminal. |term_setsize()| can be used only when in the first or second mode, 347not when 'termwinsize' is "rowsXcols". 348 349 350Terminal-Job and Terminal-Normal mode ~ 351 *Terminal-mode* *Terminal-Job* 352When the job is running the contents of the terminal is under control of the 353job. That includes the cursor position. Typed keys are sent to the job. 354The terminal contents can change at any time. This is called Terminal-Job 355mode. 356 357Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the 358contents of the terminal window is under control of Vim, the job output is 359suspended. CTRL-\ CTRL-N does the same. 360 361Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by 362|term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are. 363 364It is not possible to enter Insert mode from Terminal-Job mode. 365 366 *Terminal-Normal* *E946* 367In Terminal-Normal mode you can move the cursor around with the usual Vim 368commands, Visually mark text, yank text, etc. But you cannot change the 369contents of the buffer. The commands that would start insert mode, such as 370'i' and 'a', return to Terminal-Job mode. The window will be updated to show 371the contents of the terminal. |:startinsert| is ineffective. 372 373In Terminal-Normal mode the statusline and window title show "(Terminal)". If 374the job ends while in Terminal-Normal mode this changes to 375"(Terminal-finished)". 376 377When the job outputs lines in the terminal, such that the contents scrolls off 378the top, those lines are remembered and can be seen in Terminal-Normal mode. 379The number of lines is limited by the 'termwinscroll' option. When going over 380this limit, the first 10% of the scrolled lines are deleted and are lost. 381 382 383Cursor style ~ 384 *terminal-cursor-style* 385By default the cursor in the terminal window uses a not blinking block. The 386normal xterm escape sequences can be used to change the blinking state and the 387shape. Once focus leaves the terminal window Vim will restore the original 388cursor. 389 390An exception is when xterm is started with the "-bc" argument, or another way 391that causes the cursor to blink. This actually means that the blinking flag 392is inverted. Since Vim cannot detect this, the terminal window cursor 393blinking will also be inverted. 394 395 396Session ~ 397 *terminal-session* 398A terminal window will be restored when using a session file, if possible and 399wanted. 400 401If "terminal" was removed from 'sessionoptions' then no terminal windows will 402be restored. 403 404If the job in the terminal was finished the window will not be restored. 405 406If the terminal can be restored, the command that was used to open it will be 407used again. To change this use the |term_setrestore()| function. This can 408also be used to not restore a specific terminal by setting the command to 409"NONE". 410 411 412Special keys ~ 413 *terminal-special-keys* 414Since the terminal emulator simulates an xterm, only escape sequences that 415both Vim and xterm recognize will be available in the terminal window. If you 416want to pass on other escape sequences to the job running in the terminal you 417need to set up forwarding. Example: > 418 tmap <expr> <Esc>]b SendToTerm("\<Esc>]b") 419 func SendToTerm(what) 420 call term_sendkeys('', a:what) 421 return '' 422 endfunc 423 424 425Unix ~ 426 *terminal-unix* 427On Unix a pty is used to make it possible to run all kinds of commands. You 428can even run Vim in the terminal! That's used for debugging, see below. 429 430Environment variables are used to pass information to the running job: 431 TERM the name of the terminal, from the 'term' option or 432 $TERM in the GUI; falls back to "xterm" if it does not 433 start with "xterm" 434 ROWS number of rows in the terminal initially 435 LINES same as ROWS 436 COLUMNS number of columns in the terminal initially 437 COLORS number of colors, 't_Co' (256*256*256 in the GUI) 438 VIM_SERVERNAME v:servername 439 VIM_TERMINAL v:version 440 441 442MS-Windows ~ 443 *terminal-ms-windows* 444On MS-Windows winpty is used to make it possible to run all kind of commands. 445Obviously, they must be commands that run in a terminal, not open their own 446window. 447 448You need the following two files from winpty: 449 450 winpty.dll 451 winpty-agent.exe 452 453You can download them from the following page: 454 455 https://github.com/rprichard/winpty 456 457Just put the files somewhere in your PATH. You can set the 'winptydll' option 458to point to the right file, if needed. If you have both the 32-bit and 64-bit 459version, rename to winpty32.dll and winpty64.dll to match the way Vim was 460build. 461 *ConPTY* *E982* 462On more recent versions of MS-Windows 10 (beginning with the "October 2018 463Update"), winpty is no longer required. On those versions, |:terminal| will use 464Windows' built-in support for hosting terminal applications, "ConPTY". When 465ConPTY is in use, there may be rendering artifacts regarding ambiguous-width 466characters. If you encounter any such issues, install "winpty". Until the 467ConPTY problems have been fixed "winpty" will be preferred. 468 469Environment variables are used to pass information to the running job: 470 VIM_SERVERNAME v:servername 471 472 473============================================================================== 4742. Terminal functions *terminal-function-details* 475 476 *term_dumpdiff()* 477term_dumpdiff({filename}, {filename} [, {options}]) 478 Open a new window displaying the difference between the two 479 files. The files must have been created with 480 |term_dumpwrite()|. 481 Returns the buffer number or zero when the diff fails. 482 Also see |terminal-diff|. 483 NOTE: this does not work with double-width characters yet. 484 485 The top part of the buffer contains the contents of the first 486 file, the bottom part of the buffer contains the contents of 487 the second file. The middle part shows the differences. 488 The parts are separated by a line of equals. 489 490 If the {options} argument is present, it must be a Dict with 491 these possible members: 492 "term_name" name to use for the buffer name, instead 493 of the first file name. 494 "term_rows" vertical size to use for the terminal, 495 instead of using 'termwinsize', but 496 respecting the minimal size 497 "term_cols" horizontal size to use for the terminal, 498 instead of using 'termwinsize', but 499 respecting the minimal size 500 "vertical" split the window vertically 501 "curwin" use the current window, do not split the 502 window; fails if the current buffer 503 cannot be |abandon|ed 504 "bufnr" do not create a new buffer, use the 505 existing buffer "bufnr". This buffer 506 must have been previously created with 507 term_dumpdiff() or term_dumpload() and 508 visible in a window. 509 "norestore" do not add the terminal window to a 510 session file 511 512 Each character in the middle part indicates a difference. If 513 there are multiple differences only the first in this list is 514 used: 515 X different character 516 w different width 517 f different foreground color 518 b different background color 519 a different attribute 520 + missing position in first file 521 - missing position in second file 522 > cursor position in first file, not in second 523 < cursor position in second file, not in first 524 525 Using the "s" key the top and bottom parts are swapped. This 526 makes it easy to spot a difference. 527 528 Can also be used as a |method|: > 529 GetFilename()->term_dumpdiff(otherfile) 530< 531 *term_dumpload()* 532term_dumpload({filename} [, {options}]) 533 Open a new window displaying the contents of {filename} 534 The file must have been created with |term_dumpwrite()|. 535 Returns the buffer number or zero when it fails. 536 Also see |terminal-diff|. 537 538 For {options} see |term_dumpdiff()|. 539 540 Can also be used as a |method|: > 541 GetFilename()->term_dumpload() 542< 543 *term_dumpwrite()* 544term_dumpwrite({buf}, {filename} [, {options}]) 545 Dump the contents of the terminal screen of {buf} in the file 546 {filename}. This uses a format that can be used with 547 |term_dumpload()| and |term_dumpdiff()|. 548 If the job in the terminal already finished an error is given: 549 *E958* 550 If {filename} already exists an error is given: *E953* 551 Also see |terminal-diff|. 552 553 {options} is a dictionary with these optional entries: 554 "rows" maximum number of rows to dump 555 "columns" maximum number of columns to dump 556 557 Can also be used as a |method|, the base is used for the file 558 name: > 559 GetFilename()->term_dumpwrite(bufnr) 560 561term_getaltscreen({buf}) *term_getaltscreen()* 562 Returns 1 if the terminal of {buf} is using the alternate 563 screen. 564 {buf} is used as with |term_getsize()|. 565 566 Can also be used as a |method|: > 567 GetBufnr()->term_getaltscreen() 568 569 570term_getansicolors({buf}) *term_getansicolors()* 571 Get the ANSI color palette in use by terminal {buf}. 572 Returns a List of length 16 where each element is a String 573 representing a color in hexadecimal "#rrggbb" format. 574 Also see |term_setansicolors()| and |g:terminal_ansi_colors|. 575 If neither was used returns the default colors. 576 577 {buf} is used as with |term_getsize()|. If the buffer does not 578 exist or is not a terminal window, an empty list is returned. 579 580 Can also be used as a |method|: > 581 GetBufnr()->term_getansicolors() 582 583< {only available when compiled with GUI enabled and/or the 584 |+termguicolors| feature} 585 586term_getattr({attr}, {what}) *term_getattr()* 587 Given {attr}, a value returned by term_scrape() in the "attr" 588 item, return whether {what} is on. {what} can be one of: 589 bold 590 italic 591 underline 592 strike 593 reverse 594 595 Can also be used as a |method|: > 596 GetAttr()->term_getattr() 597 598 599term_getcursor({buf}) *term_getcursor()* 600 Get the cursor position of terminal {buf}. Returns a list with 601 two numbers and a dictionary: [row, col, dict]. 602 603 "row" and "col" are one based, the first screen cell is row 604 1, column 1. This is the cursor position of the terminal 605 itself, not of the Vim window. 606 607 "dict" can have these members: 608 "visible" one when the cursor is visible, zero when it 609 is hidden. 610 "blink" one when the cursor is blinking, zero when it 611 is not blinking. 612 "shape" 1 for a block cursor, 2 for underline and 3 613 for a vertical bar. 614 "color" color of the cursor, e.g. "green" 615 616 {buf} must be the buffer number of a terminal window. If the 617 buffer does not exist or is not a terminal window, an empty 618 list is returned. 619 620 Can also be used as a |method|: > 621 GetBufnr()->term_getcursor() 622 623term_getjob({buf}) *term_getjob()* 624 Get the Job associated with terminal window {buf}. 625 {buf} is used as with |term_getsize()|. 626 Returns |v:null| when there is no job. 627 628 Can also be used as a |method|: > 629 GetBufnr()->term_getjob() 630 631 632term_getline({buf}, {row}) *term_getline()* 633 Get a line of text from the terminal window of {buf}. 634 {buf} is used as with |term_getsize()|. 635 636 The first line has {row} one. When {row} is "." the cursor 637 line is used. When {row} is invalid an empty string is 638 returned. 639 640 To get attributes of each character use |term_scrape()|. 641 642 Can also be used as a |method|: > 643 GetBufnr()->term_getline(row) 644 645 646term_getscrolled({buf}) *term_getscrolled()* 647 Return the number of lines that scrolled to above the top of 648 terminal {buf}. This is the offset between the row number 649 used for |term_getline()| and |getline()|, so that: > 650 term_getline(buf, N) 651< is equal to: > 652 getline(N + term_getscrolled(buf)) 653< (if that line exists). 654 655 {buf} is used as with |term_getsize()|. 656 657 Can also be used as a |method|: > 658 GetBufnr()->term_getscrolled() 659 660 661term_getsize({buf}) *term_getsize()* 662 Get the size of terminal {buf}. Returns a list with two 663 numbers: [rows, cols]. This is the size of the terminal, not 664 the window containing the terminal. 665 666 {buf} must be the buffer number of a terminal window. Use an 667 empty string for the current buffer. If the buffer does not 668 exist or is not a terminal window, an empty list is returned. 669 670 Can also be used as a |method|: > 671 GetBufnr()->term_getsize() 672 673 674term_getstatus({buf}) *term_getstatus()* 675 Get the status of terminal {buf}. This returns a String with 676 a comma separated list of these items: 677 running job is running 678 finished job has finished 679 normal in Terminal-Normal mode 680 One of "running" or "finished" is always present. 681 682 {buf} must be the buffer number of a terminal window. If the 683 buffer does not exist or is not a terminal window, an empty 684 string is returned. 685 686 Can also be used as a |method|: > 687 GetBufnr()->term_getstatus() 688 689 690term_gettitle({buf}) *term_gettitle()* 691 Get the title of terminal {buf}. This is the title that the 692 job in the terminal has set. 693 694 {buf} must be the buffer number of a terminal window. If the 695 buffer does not exist or is not a terminal window, an empty 696 string is returned. 697 698 Can also be used as a |method|: > 699 GetBufnr()->term_gettitle() 700 701 702term_gettty({buf} [, {input}]) *term_gettty()* 703 Get the name of the controlling terminal associated with 704 terminal window {buf}. {buf} is used as with |term_getsize()|. 705 706 When {input} is omitted or 0, return the name for writing 707 (stdout). When {input} is 1 return the name for reading 708 (stdin). On UNIX, both return same name. 709 710 Can also be used as a |method|: > 711 GetBufnr()->term_gettty() 712 713 714term_list() *term_list()* 715 Return a list with the buffer numbers of all buffers for 716 terminal windows. 717 718 719term_scrape({buf}, {row}) *term_scrape()* 720 Get the contents of {row} of terminal screen of {buf}. 721 For {buf} see |term_getsize()|. 722 723 The first line has {row} one. When {row} is "." the cursor 724 line is used. When {row} is invalid an empty string is 725 returned. 726 727 Return a List containing a Dict for each screen cell: 728 "chars" character(s) at the cell 729 "fg" foreground color as #rrggbb 730 "bg" background color as #rrggbb 731 "attr" attributes of the cell, use |term_getattr()| 732 to get the individual flags 733 "width" cell width: 1 or 2 734 For a double-width cell there is one item, thus the list can 735 be shorter than the width of the terminal. 736 737 Can also be used as a |method|: > 738 GetBufnr()->term_scrape(row) 739 740 741term_sendkeys({buf}, {keys}) *term_sendkeys()* 742 Send keystrokes {keys} to terminal {buf}. 743 {buf} is used as with |term_getsize()|. 744 745 {keys} are translated as key sequences. For example, "\<c-x>" 746 means the character CTRL-X. 747 748 Can also be used as a |method|: > 749 GetBufnr()->term_sendkeys(keys) 750 751 752term_setansicolors({buf}, {colors}) *term_setansicolors()* 753 Set the ANSI color palette used by terminal {buf}. 754 {colors} must be a List of 16 valid color names or hexadecimal 755 color codes, like those accepted by |highlight-guifg|. 756 Also see |term_getansicolors()| and |g:terminal_ansi_colors|. 757 758 The colors normally are: 759 0 black 760 1 dark red 761 2 dark green 762 3 brown 763 4 dark blue 764 5 dark magenta 765 6 dark cyan 766 7 light grey 767 8 dark grey 768 9 red 769 10 green 770 11 yellow 771 12 blue 772 13 magenta 773 14 cyan 774 15 white 775 776 These colors are used in the GUI and in the terminal when 777 'termguicolors' is set. When not using GUI colors (GUI mode 778 or 'termguicolors'), the terminal window always uses the 16 779 ANSI colors of the underlying terminal. 780 781 Can also be used as a |method|: > 782 GetBufnr()->term_setansicolors(colors) 783 784< {only available with GUI enabled and/or the |+termguicolors| 785 feature} 786 787 788term_setapi({buf}, {expr}) *term_setapi()* 789 Set the function name prefix to be used for the |terminal-api| 790 function in terminal {buf}. For example: > 791 :call term_setapi(buf, "Myapi_") 792 :call term_setapi(buf, "") 793< 794 The default is "Tapi_". When {expr} is an empty string then 795 no |terminal-api| function can be used for {buf}. 796 797 When used as a method the base is used for {buf}: > 798 GetBufnr()->term_setapi({expr}) 799 800 801term_setkill({buf}, {how}) *term_setkill()* 802 When exiting Vim or trying to close the terminal window in 803 another way, {how} defines whether the job in the terminal can 804 be stopped. 805 When {how} is empty (the default), the job will not be 806 stopped, trying to exit will result in |E947|. 807 Otherwise, {how} specifies what signal to send to the job. 808 See |job_stop()| for the values. 809 810 After sending the signal Vim will wait for up to a second to 811 check that the job actually stopped. 812 813 Can also be used as a |method|: > 814 GetBufnr()->term_setkill(how) 815 816 817term_setrestore({buf}, {command}) *term_setrestore()* 818 Set the command to write in a session file to restore the job 819 in this terminal. The line written in the session file is: > 820 terminal ++curwin ++cols=%d ++rows=%d {command} 821< Make sure to escape the command properly. 822 823 Use an empty {command} to run 'shell'. 824 Use "NONE" to not restore this window. 825 826 Can also be used as a |method|: > 827 GetBufnr()->term_setrestore(command) 828 829 830term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955* 831 Set the size of terminal {buf}. The size of the window 832 containing the terminal will also be adjusted, if possible. 833 If {rows} or {cols} is zero or negative, that dimension is not 834 changed. 835 836 {buf} must be the buffer number of a terminal window. Use an 837 empty string for the current buffer. If the buffer does not 838 exist or is not a terminal window, an error is given. 839 840 Can also be used as a |method|: > 841 GetBufnr()->term_setsize(rows, cols) 842 843 844term_start({cmd} [, {options}]) *term_start()* 845 Open a terminal window and run {cmd} in it. 846 847 {cmd} can be a string or a List, like with |job_start()|. The 848 string "NONE" can be used to open a terminal window without 849 starting a job, the pty of the terminal can be used by a 850 command like gdb. 851 852 Returns the buffer number of the terminal window. If {cmd} 853 cannot be executed the window does open and shows an error 854 message. 855 If opening the window fails zero is returned. 856 857 {options} are similar to what is used for |job_start()|, see 858 |job-options|. However, not all options can be used. These 859 are supported: 860 all timeout options 861 "stoponexit", "cwd", "env" 862 "callback", "out_cb", "err_cb", "exit_cb", "close_cb" 863 "in_io", "in_top", "in_bot", "in_name", "in_buf" 864 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg" 865 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg" 866 However, at least one of stdin, stdout or stderr must be 867 connected to the terminal. When I/O is connected to the 868 terminal then the callback function for that part is not used. 869 870 There are extra options: 871 "term_name" name to use for the buffer name, instead 872 of the command name. 873 "term_rows" vertical size to use for the terminal, 874 instead of using 'termwinsize'; valid 875 range is from zero to 1000 876 "term_cols" horizontal size to use for the terminal, 877 instead of using 'termwinsize' 878 "vertical" split the window vertically; note that 879 other window position can be defined with 880 command modifiers, such as |:belowright|. 881 "curwin" use the current window, do not split the 882 window; fails if the current buffer 883 cannot be |abandon|ed 884 "hidden" do not open a window 885 "norestore" do not add the terminal window to a 886 session file 887 "term_kill" what to do when trying to close the 888 terminal window, see |term_setkill()| 889 "term_finish" What to do when the job is finished: 890 "close": close any windows 891 "open": open window if needed 892 Note that "open" can be interruptive. 893 See |term++close| and |term++open|. 894 "term_opencmd" command to use for opening the window when 895 "open" is used for "term_finish"; must 896 have "%d" where the buffer number goes, 897 e.g. "10split|buffer %d"; when not 898 specified "botright sbuf %d" is used 899 "term_highlight" highlight group to use instead of 900 "Terminal" 901 "eof_chars" Text to send after all buffer lines were 902 written to the terminal. When not set 903 CTRL-D is used on MS-Windows. For Python 904 use CTRL-Z or "exit()". For a shell use 905 "exit". A CR is always added. 906 "ansi_colors" A list of 16 color names or hex codes 907 defining the ANSI palette used in GUI 908 color modes. See |g:terminal_ansi_colors|. 909 "tty_type" (MS-Windows only): Specify which pty to 910 use. See 'termwintype' for the values. 911 "term_api" function name prefix for the 912 |terminal-api| function. See 913 |term_setapi()|. 914 915 Can also be used as a |method|: > 916 GetCommand()->term_start() 917 918 919term_wait({buf} [, {time}]) *term_wait()* 920 Wait for pending updates of {buf} to be handled. 921 {buf} is used as with |term_getsize()|. 922 {time} is how long to wait for updates to arrive in msec. If 923 not set then 10 msec will be used. 924 925 Can also be used as a |method|: > 926 GetBufnr()->term_wait() 927 928============================================================================== 9293. Terminal communication *terminal-communication* 930 931There are several ways to communicate with the job running in a terminal: 932- Use |term_sendkeys()| to send text and escape sequences from Vim to the job. 933- Use the JSON API to send encoded commands from the job to Vim. 934- Use the |client-server| mechanism. This works on machines with an X server 935 and on MS-Windows. 936 937 938Vim to job: term_sendkeys() ~ 939 *terminal-to-job* 940This allows for remote controlling the job running in the terminal. It is a 941one-way mechanism. The job can update the display to signal back to Vim. 942For example, if a shell is running in a terminal, you can do: > 943 call term_sendkeys(buf, "ls *.java\<CR>") 944 945This requires for the job to be in the right state where it will do the right 946thing when receiving the keys. For the above example, the shell must be 947waiting for a command to be typed. 948 949For a job that was written for the purpose, you can use the JSON API escape 950sequence in the other direction. E.g.: > 951 call term_sendkeys(buf, "\<Esc>]51;["response"]\x07") 952 953 954Job to Vim: JSON API ~ 955 *terminal-api* 956The job can send JSON to Vim, using a special escape sequence. The JSON 957encodes a command that Vim understands. Example of such a message: > 958 <Esc>]51;["drop", "README.md"]<07> 959 960The body is always a list, making it easy to find the end: ]<07>. 961The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is 962similar to what we are doing here. 963 964Currently supported commands: 965 966 call {funcname} {argument} 967 968 Call a user defined function with {argument}. 969 The function is called with two arguments: the buffer number 970 of the terminal and {argument}, the decoded JSON argument. 971 By default, the function name must start with "Tapi_" to avoid 972 accidentally calling a function not meant to be used for the 973 terminal API. This can be changed with |term_setapi()|. 974 The user function should sanity check the argument. 975 The function can use |term_sendkeys()| to send back a reply. 976 Example in JSON: > 977 ["call", "Tapi_Impression", ["play", 14]] 978< Calls a function defined like this: > 979 function Tapi_Impression(bufnum, arglist) 980 if len(a:arglist) == 2 981 echomsg "impression " . a:arglist[0] 982 echomsg "count " . a:arglist[1] 983 endif 984 endfunc 985< Output from `:echo` may be erased by a redraw, use `:echomsg` 986 to be able to see it with `:messages`. 987 988 drop {filename} [options] 989 990 Let Vim open a file, like the `:drop` command. If {filename} 991 is already open in a window, switch to that window. Otherwise 992 open a new window to edit {filename}. 993 Note that both the job and Vim may change the current 994 directory, thus it's best to use the full path. 995 996 [options] is only used when opening a new window. If present, 997 it must be a Dict. Similarly to |++opt|, these entries are 998 recognized: 999 "ff" file format: "dos", "mac" or "unix" 1000 "fileformat" idem 1001 "enc" overrides 'fileencoding' 1002 "encoding" idem 1003 "bin" sets 'binary' 1004 "binary" idem 1005 "nobin" resets 'binary' 1006 "nobinary" idem 1007 "bad" specifies behavior for bad characters, see 1008 |++bad| 1009 1010 Example in JSON: > 1011 ["drop", "path/file.txt", {"ff": "dos"}] 1012 1013A trick to have Vim send this escape sequence: > 1014 exe "set t_ts=\<Esc>]51; t_fs=\x07" 1015 let &titlestring = '["call","Tapi_TryThis",["hello",123]]' 1016 redraw 1017 set t_ts& t_fs& 1018 1019Rationale: Why not allow for any command or expression? Because that might 1020create a security problem. 1021 1022 1023Using the client-server feature ~ 1024 *terminal-client-server* 1025This only works when v:servername is not empty. If needed you can set it, 1026before opening the terminal, with: > 1027 call remote_startserver('vim-server') 1028 1029$VIM_SERVERNAME is set in the terminal to pass on the server name. 1030 1031In the job you can then do something like: > 1032 vim --servername $VIM_SERVERNAME --remote +123 some_file.c 1033This will open the file "some_file.c" and put the cursor on line 123. 1034 1035============================================================================== 10364. Remote testing *terminal-testing* 1037 1038Most Vim tests execute a script inside Vim. For some tests this does not 1039work, running the test interferes with the code being tested. To avoid this 1040Vim is executed in a terminal window. The test sends keystrokes to it and 1041inspects the resulting screen state. 1042 1043Functions ~ 1044 1045|term_sendkeys()| send keystrokes to a terminal (not subject to tmap) 1046|term_wait()| wait for screen to be updated 1047|term_scrape()| inspect terminal screen 1048 1049 1050============================================================================== 10515. Diffing screen dumps *terminal-diff* 1052 1053In some cases it can be bothersome to test that Vim displays the right 1054characters on the screen. E.g. with syntax highlighting. To make this 1055simpler it is possible to take a screen dump of a terminal and compare it to 1056an expected screen dump. 1057 1058Vim uses the window size, text, color and other attributes as displayed. The 1059Vim screen size, font and other properties do not matter. Therefore this 1060mechanism is portable across systems. A conventional screenshot would reflect 1061all differences, including font size and family. 1062 1063 1064Writing a screen dump test for Vim ~ 1065 *terminal-dumptest* 1066For an example see the Test_syntax_c() function in 1067src/testdir/test_syntax.vim. The main parts are: 1068- Write a file you want to test with. This is useful for testing syntax 1069 highlighting. You can also start Vim with an empty buffer. 1070- Run Vim in a terminal with a specific size. The default is 20 lines of 75 1071 characters. This makes sure the dump is always this size. The function 1072 RunVimInTerminal() takes care of this. Pass it the arguments for the Vim 1073 command. 1074- Send any commands to Vim using |term_sendkeys()|. For example: > 1075 call term_sendkeys(buf, ":echo &lines &columns\<CR>") 1076- Check that the screen is now in the expected state, using 1077 VerifyScreenDump(). This expects the reference screen dump to be in the 1078 src/testdir/dumps/ directory. Pass the name without ".dump". It is 1079 recommended to use the name of the test function and a sequence number, so 1080 that we know what test is using the file. 1081- Repeat sending commands and checking the state. 1082- Finally stop Vim by calling StopVimInTerminal(). 1083 1084The first time you do this you won't have a screen dump yet. Create an empty 1085file for now, e.g.: > 1086 touch src/testdir/dumps/Test_function_name_01.dump 1087 1088The test will then fail, giving you the command to compare the reference dump 1089and the failed dump, e.g.: > 1090 call term_dumpdiff("failed/Test_func.dump", "dumps/Test_func.dump") 1091 1092Use this command in Vim, with the current directory set to src/testdir. 1093Once you are satisfied with the test, move the failed dump in place of the 1094reference: > 1095 :!mv failed/Test_func.dump dumps/Test_func.dump 1096 1097 1098Creating a screen dump ~ 1099 *terminal-screendump* 1100 1101To create the screen dump, run Vim (or any other program) in a terminal and 1102make it show the desired state. Then use the |term_dumpwrite()| function to 1103create a screen dump file. For example: > 1104 :call term_dumpwrite(77, "mysyntax.dump") 1105 1106Here "77" is the buffer number of the terminal. Use `:ls!` to see it. 1107 1108You can view the screen dump with |term_dumpload()|: > 1109 :call term_dumpload("mysyntax.dump") 1110 1111To verify that Vim still shows exactly the same screen, run Vim again with 1112exactly the same way to show the desired state. Then create a screen dump 1113again, using a different file name: > 1114 :call term_dumpwrite(88, "test.dump") 1115 1116To assert that the files are exactly the same use |assert_equalfile()|: > 1117 call assert_equalfile("mysyntax.dump", "test.dump") 1118 1119If there are differences then v:errors will contain the error message. 1120 1121 1122Comparing screen dumps ~ 1123 *terminal-diffscreendump* 1124 1125|assert_equalfile()| does not make it easy to see what is different. 1126To spot the problem use |term_dumpdiff()|: > 1127 call term_dumpdiff("mysyntax.dump", "test.dump") 1128 1129This will open a window consisting of three parts: 11301. The contents of the first dump 11312. The difference between the first and second dump 11323. The contents of the second dump 1133 1134You can usually see what differs in the second part. Use the 'ruler' to 1135relate it to the position in the first or second dump. Letters indicate the 1136kind of difference: 1137 X different character 1138 > cursor in first but not in second 1139 < cursor in second but not in first 1140 w character width differs (single vs double width) 1141 f foreground color differs 1142 b background color differs 1143 a attribute differs (bold, underline, reverse, etc.) 1144 ? character missing in both 1145 + character missing in first 1146 - character missing in second 1147 1148Alternatively, press "s" to swap the first and second dump. Do this several 1149times so that you can spot the difference in the context of the text. 1150 1151============================================================================== 11526. Debugging *terminal-debug* *terminal-debugger* 1153 1154The Terminal debugging plugin can be used to debug a program with gdb and view 1155the source code in a Vim window. Since this is completely contained inside 1156Vim this also works remotely over an ssh connection. 1157 1158When the |+terminal| feature is missing, the plugin will use the "prompt" 1159buffer type, if possible. The running program will then use a newly opened 1160terminal window. See |termdebug-prompt| below for details. 1161 1162 1163Starting ~ 1164 *termdebug-starting* 1165Load the plugin with this command: > 1166 packadd termdebug 1167< *:Termdebug* 1168To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the 1169command name, for example: > 1170 :Termdebug vim 1171 1172This opens two windows: 1173 1174gdb window A terminal window in which "gdb vim" is executed. Here you 1175 can directly interact with gdb. The buffer name is "!gdb". 1176 1177program window A terminal window for the executed program. When "run" is 1178 used in gdb the program I/O will happen in this window, so 1179 that it does not interfere with controlling gdb. The buffer 1180 name is "gdb program". 1181 1182The current window is used to show the source code. When gdb pauses the 1183source file location will be displayed, if possible. A sign is used to 1184highlight the current position, using highlight group debugPC. 1185 1186If the buffer in the current window is modified, another window will be opened 1187to display the current gdb position. You can use `:Winbar` to add a window 1188toolbar there. 1189 1190Focus the terminal of the executed program to interact with it. This works 1191the same as any command running in a terminal window. 1192 1193When the debugger ends, typically by typing "quit" in the gdb window, the two 1194opened windows are closed. 1195 1196Only one debugger can be active at a time. 1197 *:TermdebugCommand* 1198If you want to give specific commands to the command being debugged, you can 1199use the `:TermdebugCommand` command followed by the command name and 1200additional parameters. > 1201 :TermdebugCommand vim --clean -c ':set nu' 1202 1203Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang 1204argument to start the command right away, without pausing at the gdb window 1205(and cursor will be in the debugged window). For example: > 1206 :TermdebugCommand! vim --clean 1207 1208To attach gdb to an already running executable or use a core file, pass extra 1209arguments. E.g.: > 1210 :Termdebug vim core 1211 :Termdebug vim 98343 1212 1213If no argument is given, you'll end up in a gdb window, in which you need to 1214specify which command to run using e.g. the gdb `file` command. 1215 1216 1217Example session ~ 1218 *termdebug-example* 1219Start in the Vim "src" directory and build Vim: > 1220 % make 1221Make sure that debug symbols are present, usually that means that $CFLAGS 1222includes "-g". 1223 1224Start Vim: > 1225 % ./vim 1226 1227Load the termdebug plugin and start debugging Vim: > 1228 :packadd termdebug 1229 :Termdebug vim 1230You should now have three windows: 1231 source - where you started, has a window toolbar with buttons 1232 gdb - you can type gdb commands here 1233 program - the executed program will use this window 1234 1235You can use CTRL-W CTRL-W or the mouse to move focus between windows. 1236Put focus on the gdb window and type: > 1237 break ex_help 1238 run 1239Vim will start running in the program window. Put focus there and type: > 1240 :help gui 1241Gdb will run into the ex_help breakpoint. The source window now shows the 1242ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the 1243breakpoint was set. The line where the debugger stopped is highlighted. You 1244can now step through the program. Let's use the mouse: click on the "Next" 1245button in the window toolbar. You will see the highlighting move as the 1246debugger executes a line of source code. 1247 1248Click "Next" a few times until the for loop is highlighted. Put the cursor on 1249the end of "eap->arg", then click "Eval" in the toolbar. You will see this 1250displayed: 1251 "eap->arg": 0x555555e68855 "gui" ~ 1252This way you can inspect the value of local variables. You can also focus the 1253gdb window and use a "print" command, e.g.: > 1254 print *eap 1255If mouse pointer movements are working, Vim will also show a balloon when the 1256mouse rests on text that can be evaluated by gdb. 1257 1258Now go back to the source window and put the cursor on the first line after 1259the for loop, then type: > 1260 :Break 1261You will see a ">>" marker appear, this indicates the new breakpoint. Now 1262click "Cont" in the toolbar and the code until the breakpoint will be 1263executed. 1264 1265You can type more advanced commands in the gdb window. For example, type: > 1266 watch curbuf 1267Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution 1268will now continue until the value of "curbuf" changes, which is in do_ecmd(). 1269To remove this watchpoint again type in the gdb window: > 1270 delete 3 1271 1272You can see the stack by typing in the gdb window: > 1273 where 1274Move through the stack frames, e.g. with: > 1275 frame 3 1276The source window will show the code, at the point where the call was made to 1277a deeper level. 1278 1279 1280Stepping through code ~ 1281 *termdebug-stepping* 1282Put focus on the gdb window to type commands there. Some common ones are: 1283- CTRL-C interrupt the program 1284- next execute the current line and stop at the next line 1285- step execute the current line and stop at the next statement, 1286 entering functions 1287- finish execute until leaving the current function 1288- where show the stack 1289- frame N go to the Nth stack frame 1290- continue continue execution 1291 1292 *:Run* *:Arguments* 1293In the window showing the source code these commands can be used to control 1294gdb: 1295 `:Run` [args] run the program with [args] or the previous arguments 1296 `:Arguments` {args} set arguments for the next `:Run` 1297 1298 *:Break* set a breakpoint at the cursor position 1299 :Break {position} 1300 set a breakpoint at the specified position 1301 *:Clear* delete the breakpoint at the cursor position 1302 1303 *:Step* execute the gdb "step" command 1304 *:Over* execute the gdb "next" command (`:Next` is a Vim command) 1305 *:Finish* execute the gdb "finish" command 1306 *:Continue* execute the gdb "continue" command 1307 *:Stop* interrupt the program 1308 1309If 'mouse' is set the plugin adds a window toolbar with these entries: 1310 Step `:Step` 1311 Next `:Over` 1312 Finish `:Finish` 1313 Cont `:Continue` 1314 Stop `:Stop` 1315 Eval `:Evaluate` 1316This way you can use the mouse to perform the most common commands. You need 1317to have the 'mouse' option set to enable mouse clicks. 1318 *:Winbar* 1319You can add the window toolbar in other windows you open with: > 1320 :Winbar 1321 1322If gdb stops at a source line and there is no window currently showing the 1323source code, a new window will be created for the source code. This also 1324happens if the buffer in the source code window has been modified and can't be 1325abandoned. 1326 1327Gdb gives each breakpoint a number. In Vim the number shows up in the sign 1328column, with a red background. You can use these gdb commands: 1329- info break list breakpoints 1330- delete N delete breakpoint N 1331You can also use the `:Clear` command if the cursor is in the line with the 1332breakpoint, or use the "Clear breakpoint" right-click menu entry. 1333 1334 1335Inspecting variables ~ 1336 *termdebug-variables* *:Evaluate* 1337 `:Evaluate` evaluate the expression under the cursor 1338 `K` same (see |termdebug_map_K| to disable) 1339 `:Evaluate` {expr} evaluate {expr} 1340 `:'<,'>Evaluate` evaluate the Visually selected text 1341 1342This is similar to using "print" in the gdb window. 1343You can usually shorten `:Evaluate` to `:Ev`. 1344 1345 1346Other commands ~ 1347 *termdebug-commands* 1348 *:Gdb* jump to the gdb window 1349 *:Program* jump to the window with the running program 1350 *:Source* jump to the window with the source code, create it if there 1351 isn't one 1352 *:Asm* jump to the window with the disassembly, create it if there 1353 isn't one 1354 1355Events ~ 1356 *termdebug-events* 1357Four autocommands can be used: > 1358 au User TermdebugStartPre echomsg 'debugging starting' 1359 au User TermdebugStartPost echomsg 'debugging started' 1360 au User TermdebugStopPre echomsg 'debugging stopping' 1361 au User TermdebugStopPost echomsg 'debugging stopped' 1362< 1363 *TermdebugStartPre* 1364TermdebugStartPre Before starting debugging. 1365 Not triggered if the debugger is already 1366 running or |g:termdebugger| cannot be 1367 executed. 1368 *TermdebugStartPost* 1369TermdebugStartPost After debugging has initialized. 1370 If a "!" bang is passed to `:Termdebug` or 1371 `:TermdebugCommand` the event is triggered 1372 before running the provided command in gdb. 1373 *TermdebugStopPre* 1374TermdebugStopPre Before debugging ends, when gdb is terminated, 1375 most likely after issuing a "quit" command in 1376 the gdb window. 1377 *TermdebugStopPost* 1378TermdebugStopPost After debugging has ended, gdb-related windows 1379 are closed, debug buffers wiped out and 1380 the state before the debugging was restored. 1381 1382 1383Prompt mode ~ 1384 *termdebug-prompt* 1385When the |+terminal| feature is not supported and on MS-Windows, gdb will run 1386in a buffer with 'buftype' set to "prompt". This works slightly differently: 1387- The gdb window will be in Insert mode while typing commands. Go to Normal 1388 mode with <Esc>, then you can move around in the buffer, copy/paste, etc. 1389 Go back to editing the gdb command with any command that starts Insert mode, 1390 such as `a` or `i`. 1391- The program being debugged will run in a separate window. On MS-Windows 1392 this is a new console window. On Unix, if the |+terminal| feature is 1393 available a Terminal window will be opened to run the debugged program in. 1394 1395 *termdebug_use_prompt* 1396Prompt mode can be used even when the |+terminal| feature is present with: > 1397 let g:termdebug_use_prompt = 1 1398< 1399 *termdebug_map_K* 1400The K key is normally mapped to :Evaluate. If you do not want this use: > 1401 let g:termdebug_map_K = 0 1402 1403< 1404 *termdebug_disasm_window* 1405If you want the Asm window shown by default, set this to 1. Setting to 1406any value greater than 1 will set the Asm window height to that value: > 1407 let g:termdebug_disasm_window = 15 1408< 1409 1410Communication ~ 1411 *termdebug-communication* 1412There is another, hidden, buffer, which is used for Vim to communicate with 1413gdb. The buffer name is "gdb communication". Do not delete this buffer, it 1414will break the debugger. 1415 1416Gdb has some weird behavior, the plugin does its best to work around that. 1417For example, after typing "continue" in the gdb window a CTRL-C can be used to 1418interrupt the running program. But after using the MI command 1419"-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see 1420"continue" being used for the `:Continue` command, instead of using the 1421communication channel. 1422 1423 1424Customizing ~ 1425 1426GDB command *termdebug-customizing* 1427 *g:termdebugger* 1428To change the name of the gdb command, set the "g:termdebugger" variable before 1429invoking `:Termdebug`: > 1430 let g:termdebugger = "mygdb" 1431< *gdb-version* 1432Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI 1433interface. The "new-ui" command requires gdb version 7.12 or later. if you 1434get this error: 1435 Undefined command: "new-ui". Try "help".~ 1436Then your gdb is too old. 1437 1438 1439Colors *hl-debugPC* *hl-debugBreakpoint* 1440 1441The color of the signs can be adjusted with these highlight groups: 1442- debugPC the current position 1443- debugBreakpoint a breakpoint 1444 1445The defaults are, when 'background' is "light": 1446 hi debugPC term=reverse ctermbg=lightblue guibg=lightblue 1447 hi debugBreakpoint term=reverse ctermbg=red guibg=red 1448 1449When 'background' is "dark": 1450 hi debugPC term=reverse ctermbg=darkblue guibg=darkblue 1451 hi debugBreakpoint term=reverse ctermbg=red guibg=red 1452 1453 1454Shortcuts *termdebug_shortcuts* 1455 1456You can define your own shortcuts (mappings) to control gdb, that can work in 1457any window, using the TermDebugSendCommand() function. Example: > 1458 map ,w :call TermDebugSendCommand('where')<CR> 1459The argument is the gdb command. 1460 1461 1462Popup menu *termdebug_popup* 1463 1464By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds 1465these entries to the popup menu: 1466 Set breakpoint `:Break` 1467 Clear breakpoint `:Clear` 1468 Evaluate `:Evaluate` 1469If you don't want this then disable it with: > 1470 let g:termdebug_popup = 0 1471 1472 1473Vim window width *termdebug_wide* 1474 1475To change the width of the Vim window when debugging starts and use a vertical 1476split: > 1477 let g:termdebug_wide = 163 1478 1479This will set 'columns' to 163 when `:Termdebug` is used. The value is 1480restored when quitting the debugger. 1481 1482If g:termdebug_wide is set and 'columns' is already a greater value, then a 1483vertical split will be used without modifying 'columns'. 1484 1485Set g:termdebug_wide to 1 to use a vertical split without ever changing 1486'columns'. This is useful when the terminal can't be resized by Vim. 1487 1488 1489 vim:tw=78:ts=8:noet:ft=help:norl: 1490