vim: runtime/doc/terminal.txt annotate

annotate runtime/doc/terminal.txt @ 12064:407a475c67fd v8.0.0912

patch 8.0.0912: cannot run a job in a hidden terminal commit https://github.com/vim/vim/commit/8cad930a259a05a95c7d0c527a5881d5f9a59057 Author: Bram Moolenaar <Bram@vim.org> Date: Sat Aug 12 14:32:32 2017 +0200 patch 8.0.0912: cannot run a job in a hidden terminal Problem: Cannot run a job in a hidden terminal. Solution: Add option "hidden" and ++hidden.

author	Christian Brabandt <cb@256bit.org>
date	Sat, 12 Aug 2017 14:45:04 +0200
parents	9897241c08b5
children	b80c0172d1a8

rev	line source
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	1 terminal.txt For Vim version 8.0. Last change: 2017 Aug 12
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	2
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	3
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	4 VIM REFERENCE MANUAL by Bram Moolenaar
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	5
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	6
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	7 Terminal window support terminal
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	8
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	9
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	10 WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	11
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	12 The terminal feature is optional, use this to check if your Vim has it: >
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	13 echo has('terminal')
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	14 If the result is "1" you have it.
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	15
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	16
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	17 1. Basic use \|terminal-use\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	18 2. Remote testing \|terminal-testing\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	19 3. Debugging \|terminal-debug\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	20
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	21 {Vi does not have any of these commands}
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	22
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	23 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	24 1. Basic use terminal-use
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	25
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	26 This feature is for running a terminal emulator in a Vim window. A job can be
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	27 started connected to the terminal emulator. For example, to run a shell: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	28 :term bash
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	29
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	30 Or to run a debugger: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	31 :term gdb vim
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	32
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	33 The job runs asynchronously from Vim, the window will be updated to show
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	34 output from the job, also while editing in any other window.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	35
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	36
11814 d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	37 Typing ~
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	38
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	39 When the keyboard focus is in the terminal window, typed keys will be sent to
11814 d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	40 the job. This uses a pty when possible. You can click outside of the
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	41 terminal window to move keyboard focus elsewhere.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	42
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	43 CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	44 CTRL-W CTRL-W move focus to the next window
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	45 CTRL-W : enter an Ex command
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	46 See \|CTRL-W\| for more commands.
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	47
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	48 Special in the terminal window: CTRL-W_. CTRL-W_N
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	49 CTRL-W . send a CTRL-W to the job in the terminal
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	50 CTRL-W N go to Terminal-Normal mode, see \|Terminal-mode\|
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	51 CTRL-\ CTRL-N go to Terminal-Normal mode, see \|Terminal-mode\|
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	52 CTRL-W " {reg} paste register {reg} CTRL-W_quote
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	53 Also works with the = register to insert the result of
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	54 evaluating an expression.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	55
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	56 See option 'termkey' for specifying another key instead of CTRL-W that
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	57 will work like CTRL-W. However, typing 'termkey' twice sends 'termkey' to
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	58 the job. For example:
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	59 'termkey' CTRL-W move focus to the next window
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	60 'termkey' : enter an Ex command
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	61 'termkey' 'termkey' send 'termkey' to the job in the terminal
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	62 'termkey' . send a CTRL-W to the job in the terminal
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	63 'termkey' N go to terminal Normal mode, see below
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	64 'termkey' CTRL-N same as CTRL-W N
11965 a932d3da41c8 patch 8.0.0863: a remote command does not work in the terminal window Christian Brabandt <cb@256bit.org> parents: 11914 diff changeset	65 t_CTRL-\_CTRL-N
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	66 The special key combination CTRL-\ CTRL-N can be used to switch to Normal
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	67 mode, just like this works in any other mode.
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	68
11814 d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	69
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	70 Size ~
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	71
11659 49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	72 See option 'termsize' for controlling the size of the terminal window.
49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	73 (TODO: scrolling when the terminal is larger than the window)
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	74
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	75
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	76 Syntax ~
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	77
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	78 :[range]ter[minal] [options] [command] :ter :terminal
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	79 Open a new terminal window.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	80
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	81 If [command] is provided run it as a job and connect
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	82 the input and output to the terminal.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	83 If [command] is not given the 'shell' option is used.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	84
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	85 A new buffer will be created, using [command] or
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	86 'shell' as the name, prefixed with a "!". If a buffer
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	87 by this name already exists a number is added in
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	88 parentheses. E.g. if "gdb" exists the second terminal
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	89 buffer will use "!gdb (1)".
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	90
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	91 If [range] is given it is used for the terminal size.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	92 One number specifies the number of rows. Unless the
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	93 "vertical" modifier is used, then it is the number of
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	94 columns.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	95
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	96 Two comma separated numbers are used as "rows,cols".
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	97 E.g. `:24,80gdb` opens a terminal with 24 rows and 80
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	98 columns. However, if the terminal window spans the
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	99 Vim window with, there is no vertical split, the Vim
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	100 window width is used.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	101 term++close term++open
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	102 Supported [options] are:
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	103 ++close The terminal window will close
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	104 automatically when the job terminates.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	105 ++open When the job terminates and no window
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	106 shows it, a window will be opened.
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	107 Note that this can be interruptive.
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	108 ++curwin Open the terminal in the current
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	109 window, do not split the current
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	110 window. Fails if the current buffer
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	111 cannot be \|abandon\|ed.
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	112 ++hidden Open the terminal in a hidden buffer,
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	113 no window will be used.
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	114
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	115 If you want to use more options use the \|term_start()\|
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	116 function.
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	117
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	118 When the buffer associated with the terminal is wiped out the job is killed,
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	119 similar to calling `job_stop(job, "kill")`
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	120
11967 12833414cc02 patch 8.0.0864: cannot specify the name of a terminal Christian Brabandt <cb@256bit.org> parents: 11965 diff changeset	121 By default the 'bufhidden' option of the buffer will be set to "hide".
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	122 So long as the job is running: If the window is closed the buffer becomes
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	123 hidden. The command will not be stopped. The `:buffer` command can be used
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	124 to turn the current window into a terminal window. If there are unsaved
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	125 changes this fails, use ! to force, as usual.
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	126
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	127 To have a background job run without a window, and open the window when it's
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	128 done, use options like this: >
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	129 :term ++hidden ++open make
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	130 Note that the window will open at an unexpected moment, this will interrupt
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	131 what you are doing.
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	132
11967 12833414cc02 patch 8.0.0864: cannot specify the name of a terminal Christian Brabandt <cb@256bit.org> parents: 11965 diff changeset	133 E947
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal Christian Brabandt <cb@256bit.org> parents: 11965 diff changeset	134 So long as the job is running, the buffer is considered modified and Vim
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal Christian Brabandt <cb@256bit.org> parents: 11965 diff changeset	135 cannot be quit easily, see \|abandon\|.
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	136
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	137 When the job has finished and no changes were made to the buffer: closing the
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	138 window will wipe out the buffer.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	139
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	140 Before changes can be made to a terminal buffer, the 'modifiable' option must
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	141 be set. This is only possible when the job has finished. At the first change
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	142 the buffer will become a normal buffer and the highlighting is removed.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	143 You may want to change the buffer name with \|:file\| to be able to write, since
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	144 the buffer name will still be set to the command.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	145
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	146
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	147 Resizing ~
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	148
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	149 The size of the terminal can be in one of three modes:
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	150
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	151 1. The 'termsize' option is empty: The terminal size follows the window size.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	152 The minimal size is 2 screen lines with 10 cells.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	153
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	154 2. The 'termsize' option is "rows*cols", where "rows" is the minimal number of
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	155 screen rows and "cols" is the minimal number of cells.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	156
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	157 3. The 'termsize' option is "rowsXcols" (where the x is upper or lower case).
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	158 The terminal size is fixed to the specified number of screen lines and
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	159 cells. If the window is bigger there will be unused empty space.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	160
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	161 If the window is smaller than the terminal size, only part of the terminal can
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	162 be seen (the lower-left part).
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	163
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	164 The \|term_getsize()\| function can be used to get the current size of the
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	165 terminal. \|term_setsize()\| can be used only when in the first or second mode,
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	166 not when 'termsize' is "rowsXcols".
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	167
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	168
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	169 Terminal-Job and Terminal-Normal mode ~
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	170 Terminal-mode
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	171 When the job is running the contents of the terminal is under control of the
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	172 job. That includes the cursor position. Typed keys are sent to the job.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	173 The terminal contents can change at any time. This is called Terminal-Job
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	174 mode.
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	175
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	176 Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode. Now the
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	177 contents of the terminal window is under control of Vim, the job output is
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	178 suspended. CTRL-\ CTRL-N does the same.
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	179 E946
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	180 In Terminal-Normal mode you can move the cursor around with the usual Vim
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	181 commands, Visually mark text, yank text, etc. But you cannot change the
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	182 contents of the buffer. The commands that would start insert mode, such as
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	183 'i' and 'a', return to Terminal-Job mode. The window will be updated to show
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	184 the contents of the terminal.
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	185
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	186 In Terminal-Normal mode the statusline and window title show "(Terminal)". If
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	187 the job ends while in Terminal-Normal mode this changes to
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	188 "(Terminal-finished)".
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	189
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	190
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	191 Unix ~
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	192
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	193 On Unix a pty is used to make it possible to run all kinds of commands. You
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	194 can even run Vim in the terminal! That's used for debugging, see below.
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	195
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	196 Environment variables are used to pass information to the running job:
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	197 TERM name of the terminal, 'term'
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	198 ROWS number of rows in the terminal initially
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	199 LINES same as ROWS
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	200 COLUMNS number of columns in the terminal initially
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	201 COLORS number of colors, 't_Co' (256256256 in the GUI)
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	202 VIM_SERVERNAME v:servername
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	203
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	204 The \|client-server\| feature can be used to communicate with the Vim instance
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	205 where the job was started. This only works when v:servername is not empty.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	206 If needed you can set it with: >
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	207 call remote_startserver('vim-server')
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	208
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	209 In the job you can then do something like: >
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	210 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	211 This will open the file "some_file.c" and put the cursor on line 123.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	212
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	213
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	214 MS-Windows ~
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	215
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	216 On MS-Windows winpty is used to make it possible to run all kind of commands.
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	217 Obviously, they must be commands that run in a terminal, not open their own
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	218 window.
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	219
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	220 You need the following two files from winpty:
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	221
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	222 winpty.dll
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	223 winpty-agent.exe
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	224
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	225 You can download them from the following page:
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	226
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	227 https://github.com/rprichard/winpty
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	228
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	229 Just put the files somewhere in your PATH.
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	230
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	231 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	232 2. Remote testing terminal-testing
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	233
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	234 Most Vim tests execute a script inside Vim. For some tests this does not
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	235 work, running the test interferes with the code being tested. To avoid this
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	236 Vim is executed in a terminal window. The test sends keystrokes to it and
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	237 inspects the resulting screen state.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	238
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	239 Functions ~
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	240
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	241 term_sendkeys() send keystrokes to a terminal
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	242 term_wait() wait for screen to be updated
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	243 term_scrape() inspect terminal screen
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	244
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	245
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	246 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	247 3. Debugging terminal-debug
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	248
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	249 The Terminal debugging plugin can be used to debug a program with gdb and view
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	250 the source code in a Vim window. For example: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	251
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	252 :TermDebug vim
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	253
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	254 This opens three windows:
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	255 - A terminal window in which "gdb vim" is executed. Here you can directly
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	256 interact with gdb.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	257 - A terminal window for the executed program. When "run" is used in gdb the
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	258 program I/O will happen in this window, so that it does not interfere with
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	259 controlling gdb.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	260 - A normal Vim window used to show the source code. When gdb jumps to a
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	261 source file location this window will display the code, if possible. Values
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	262 of variables can be inspected, breakpoints set and cleared, etc.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	263
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	264 This uses two terminal windows. To open the gdb window: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	265 :term gdb [arguments]
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	266 To open the terminal to run the tested program \|term_start()\| is used.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	267
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	268 TODO
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	269
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	270
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	271 vim:tw=78:ts=8:ft=help:norl:

Mercurial > vim

annotate runtime/doc/terminal.txt @ 12064:407a475c67fd v8.0.0912