blob: 89689463ac483771879139bc88a9526041895af5 [file] [log] [blame]
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +02001*terminal.txt* For Vim version 8.0. Last change: 2017 Jul 28
Bram Moolenaare4f25e42017-07-07 11:54:15 +02002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Terminal window support *terminal*
8
9
10WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE
11
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +020012The terminal feature is optional, use this to check if your Vim has it: >
13 echo has('terminal')
14If the result is "1" you have it.
15
Bram Moolenaare4f25e42017-07-07 11:54:15 +020016
171. Basic use |terminal-use|
182. Remote testing |terminal-testing|
193. Debugging |terminal-debug|
20
21{Vi does not have any of these commands}
22
23==============================================================================
241. Basic use *terminal-use*
25
26This feature is for running a terminal emulator in a Vim window. A job can be
27started connected to the terminal emulator. For example, to run a shell: >
28 :term bash
29
30Or to run a debugger: >
31 :term gdb vim
32
33The job runs asynchronously from Vim, the window will be updated to show
34output from the job, also while editing in any other window.
35
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020036Typing ~
37
Bram Moolenaare4f25e42017-07-07 11:54:15 +020038When the keyboard focus is in the terminal window, typed keys will be send to
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020039the job. This uses a pty when possible. You can click outside of the
40terminal window to move keyboard focus elsewhere.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020041
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020042Navigate between windows with CTRL-W commands. E.g. CTRL-W CTRL-W moves focus
43to the next window. Use "CTRL-W :" to edit an Ex command. Use "CTRL-W ." to
44send a CTRL-W to the job in the terminal.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020045
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020046See option 'termkey' for specifying another key that precedes a Vim command.
47Typing 'termkey' twice sends 'termkey' to the job.
48
49Size ~
Bram Moolenaare4f25e42017-07-07 11:54:15 +020050
Bram Moolenaar74675a62017-07-15 13:53:23 +020051See option 'termsize' for controlling the size of the terminal window.
52(TODO: scrolling when the terminal is larger than the window)
Bram Moolenaare4f25e42017-07-07 11:54:15 +020053
54Syntax ~
Bram Moolenaar8a773062017-07-24 22:29:21 +020055
Bram Moolenaar1f28b4c2017-07-28 13:48:34 +020056:ter[minal] [command] *:ter* *:terminal*
Bram Moolenaar8a773062017-07-24 22:29:21 +020057 Open a new terminal window.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020058
59 If [command] is provided run it as a job and connect
60 the input and output to the terminal.
61 If [command] is not given the 'shell' option is used.
62
63 A new buffer will be created, using [command] or
64 'shell' as the name. If a buffer by this name already
65 exists a number is added in parenthesis.
66 E.g. if "gdb" exists the second terminal buffer will
67 use "gdb (1)".
68
69 The window can be closed, in which case the buffer
70 becomes hidden. The command will not be stopped. The
71 `:buffer` command can be used to turn the current
72 window into a terminal window, using the existing
73 buffer. If there are unsaved changes this fails, use
74 ! to force, as usual.
75
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +020076When the buffer associated with the terminal is wiped out the job is killed,
77similar to calling `job_stop(job, "kill")`
78
79
Bram Moolenaare4f25e42017-07-07 11:54:15 +020080Resizing ~
81
82The size of the terminal can be in one of three modes:
83
841. The 'termsize' option is empty: The terminal size follows the window size.
85 The minimal size is 2 screen lines with 10 cells.
86
872. The 'termsize' option is "rows*cols", where "rows" is the minimal number of
Bram Moolenaar8a773062017-07-24 22:29:21 +020088 screen rows and "cols" is the minimal number of cells.
Bram Moolenaare4f25e42017-07-07 11:54:15 +020089
903. The 'termsize' option is "rowsXcols" (where the x is upper or lower case).
91 The terminal size is fixed to the specified number of screen lines and
92 cells. If the window is bigger there will be unused empty space.
93
94If the window is smaller than the terminal size, only part of the terminal can
95be seen (the lower-left part).
96
97The |term_getsize()| function can be used to get the current size of the
98terminal. |term_setsize()| can be used only when in the first or second mode,
99not when 'termsize' is "rowsXcols".
100
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200101
102Unix ~
103
104On Unix a pty is used to make it possible to run all kinds of commands. You
105can even run Vim in the terminal! That's used for debugging, see below.
106
107
108MS-Windows ~
109
Bram Moolenaar8a773062017-07-24 22:29:21 +0200110On MS-Windows winpty is used to make it possible to run all kind of commands.
111Obviously, they must be commands that run in a terminal, not open their own
112window.
113
114You need the following two files from winpty:
115
116 winpty.dll
117 winpty-agent.exe
118
119You can download them from the following page:
120
121 https://github.com/rprichard/winpty
122
123Just put the files somewhere in your PATH.
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200124
Bram Moolenaare4f25e42017-07-07 11:54:15 +0200125==============================================================================
1262. Remote testing *terminal-testing*
127
128Most Vim tests execute a script inside Vim. For some tests this does not
129work, running the test interferes with the code being tested. To avoid this
130Vim is executed in a terminal window. The test sends keystrokes to it and
131inspects the resulting screen state.
132
133Functions ~
134
135term_sendkeys() send keystrokes to a terminal
136term_wait() wait for screen to be updated
137term_scrape() inspect terminal screen
138
139
140==============================================================================
1413. Debugging *terminal-debug*
142
143The Terminal debugging plugin can be used to debug a program with gdb and view
144the source code in a Vim window. For example: >
145
146 :TermDebug vim
147
148This opens three windows:
149- A terminal window in which "gdb vim" is executed. Here you can directly
150 interact with gdb.
151- A terminal window for the executed program. When "run" is used in gdb the
152 program I/O will happen in this window, so that it does not interfere with
153 controlling gdb.
154- A normal Vim window used to show the source code. When gdb jumps to a
155 source file location this window will display the code, if possible. Values
156 of variables can be inspected, breakpoints set and cleared, etc.
157
158This uses two terminal windows. To open the gdb window: >
159 :term gdb [arguments]
160To open the terminal to run the tested program |term_open()| is used.
161
162TODO
163
164
165 vim:tw=78:ts=8:ft=help:norl: