Mercurial > vim

annotate runtime/doc/terminal.txt @ 11993:92a86fe8adc0 v8.0.0877

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.0.0877: using CTRL- CTRL-N in terminal is inconsistent commit https://github.com/vim/vim/commit/6d8197485dc84532e37aced2c39292bff374200d Author: Bram Moolenaar <Bram@vim.org> Date: Sun Aug 6 14:57:49 2017 +0200 patch 8.0.0877: using CTRL-\ CTRL-N in terminal is inconsistent Problem: Using CTRL-\ CTRL-N in terminal is inconsistent. Solution: Stay in Normal mode.
author Christian Brabandt <cb@256bit.org>
date Sun, 06 Aug 2017 15:00:04 +0200
parents 12833414cc02
children 9897241c08b5
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11967
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents: 11965
diff changeset
1 *terminal.txt* For Vim version 8.0. Last change: 2017 Aug 05
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
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
39 When the keyboard focus is in the terminal window, typed keys will be send 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
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
50 CTRL-W N go to Terminal Normal mode, see |Terminal-mode|
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
51 CTRL-W " {reg} paste register {reg} *CTRL-W_quote*
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
52 Also works with the = register to insert the result of
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
53 evaluating an expression.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
54
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
55 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
56 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
57 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
58 '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
59 '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
60 '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
61 '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
62 '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
63 '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
64 *t_CTRL-\_CTRL-N*
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 The special key combination CTRL-\ CTRL-N can be used to prefix one Normal
a932d3da41c8 patch 8.0.0863: a remote command does not work in the terminal window
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
66 mode command. This is especially useful for remote commands, when you don't
a932d3da41c8 patch 8.0.0863: a remote command does not work in the terminal window
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
67 know whether Vim currently has focus in a terminal window. Note that only one
a932d3da41c8 patch 8.0.0863: a remote command does not work in the terminal window
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
68 Normal mode command can be used.
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
69
11814
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents: 11774
diff changeset
70
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents: 11774
diff changeset
71 Size ~
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
72
11659
49c12c93abf3 Updated runtime files and translations.
Christian Brabandt <cb@256bit.org>
parents: 11621
diff changeset
73 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
74 (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
75
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
76
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
77 Syntax ~
11774
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
78
11814
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents: 11774
diff changeset
79 :ter[minal] [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
80 Open a new terminal window.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
81
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
82 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
83 the input and output to the terminal.
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
84 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
85
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
86 A new buffer will be created, using [command] or
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
87 'shell' as the name, prefixed with a "!". If a buffer
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
88 by this name already exists a number is added in
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
89 parenthesis. E.g. if "gdb" exists the second terminal
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
90 buffer will use "!gdb (1)".
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
91
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
92 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
93 similar to calling `job_stop(job, "kill")`
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
94
11967
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents: 11965
diff changeset
95 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
96 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
97 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
98 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
99 changes this fails, use ! to force, as usual.
11967
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents: 11965
diff changeset
100 *E947*
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents: 11965
diff changeset
101 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
102 cannot be quit easily, see |abandon|.
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
103
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
104 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
105 window will wipe out the buffer.
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
106
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
107 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
108 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
109 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
110 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
111 the buffer name will still be set to the command.
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
112
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
113
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
114 Resizing ~
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
115
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
116 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
117
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
118 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
119 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
120
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
121 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
122 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
123
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
124 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
125 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
126 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
127
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
128 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
129 be seen (the lower-left part).
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
130
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
131 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
132 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
133 not when 'termsize' is "rowsXcols".
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
134
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
135
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
136 Terminal Normal 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
137 *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
138 When the job is running the contents of the terminal is under control of the
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
139 job. That includes the cursor position. The terminal contents can change at
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
140 any time.
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
141
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
142 Use CTRL-W N (or 'termkey' N) to go to Terminal Normal mode. Now the contents
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
143 of the terminal window is under control of Vim, the job output is suspended.
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
144 *E946*
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
145 In this mode you can move the cursor around with the usual Vim 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
146 Visually mark text, yank text, etc. But you cannot change the contents of the
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
147 buffer. The commands that would start insert mode, such as 'i' and 'a',
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
148 return control of the window to the job. Any pending output will now be
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
149 displayed.
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
150
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
151 In Terminal mode the statusline and window title show "(Terminal)". If the
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
152 job ends while in Terminal mode this changes to "(Terminal-finished)".
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
153
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
154
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
155 Unix ~
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
156
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
157 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
158 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
159
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
160 Environment variables are used to pass information to the running job:
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
161 TERM name of the terminal, 'term'
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
162 ROWS number of rows in the terminal initially
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
163 LINES same as ROWS
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
164 COLUMNS number of columns in the terminal initially
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
165 COLORS number of colors, 't_Co' (256*256*256 in the GUI)
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
166 VIM_SERVERNAME v:servername
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
167
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
168 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
169 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
170 If needed you can set it with: >
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
171 call remote_startserver('vim-server')
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
172
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
173 In the job you can then do something like: >
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
174 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
175 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
176
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
177
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
178 MS-Windows ~
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
179
11774
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
180 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
181 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
182 window.
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
183
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
184 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
185
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
186 winpty.dll
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
187 winpty-agent.exe
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
188
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
189 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
190
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
191 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
192
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
193 Just put the files somewhere in your PATH.
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
194
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
195 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
196 2. Remote testing *terminal-testing*
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
197
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
198 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
199 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
200 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
201 inspects the resulting screen state.
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
202
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
203 Functions ~
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
204
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
205 term_sendkeys() send keystrokes to a terminal
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
206 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
207 term_scrape() inspect terminal screen
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
208
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
209
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
210 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
211 3. Debugging *terminal-debug*
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
212
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
213 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
214 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
215
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
216 :TermDebug vim
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
217
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
218 This opens three windows:
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
219 - 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
220 interact with gdb.
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
221 - 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
222 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
223 controlling gdb.
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
224 - 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
225 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
226 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
227
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
228 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
229 :term gdb [arguments]
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
230 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
231
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
232 TODO
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
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
235 vim:tw=78:ts=8:ft=help:norl: