Mercurial > vim

comparison runtime/doc/terminal.txt @ 12031:9897241c08b5 v8.0.0896

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.0.0896: cannot close a terminal window when the job ends commit https://github.com/vim/vim/commit/dd693ce28b158ff573129ee30fe5b886544a03c2 Author: Bram Moolenaar <Bram@vim.org> Date: Thu Aug 10 23:15:19 2017 +0200 patch 8.0.0896: cannot close a terminal window when the job ends Problem: Cannot automaticlaly close a terminal window when the job ends. Solution: Add the ++close argument to :term. Add the term_finish option to term_start(). (Yasuhiro Matsumoto, closes #1950) Also add ++open.
author Christian Brabandt <cb@256bit.org>
date Thu, 10 Aug 2017 23:30:05 +0200
parents 12833414cc02
children 407a475c67fd
comparison
equal deleted inserted replaced
12030:4d0860530243 12031:9897241c08b5
1 *terminal.txt* For Vim version 8.0. Last change: 2017 Aug 05 1 *terminal.txt* For Vim version 8.0. Last change: 2017 Aug 10
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
34 output from the job, also while editing in any other window. 34 output from the job, also while editing in any other window.
35 35
36 36
37 Typing ~ 37 Typing ~
38 38
39 When the keyboard focus is in the terminal window, typed keys will be send to 39 When the keyboard focus is in the terminal window, typed keys will be sent to
40 the job. This uses a pty when possible. You can click outside of the 40 the job. This uses a pty when possible. You can click outside of the
41 terminal window to move keyboard focus elsewhere. 41 terminal window to move keyboard focus elsewhere.
42 42
43 CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.: 43 CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
44 CTRL-W CTRL-W move focus to the next window 44 CTRL-W CTRL-W move focus to the next window
45 CTRL-W : enter an Ex command 45 CTRL-W : enter an Ex command
46 See |CTRL-W| for more commands. 46 See |CTRL-W| for more commands.
47 47
48 Special in the terminal window: *CTRL-W_.* *CTRL-W_N* 48 Special in the terminal window: *CTRL-W_.* *CTRL-W_N*
49 CTRL-W . send a CTRL-W to the job in the terminal 49 CTRL-W . send a CTRL-W to the job in the terminal
50 CTRL-W N go to Terminal Normal mode, see |Terminal-mode| 50 CTRL-W N go to Terminal-Normal mode, see |Terminal-mode|
51 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode|
51 CTRL-W " {reg} paste register {reg} *CTRL-W_quote* 52 CTRL-W " {reg} paste register {reg} *CTRL-W_quote*
52 Also works with the = register to insert the result of 53 Also works with the = register to insert the result of
53 evaluating an expression. 54 evaluating an expression.
54 55
55 See option 'termkey' for specifying another key instead of CTRL-W that 56 See option 'termkey' for specifying another key instead of CTRL-W that
60 'termkey' 'termkey' send 'termkey' to the job in the terminal 61 'termkey' 'termkey' send 'termkey' to the job in the terminal
61 'termkey' . send a CTRL-W to the job in the terminal 62 'termkey' . send a CTRL-W to the job in the terminal
62 'termkey' N go to terminal Normal mode, see below 63 'termkey' N go to terminal Normal mode, see below
63 'termkey' CTRL-N same as CTRL-W N 64 'termkey' CTRL-N same as CTRL-W N
64 *t_CTRL-\_CTRL-N* 65 *t_CTRL-\_CTRL-N*
65 The special key combination CTRL-\ CTRL-N can be used to prefix one Normal 66 The special key combination CTRL-\ CTRL-N can be used to switch to Normal
66 mode command. This is especially useful for remote commands, when you don't 67 mode, just like this works in any other mode.
67 know whether Vim currently has focus in a terminal window. Note that only one
68 Normal mode command can be used.
69 68
70 69
71 Size ~ 70 Size ~
72 71
73 See option 'termsize' for controlling the size of the terminal window. 72 See option 'termsize' for controlling the size of the terminal window.
74 (TODO: scrolling when the terminal is larger than the window) 73 (TODO: scrolling when the terminal is larger than the window)
75 74
76 75
77 Syntax ~ 76 Syntax ~
78 77
79 :ter[minal] [command] *:ter* *:terminal* 78 :[range]ter[minal] [options] [command] *:ter* *:terminal*
80 Open a new terminal window. 79 Open a new terminal window.
81 80
82 If [command] is provided run it as a job and connect 81 If [command] is provided run it as a job and connect
83 the input and output to the terminal. 82 the input and output to the terminal.
84 If [command] is not given the 'shell' option is used. 83 If [command] is not given the 'shell' option is used.
85 84
86 A new buffer will be created, using [command] or 85 A new buffer will be created, using [command] or
87 'shell' as the name, prefixed with a "!". If a buffer 86 'shell' as the name, prefixed with a "!". If a buffer
88 by this name already exists a number is added in 87 by this name already exists a number is added in
89 parenthesis. E.g. if "gdb" exists the second terminal 88 parentheses. E.g. if "gdb" exists the second terminal
90 buffer will use "!gdb (1)". 89 buffer will use "!gdb (1)".
90
91 If [range] is given it is used for the terminal size.
92 One number specifies the number of rows. Unless the
93 "vertical" modifier is used, then it is the number of
94 columns.
95
96 Two comma separated numbers are used as "rows,cols".
97 E.g. `:24,80gdb` opens a terminal with 24 rows and 80
98 columns. However, if the terminal window spans the
99 Vim window with, there is no vertical split, the Vim
100 window width is used.
101 *term++close* *term++open*
102 Supported [options] are:
103 ++close The terminal window will close
104 automatically when the job terminates.
105 ++open When the job terminates and no window
106 show it, a window will be opened.
107 Note that this can be interruptive.
91 108
92 When the buffer associated with the terminal is wiped out the job is killed, 109 When the buffer associated with the terminal is wiped out the job is killed,
93 similar to calling `job_stop(job, "kill")` 110 similar to calling `job_stop(job, "kill")`
94 111
95 By default the 'bufhidden' option of the buffer will be set to "hide". 112 By default the 'bufhidden' option of the buffer will be set to "hide".
131 The |term_getsize()| function can be used to get the current size of the 148 The |term_getsize()| function can be used to get the current size of the
132 terminal. |term_setsize()| can be used only when in the first or second mode, 149 terminal. |term_setsize()| can be used only when in the first or second mode,
133 not when 'termsize' is "rowsXcols". 150 not when 'termsize' is "rowsXcols".
134 151
135 152
136 Terminal Normal mode ~ 153 Terminal-Job and Terminal-Normal mode ~
137 *Terminal-mode* 154 *Terminal-mode*
138 When the job is running the contents of the terminal is under control of the 155 When the job is running the contents of the terminal is under control of the
139 job. That includes the cursor position. The terminal contents can change at 156 job. That includes the cursor position. Typed keys are sent to the job.
140 any time. 157 The terminal contents can change at any time. This is called Terminal-Job
141 158 mode.
142 Use CTRL-W N (or 'termkey' N) to go to Terminal Normal mode. Now the contents 159
143 of the terminal window is under control of Vim, the job output is suspended. 160 Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode. Now the
161 contents of the terminal window is under control of Vim, the job output is
162 suspended. CTRL-\ CTRL-N does the same.
144 *E946* 163 *E946*
145 In this mode you can move the cursor around with the usual Vim commands, 164 In Terminal-Normal mode you can move the cursor around with the usual Vim
146 Visually mark text, yank text, etc. But you cannot change the contents of the 165 commands, Visually mark text, yank text, etc. But you cannot change the
147 buffer. The commands that would start insert mode, such as 'i' and 'a', 166 contents of the buffer. The commands that would start insert mode, such as
148 return control of the window to the job. Any pending output will now be 167 'i' and 'a', return to Terminal-Job mode. The window will be updated to show
149 displayed. 168 the contents of the terminal.
150 169
151 In Terminal mode the statusline and window title show "(Terminal)". If the 170 In Terminal-Normal mode the statusline and window title show "(Terminal)". If
152 job ends while in Terminal mode this changes to "(Terminal-finished)". 171 the job ends while in Terminal-Normal mode this changes to
172 "(Terminal-finished)".
153 173
154 174
155 Unix ~ 175 Unix ~
156 176
157 On Unix a pty is used to make it possible to run all kinds of commands. You 177 On Unix a pty is used to make it possible to run all kinds of commands. You