vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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: