*terminal.txt*	For Vim version 8.0.  Last change: 2017 Oct 29
    
    
    		  VIM REFERENCE MANUAL	  by Bram Moolenaar
    
    
    Terminal window support					*terminal*
    
    
    WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE
    
    The terminal feature is optional, use this to check if your Vim has it: >
    	echo has('terminal')
    If the result is "1" you have it.
    
    
    1. Basic use			|terminal-use|
    2. Remote testing		|terminal-testing|
    3. Debugging			|terminal-debug|
    
    {Vi does not have any of these commands}
    {only available when compiled with the |+terminal| feature}
    
    The terminal feature requires the |+multi_byte|, |+job| and |+channel| features.
    
    ==============================================================================
    1. Basic use						*terminal-use*
    
    This feature is for running a terminal emulator in a Vim window.  A job can be
    started connected to the terminal emulator. For example, to run a shell: >
         :term bash
    
    Or to run build command: >
         :term make myprogram
    
    The job runs asynchronously from Vim, the window will be updated to show
    output from the job, also while editing in another window.
    
    
    Typing ~
    							*terminal-typing*
    When the keyboard focus is in the terminal window, typed keys will be sent to
    the job.  This uses a pty when possible.  You can click outside of the
    terminal window to move keyboard focus elsewhere.
    
    CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
    	CTRL-W CTRL-W 	move focus to the next window
    	CTRL-W :	enter an Ex command
    See |CTRL-W| for more commands.
    
    Special in the terminal window:			*CTRL-W_.*  *CTRL-W_N* 
    	CTRL-W .	send a CTRL-W to the job in the terminal
    	CTRL-W N	go to Terminal-Normal mode, see |Terminal-mode|
    	CTRL-\ CTRL-N   go to Terminal-Normal mode, see |Terminal-mode|
    	CTRL-W " {reg}  paste register {reg}		*CTRL-W_quote*
    			Also works with the = register to insert the result of
    			evaluating an expression.
    	CTRL-W CTRL-C	ends the job, see below |t_CTRL-W_CTRL-C|
    
    See option 'termkey' for specifying another key instead of CTRL-W that
    will work like CTRL-W.  However, typing 'termkey' twice sends 'termkey' to
    the job.  For example:
    	'termkey' CTRL-W    move focus to the next window
    	'termkey' :	    enter an Ex command
    	'termkey' 'termkey' send 'termkey' to the job in the terminal
    	'termkey' .	    send a CTRL-W to the job in the terminal
    	'termkey' N  	    go to terminal Normal mode, see below
    	'termkey' CTRL-N    same as CTRL-W N
    	'termkey' CTRL-C    same as |t_CTRL-W_CTRL-C|
    							*t_CTRL-\_CTRL-N*
    The special key combination CTRL-\ CTRL-N can be used to switch to Normal
    mode, just like this works in any other mode.
    							*t_CTRL-W_CTRL-C*
    CTRL-W CTRL-C can be typed to forcefully end the job.  On MS-Windows a
    CTRL-BREAK will also kill the job.
    
    If you type CTRL-C the effect depends on what the pty has been configured to
    do.  For simple commands this causes a SIGINT to be sent to the job, which
    would end it.  Other commands may ignore the SIGINT or handle the CTRL-C
    themselves (like Vim does).
    
    To change the keys you type use terminal mode mappings, see |:tmap|.
    These are defined like any mapping, but apply only when typing keys that are
    sent to the job running in the terminal.  For example, to make Escape switch
    to Terminal-Normal mode: >
       tnoremap <Esc> <C-W>N
    <							*options-in-terminal*
    After opening the terminal window and setting 'buftype' to "terminal" the
    BufWinEnter autocommand event is triggered.  This makes it possible to set
    options specifically for the window and buffer.  Example: >
       au BufWinEnter * if &buftype == 'terminal' | setlocal bufhidden=hide | endif
    
    
    Size and color ~
    
    See option 'termsize' for controlling the size of the terminal window.
    (TODO: scrolling when the terminal is larger than the window)
    
    The job running in the terminal can change the colors.  The default foreground
    and background colors are taken from Vim, the Normal highlight group.
    
    For a color terminal the 'background' option is used to decide whether the
    terminal window will start with a white or black background.
    
    To use a different color the Terminal highlight group can be used: >
        hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
    
    
    Syntax ~
    
    :[range]ter[minal] [options] [command]			*:ter* *:terminal*
    			Open a new terminal window.
    
    			If [command] is provided run it as a job and connect
    			the input and output to the terminal.
    			If [command] is not given the 'shell' option is used.
    			if [command] is NONE no job is started, the pty of the
    			terminal can be used by a command like gdb.
    
    			A new buffer will be created, using [command] or
    			'shell' as the name, prefixed with a "!".  If a buffer
    			by this name already exists a number is added in
    			parentheses.  E.g. if "gdb" exists the second terminal
    			buffer will use "!gdb (1)".
    
    			If [range] is given the specified lines are used as
    			input for the job.  It will not be possible to type
    			keys in the terminal window.  For MS-Windows see the
    			++eof argument below.
    
    			Two comma separated numbers are used as "rows,cols".
    			E.g. `:24,80gdb` opens a terminal with 24 rows and 80
    			columns.  However, if the terminal window spans the
    			Vim window with, there is no vertical split, the Vim
    			window width is used.
    						*term++close* *term++open*
    			Supported [options] are:
    			++close		The terminal window will close
    					automatically when the job terminates.
    			++open		When the job terminates and no window
    					shows it, a window will be opened.
    					Note that this can be interruptive.
    			++curwin	Open the terminal in the current
    					window, do not split the current
    					window.  Fails if the current buffer
    					cannot be |abandon|ed.
    			++hidden	Open the terminal in a hidden buffer,
    					no window will be used.
    			++rows={height} Use {height} for the terminal window
    					height.
    			++cols={width}  Use {width} for the terminal window
    					width.
    			++eof={text}	when using [range]: text to send after
    					the last line was written. Cannot
    					contain white space.  A CR is
    					appended.  For MS-Windows the default
    					is to send CTRL-D.
    					E.g. for a shell use "++eof=exit" and
    					for Python "++eof=exit()".  Special
    					codes can be used like with `:map`,
    					e.g. "<C-Z>" for CTRL-Z.
    
    			If you want to use more options use the |term_start()|
    			function.
    
    When the buffer associated with the terminal is unloaded or wiped out the job
    is killed, similar to calling `job_stop(job, "kill")`
    
    So long as the job is running the window behaves like it contains a modified
    buffer.  Trying to close the window with `CTRL-W :quit` fails.  When using
    `CTRL-W :quit!` the job is ended.  The text in the window is lost.  The buffer
    still exists, but getting it in a window with `:buffer` will show an empty
    buffer.
    
    Trying to close the window with `CTRL-W :close` also fails.   Using
    `CTRL-W :close!` will close the window and make the buffer hidden.
    
    You can use `CTRL-W :hide` to close the terminal window and make the buffer
    hidden, the job keeps running.  The `:buffer` command can be used to turn the
    current window into a terminal window.  If there are unsaved changes this
    fails, use !  to force, as usual.
    
    To have a background job run without a window, and open the window when it's
    done, use options like this: >
    	:term ++hidden ++open make
    Note that the window will open at an unexpected moment, this will interrupt
    what you are doing.
    
    							*E947* *E948*
    So long as the job is running, the buffer is considered modified and Vim
    cannot be quit easily, see |abandon|.
    
    When the job has finished and no changes were made to the buffer: closing the
    window will wipe out the buffer.
    
    Before changes can be made to a terminal buffer, the 'modifiable' option must
    be set.  This is only possible when the job has finished.  At the first change
    the buffer will become a normal buffer and the highlighting is removed.
    You may want to change the buffer name with |:file| to be able to write, since
    the buffer name will still be set to the command.
    
    
    Resizing ~
    
    The size of the terminal can be in one of three modes:
    
    1. The 'termsize' option is empty: The terminal size follows the window size.
       The minimal size is 2 screen lines with 10 cells.
    
    2. The 'termsize' option is "rows*cols", where "rows" is the minimal number of
       screen rows and "cols" is the minimal number of cells.
    
    3. The 'termsize' option is "rowsXcols" (where the x is upper or lower case).
       The terminal size is fixed to the specified number of screen lines and
       cells.  If the window is bigger there will be unused empty space.
    
    If the window is smaller than the terminal size, only part of the terminal can
    be seen (the lower-left part).
    
    The |term_getsize()| function can be used to get the current size of the
    terminal.  |term_setsize()| can be used only when in the first or second mode,
    not when 'termsize' is "rowsXcols".
    
    
    Terminal-Job and Terminal-Normal mode ~
    							*Terminal-mode*
    When the job is running the contents of the terminal is under control of the
    job.  That includes the cursor position.  Typed keys are sent to the job.
    The terminal contents can change at any time.  This is called Terminal-Job
    mode.
    
    Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode.  Now the
    contents of the terminal window is under control of Vim, the job output is
    suspended.  CTRL-\ CTRL-N does the same.
    
    Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by
    |term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are.
    
    							*E946*
    In Terminal-Normal mode you can move the cursor around with the usual Vim
    commands, Visually mark text, yank text, etc.  But you cannot change the
    contents of the buffer.  The commands that would start insert mode, such as
    'i' and 'a', return to Terminal-Job mode.  The window will be updated to show
    the contents of the terminal. |:startinsert| is ineffective.
    
    In Terminal-Normal mode the statusline and window title show "(Terminal)".  If
    the job ends while in Terminal-Normal mode this changes to
    "(Terminal-finished)".
    
    It is not possible to enter Insert mode from Terminal-Job mode.
    
    
    Cursor style ~
    
    By default the cursor in the terminal window uses a not blinking block.  The
    normal xterm escape sequences can be used to change the blinking state and the
    shape.  Once focus leaves the terminal window Vim will restore the original
    cursor.
    
    An exception is when xterm is started with the "-bc" argument, or another way
    that causes the cursor to blink.  This actually means that the blinking flag
    is inverted.  Since Vim cannot detect this, the terminal window cursor
    blinking will also be inverted.
    
    
    Unix ~
    
    On Unix a pty is used to make it possible to run all kinds of commands.  You
    can even run Vim in the terminal!  That's used for debugging, see below.
    
    Environment variables are used to pass information to the running job:
        TERM		name of the terminal, 'term'
        ROWS		number of rows in the terminal initially
        LINES		same as ROWS
        COLUMNS		number of columns in the terminal initially
        COLORS		number of colors, 't_Co' (256*256*256 in the GUI)
        VIM_SERVERNAME	v:servername
    
    The |client-server| feature can be used to communicate with the Vim instance
    where the job was started.  This only works when v:servername is not empty.
    If needed you can set it with: >
    	call remote_startserver('vim-server')
    
    In the job you can then do something like: >
    	vim --servername $VIM_SERVERNAME --remote +123 some_file.c
    This will open the file "some_file.c" and put the cursor on line 123.
    
    
    MS-Windows ~
    
    On MS-Windows winpty is used to make it possible to run all kind of commands.
    Obviously, they must be commands that run in a terminal, not open their own
    window.
    
    You need the following two files from winpty:
    
        winpty.dll
        winpty-agent.exe
    
    You can download them from the following page:
    
        
    
    Just put the files somewhere in your PATH.  You can set the 'winptydll' option
    to point to the right file, if needed.  If you have both the 32-bit and 64-bit
    version, rename to winpty32.dll and winpty64.dll to match the way Vim was
    build.
    
    ==============================================================================
    2. Remote testing					*terminal-testing*
    
    Most Vim tests execute a script inside Vim.  For some tests this does not
    work, running the test interferes with the code being tested.  To avoid this
    Vim is executed in a terminal window.  The test sends keystrokes to it and
    inspects the resulting screen state.
    
    Functions ~
    
    term_sendkeys()		send keystrokes to a terminal (not subject to tmap)
    term_wait()		wait for screen to be updated
    term_scrape()		inspect terminal screen
    
    
    ==============================================================================
    3. Debugging					*terminal-debug*
    
    The Terminal debugging plugin can be used to debug a program with gdb and view
    the source code in a Vim window.  Since this is completely contained inside
    Vim this also works remotely over an ssh connection.
    
    
    Starting ~
    
    Load the plugin with this command: >
    	packadd termdebug
    <							*:Termdebug*
    To start debugging use `:TermDebug` folowed by the command name, for example: >
    	:Termdebug vim
    
    This opens two windows:
    gdb window	A terminal window in which "gdb vim" is executed.  Here you
    		can directly interact with gdb.  The buffer name is "!gdb".
    program window	A terminal window for the executed program.  When "run" is
    		used in gdb the program I/O will happen in this window, so
    		that it does not interfere with controlling gdb.  The buffer
    		name is "gdb program".
    
    The current window is used to show the source code.  When gdb pauses the
    source file location will be displayed, if possible.  A sign is used to
    highlight the current position (using highlight group debugPC).	 
    
    If the buffer in the current window is modified, another window will be opened
    to display the current gdb position.
    
    Focus the terminal of the executed program to interact with it.  This works
    the same as any command running in a terminal window.
    
    When the debugger ends, typically by typing "quit" in the gdb window, the two
    opened windows are closed.
    
    
    Example session ~
    
    Start in the Vim "src" directory and build Vim: >
    	% make
    Start Vim: >
    	% ./vim
    Load the termdebug plugin and start debugging Vim: >
    	:packadd termdebug
    	:Termdebug vim
    You should now have three windows:
        source  - where you started, has a window toolbar with buttons
        gdb	    - you can type gdb commands here
        program - the executed program will use this window
    You can use CTRL-W CTRL-W or the mouse to move focus between windows.
    Put focus on the gdb window and type: >
    	break ex_help
    	run
    Vim will start running in the program window. Put focus there and type: >
    	:help gui
    Gdb will run into the ex_help breakpoint.  The source window now shows the 
    ex_cmds.c file.  A ">>" marker will appear where the breakpoint was set.  The
    line where the debugger stopped is highlighted.  You can now step through the
    program.  Let's use the mouse: click on the "Next" button in the window
    toolbar.  You will see the highlighting move as the debugger executes a line
    of source code.
    
    Click "Next" a few times until the for loop is highlighted.  Put the cursor on
    the end of "eap->arg", then click "Eval" in the toolbar.  You will see this
    displayed:
    	"eap->arg": 0x555555e68855 "gui" ~
    This way you can inspect the value of local variables.  You can also focus the
    gdb window and use a "print" command, e.g.: >
    	print *eap
    
    Now go back to the source window and put the cursor on the first line after
    the for loop, then type: >
    	:Break
    You will see a ">>" marker appear, this indicates the new breakpoint.  Now
    click "Cont" in the toolbar and the code until the breakpoint will be
    executed.
    
    You can type more advanced commands in the gdb window.  For example, type: >
    	watch curbuf
    Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
    will now continue until the value of "curbuf" changes, which is in do_ecmd().
    To remove this watchpoint again type in the gdb window: >
    	delete 3
    
    You can see the stack by typing in the gdb window: >
    	where
    Move through the stack frames, e.g. with: >
    	frame 3
    The source window will show the code, at the point where the call was made to
    a deeper level.
    
    
    Stepping through code ~
    
    Put focus on the gdb window to type commands there.  Some common ones are:
    - CTRL-C    interrupt the program
    - next      execute the current line and stop at the next line
    - step      execute the current line and stop at the next statement, entering
    	    functions
    - finish    execute until leaving the current function
    - where     show the stack
    - frame N   go to the Nth stack frame
    - continue  continue execution
    
    In the window showing the source code some commands can used to control gdb:
     :Break     set a breakpoint at the current line; a sign will be displayed
     :Delete    delete a breakpoint at the current line
     :Step	    execute the gdb "step" command
     :Over      execute the gdb "next" command (:Next is a Vim command)
     :Finish    execute the gdb "finish" command
     :Continue  execute the gdb "continue" command
    
    The plugin adds a window toolbar with these entries:
      Step	    :Step
      Next	    :Over
      Finish    :Finish
      Cont	    :Continue
      Eval	    :Evaluate
    This way you can use the mouse to perform the most common commands.
    
    
    Inspecting variables ~
    
     :Evaluate	    evaluate the expression under the cursor
     K		    same
     :Evaluate {expr}   evaluate {expr}
     :'<,'>Evaluate	    evaluate the Visually selected text
    
    This is similar to using "print" in the gdb window.
    
    
    Other commands ~
    
     :Gdb	       jump to the gdb window
     :Program      jump to the window with the running program
    
    
    Communication ~
    
    There is another, hidden, buffer, which is used for Vim to communicate with
    gdb.  The buffer name is "gdb communication".  Do not delete this buffer, it
    will break the debugger.
    
    
    Customizing ~
    
    To change the name of the gdb command, set the "termdebugger" variable before
    invoking `:Termdebug`: >
    	let termdebugger = "mygdb"
    <						*gdb-version*
    Only debuggers fully compatible with gdb will work.  Vim uses the GDB/MI
    interface.  This probably requires gdb version 7.12.  if you get this error:
    	Undefined command: "new-ui". Try "help".~
    Then your gdb is too old.
    
    The color of the signs can be adjusted with these highlight groups:
    - debugPC		the current position
    - debugBreakpoint	a breakpoint
    
    The defaults are, when 'background' is "light":
      hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
      hi debugBreakpoint term=reverse ctermbg=red guibg=red
    
    When 'background' is "dark":
      hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
      hi debugBreakpoint term=reverse ctermbg=red guibg=red
    
    To change the width of the Vim window when debugging starts, and use a
    vertical split: >
      let g:termdebug_wide = 163
    This will set &columns to 163 when :Termdebug is used.  The value is restored
    when quitting the debugger.
    If g:termdebug_wide is set and &Columns is already  larger than
    g:termdebug_wide then a vertical split will be used without changing &columns.
    Set it to 1 to get a vertical split without every changing &columns (useful
    for when the terminal can't be resized by Vim).
    
    
    
     vim:tw=78:ts=8:ft=help:norl: