blob: 79d00a70b2242a05b6da4863e37ebeda98ad6c2c [file] [log] [blame]
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00001*windows.txt* For Vim version 8.2. Last change: 2022 Jan 08
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Editing with multiple windows and buffers. *windows* *buffers*
8
9The commands which have been added to use multiple windows and buffers are
10explained here. Additionally, there are explanations for commands that work
11differently when used in combination with more than one window.
12
13The basics are explained in chapter 7 and 8 of the user manual |usr_07.txt|
14|usr_08.txt|.
15
161. Introduction |windows-intro|
172. Starting Vim |windows-starting|
183. Opening and closing a window |opening-window|
194. Moving cursor to other windows |window-move-cursor|
205. Moving windows around |window-moving|
216. Window resizing |window-resize|
227. Argument and buffer list commands |buffer-list|
238. Do a command in all buffers or windows |list-repeat|
249. Tag or file name under the cursor |window-tag|
2510. The preview window |preview-window|
2611. Using hidden buffers |buffer-hidden|
2712. Special kinds of buffers |special-buffers|
28
Bram Moolenaar071d4272004-06-13 20:20:40 +000029{not able to use multiple windows when the |+windows| feature was disabled at
30compile time}
Bram Moolenaar071d4272004-06-13 20:20:40 +000031
32==============================================================================
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000331. Introduction *windows-intro* *window*
Bram Moolenaar071d4272004-06-13 20:20:40 +000034
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010035Summary:
36 A buffer is the in-memory text of a file.
37 A window is a viewport on a buffer.
38 A tab page is a collection of windows.
39
Bram Moolenaar071d4272004-06-13 20:20:40 +000040A window is a viewport onto a buffer. You can use multiple windows on one
41buffer, or several windows on different buffers.
42
43A buffer is a file loaded into memory for editing. The original file remains
44unchanged until you write the buffer to the file.
45
46A buffer can be in one of three states:
47
48 *active-buffer*
49active: The buffer is displayed in a window. If there is a file for this
50 buffer, it has been read into the buffer. The buffer may have been
51 modified since then and thus be different from the file.
52 *hidden-buffer*
53hidden: The buffer is not displayed. If there is a file for this buffer, it
54 has been read into the buffer. Otherwise it's the same as an active
55 buffer, you just can't see it.
56 *inactive-buffer*
57inactive: The buffer is not displayed and does not contain anything. Options
58 for the buffer are remembered if the file was once loaded. It can
59 contain marks from the |viminfo| file. But the buffer doesn't
60 contain text.
61
62In a table:
63
64state displayed loaded ":buffers" ~
65 in window shows ~
66active yes yes 'a'
67hidden no yes 'h'
68inactive no no ' '
69
70Note: All CTRL-W commands can also be executed with |:wincmd|, for those
71places where a Normal mode command can't be used or is inconvenient.
72
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000073The main Vim window can hold several split windows. There are also tab pages
74|tab-page|, each of which can hold multiple windows.
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +020075 *window-ID* *winid* *windowid*
Bram Moolenaarc95a3022016-06-12 23:01:46 +020076Each window has a unique identifier called the window ID. This identifier
77will not change within a Vim session. The |win_getid()| and |win_id2tabwin()|
78functions can be used to convert between the window/tab number and the
79identifier. There is also the window number, which may change whenever
80windows are opened or closed, see |winnr()|.
Bram Moolenaarba3ff532018-11-04 14:45:49 +010081The window number is only valid in one specific tab. The window ID is valid
82across tabs. For most functions that take a window ID or a window number, the
83window number only applies to the current tab, while the window ID can refer
84to a window in any tab.
Bram Moolenaarc95a3022016-06-12 23:01:46 +020085
86Each buffer has a unique number and the number will not change within a Vim
87session. The |bufnr()| and |bufname()| functions can be used to convert
88between a buffer name and the buffer number.
89
Bram Moolenaar071d4272004-06-13 20:20:40 +000090==============================================================================
912. Starting Vim *windows-starting*
92
93By default, Vim starts with one window, just like Vi.
94
95The "-o" and "-O" arguments to Vim can be used to open a window for each file
96in the argument list. The "-o" argument will split the windows horizontally;
97the "-O" argument will split the windows vertically. If both "-o" and "-O"
98are given, the last one encountered will be used to determine the split
99orientation. For example, this will open three windows, split horizontally: >
100 vim -o file1 file2 file3
101
102"-oN", where N is a decimal number, opens N windows split horizontally. If
103there are more file names than windows, only N windows are opened and some
104files do not get a window. If there are more windows than file names, the
105last few windows will be editing empty buffers. Similarly, "-ON" opens N
106windows split vertically, with the same restrictions.
107
108If there are many file names, the windows will become very small. You might
109want to set the 'winheight' and/or 'winwidth' options to create a workable
110situation.
111
112Buf/Win Enter/Leave |autocommand|s are not executed when opening the new
113windows and reading the files, that's only done when they are really entered.
114
115 *status-line*
116A status line will be used to separate windows. The 'laststatus' option tells
117when the last window also has a status line:
118 'laststatus' = 0 never a status line
119 'laststatus' = 1 status line if there is more than one window
120 'laststatus' = 2 always a status line
121
122You can change the contents of the status line with the 'statusline' option.
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000123This option can be local to the window, so that you can have a different
124status line in each window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000125
126Normally, inversion is used to display the status line. This can be changed
127with the 's' character in the 'highlight' option. For example, "sb" sets it to
128bold characters. If no highlighting is used for the status line ("sn"), the
129'^' character is used for the current window, and '=' for other windows. If
130the mouse is supported and enabled with the 'mouse' option, a status line can
131be dragged to resize windows.
132
133Note: If you expect your status line to be in reverse video and it isn't,
134check if the 'highlight' option contains "si". In version 3.0, this meant to
135invert the status line. Now it should be "sr", reverse the status line, as
136"si" now stands for italic! If italic is not available on your terminal, the
137status line is inverted anyway; you will only see this problem on terminals
138that have termcap codes for italics.
139
Bram Moolenaar65e0d772020-06-14 17:29:55 +0200140 *filler-lines*
Bram Moolenaara98f8a22021-02-13 18:24:23 +0100141The lines after the last buffer line in a window are called filler lines. By
142default, these lines start with a tilde (~) character. The 'eob' item in the
143'fillchars' option can be used to change this character. By default, these
144characters are highlighted as NonText (|hl-NonText|). The EndOfBuffer
145highlight group (|hl-EndOfBuffer|) can be used to change the highlighting of
146the filler characters.
Bram Moolenaar65e0d772020-06-14 17:29:55 +0200147
Bram Moolenaar071d4272004-06-13 20:20:40 +0000148==============================================================================
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00001493. Opening and closing a window *opening-window*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000150
151CTRL-W s *CTRL-W_s*
152CTRL-W S *CTRL-W_S*
153CTRL-W CTRL-S *CTRL-W_CTRL-S*
Bram Moolenaar7b449342014-03-25 13:03:48 +0100154:[N]sp[lit] [++opt] [+cmd] [file] *:sp* *:split*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000155 Split current window in two. The result is two viewports on
Bram Moolenaar7b449342014-03-25 13:03:48 +0100156 the same file.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100157
Bram Moolenaar7b449342014-03-25 13:03:48 +0100158 Make the new window N high (default is to use half the height
159 of the current window). Reduces the current window height to
160 create room (and others, if the 'equalalways' option is set,
161 'eadirection' isn't "hor", and one of them is higher than the
162 current or the new window).
163
164 If [file] is given it will be edited in the new window. If it
165 is not loaded in any buffer, it will be read. Else the new
166 window will use the already loaded buffer.
167
Bram Moolenaar071d4272004-06-13 20:20:40 +0000168 Note: CTRL-S does not work on all terminals and might block
169 further input, use CTRL-Q to get going again.
170 Also see |++opt| and |+cmd|.
Bram Moolenaar54775062019-07-31 21:07:14 +0200171 *E242*
172 Be careful when splitting a window in an autocommand, it may
173 mess up the window layout if this happens while making other
174 window layout changes.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000175
176CTRL-W CTRL-V *CTRL-W_CTRL-V*
177CTRL-W v *CTRL-W_v*
178:[N]vs[plit] [++opt] [+cmd] [file] *:vs* *:vsplit*
Bram Moolenaar67f71312007-08-12 14:55:56 +0000179 Like |:split|, but split vertically. The windows will be
180 spread out horizontally if
181 1. a width was not specified,
182 2. 'equalalways' is set,
183 3. 'eadirection' isn't "ver", and
Bram Moolenaarc1a11ed2008-06-24 22:09:24 +0000184 4. one of the other windows is wider than the current or new
Bram Moolenaar67f71312007-08-12 14:55:56 +0000185 window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000186 Note: In other places CTRL-Q does the same as CTRL-V, but here
187 it doesn't!
188
189CTRL-W n *CTRL-W_n*
190CTRL-W CTRL_N *CTRL-W_CTRL-N*
191:[N]new [++opt] [+cmd] *:new*
192 Create a new window and start editing an empty file in it.
193 Make new window N high (default is to use half the existing
194 height). Reduces the current window height to create room (and
195 others, if the 'equalalways' option is set and 'eadirection'
196 isn't "hor").
197 Also see |++opt| and |+cmd|.
198 If 'fileformats' is not empty, the first format given will be
199 used for the new buffer. If 'fileformats' is empty, the
200 'fileformat' of the current buffer is used. This can be
201 overridden with the |++opt| argument.
202 Autocommands are executed in this order:
203 1. WinLeave for the current window
204 2. WinEnter for the new window
205 3. BufLeave for the current buffer
206 4. BufEnter for the new buffer
Bram Moolenaar53bfca22012-04-13 23:04:47 +0200207 This behaves like a ":split" first, and then an ":enew"
208 command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000209
Bram Moolenaar071d4272004-06-13 20:20:40 +0000210:[N]new [++opt] [+cmd] {file}
211:[N]sp[lit] [++opt] [+cmd] {file} *:split_f*
Bram Moolenaar53bfca22012-04-13 23:04:47 +0200212 Create a new window and start editing file {file} in it. This
Bram Moolenaar942db232021-02-13 18:14:48 +0100213 behaves almost like a ":split" first, and then an ":edit"
214 command, but the alternate file name in the original window is
215 set to {file}.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000216 If [+cmd] is given, execute the command when the file has been
217 loaded |+cmd|.
218 Also see |++opt|.
219 Make new window N high (default is to use half the existing
220 height). Reduces the current window height to create room
221 (and others, if the 'equalalways' option is set).
222
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100223:[N]vne[w] [++opt] [+cmd] [file] *:vne* *:vnew*
224 Like |:new|, but split vertically. If 'equalalways' is set
225 and 'eadirection' isn't "ver" the windows will be spread out
226 horizontally, unless a width was specified.
227
Bram Moolenaarff781552020-03-19 20:37:11 +0100228:[N]sv[iew] [++opt] [+cmd] [file] *:sv* *:sview* *splitview*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000229 Same as ":split", but set 'readonly' option for this buffer.
230
Bram Moolenaar61da1bf2019-06-06 12:14:49 +0200231:[N]sf[ind] [++opt] [+cmd] {file} *:sf* *:sfi* *:sfind* *splitfind*
Bram Moolenaarc236c162008-07-13 17:41:49 +0000232 Same as ":split", but search for {file} in 'path' like in
233 |:find|. Doesn't split if {file} is not found.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000234
235CTRL-W CTRL-^ *CTRL-W_CTRL-^* *CTRL-W_^*
Bram Moolenaar1bbb6192018-11-10 16:02:01 +0100236CTRL-W ^ Split the current window in two and edit the alternate file.
237 When a count N is given, split the current window and edit
238 buffer N. Similar to ":sp #" and ":sp #N", but it allows the
239 other buffer to be unnamed. This command matches the behavior
240 of |CTRL-^|, except that it splits a window first.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000241
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200242 *CTRL-W_:*
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +0200243CTRL-W : Does the same as typing |:| - enter a command line. Useful in a
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200244 terminal window, where all Vim commands must be preceded with
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +0200245 CTRL-W or 'termwinkey'.
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200246
Bram Moolenaar071d4272004-06-13 20:20:40 +0000247Note that the 'splitbelow' and 'splitright' options influence where a new
248window will appear.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000249 *E36*
250Creating a window will fail if there is not enough room. Every window needs
251at least one screen line and column, sometimes more. Options 'winminheight'
252and 'winminwidth' are relevant.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000253
254 *:vert* *:vertical*
255:vert[ical] {cmd}
256 Execute {cmd}. If it contains a command that splits a window,
257 it will be split vertically.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000258 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000259
260:lefta[bove] {cmd} *:lefta* *:leftabove*
261:abo[veleft] {cmd} *:abo* *:aboveleft*
262 Execute {cmd}. If it contains a command that splits a window,
263 it will be opened left (vertical split) or above (horizontal
264 split) the current window. Overrules 'splitbelow' and
265 'splitright'.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000266 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000267
268:rightb[elow] {cmd} *:rightb* *:rightbelow*
269:bel[owright] {cmd} *:bel* *:belowright*
270 Execute {cmd}. If it contains a command that splits a window,
271 it will be opened right (vertical split) or below (horizontal
272 split) the current window. Overrules 'splitbelow' and
273 'splitright'.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000274 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000275
276 *:topleft* *E442*
277:to[pleft] {cmd}
278 Execute {cmd}. If it contains a command that splits a window,
279 it will appear at the top and occupy the full width of the Vim
280 window. When the split is vertical the window appears at the
281 far left and occupies the full height of the Vim window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000282 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000283
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200284 *:bo* *:botright*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000285:bo[tright] {cmd}
286 Execute {cmd}. If it contains a command that splits a window,
287 it will appear at the bottom and occupy the full width of the
288 Vim window. When the split is vertical the window appears at
289 the far right and occupies the full height of the Vim window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000290 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000291
292These command modifiers can be combined to make a vertically split window
293occupy the full height. Example: >
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200294 :vertical topleft split tags
Bram Moolenaar071d4272004-06-13 20:20:40 +0000295Opens a vertically split, full-height window on the "tags" file at the far
296left of the Vim window.
297
298
299Closing a window
300----------------
301
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100302:q[uit]
Bram Moolenaar6c391a72021-09-09 21:55:11 +0200303:{count}q[uit] *:count_quit*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000304CTRL-W q *CTRL-W_q*
305CTRL-W CTRL-Q *CTRL-W_CTRL-Q*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100306 Without {count}: Quit the current window. If {count} is
307 given quit the {count} window.
Bram Moolenaar47e13952020-05-12 22:49:12 +0200308 *edit-window*
309 When quitting the last edit window (not counting help or
310 preview windows), exit Vim.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100311
Bram Moolenaar071d4272004-06-13 20:20:40 +0000312 When 'hidden' is set, and there is only one window for the
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100313 current buffer, it becomes hidden. When 'hidden' is not set,
314 and there is only one window for the current buffer, and the
315 buffer was changed, the command fails.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100316
Bram Moolenaared32d942014-12-06 23:33:00 +0100317 (Note: CTRL-Q does not work on all terminals).
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100318
Bram Moolenaared32d942014-12-06 23:33:00 +0100319 If [count] is greater than the last window number the last
320 window will be closed: >
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100321 :1quit " quit the first window
322 :$quit " quit the last window
323 :9quit " quit the last window
Bram Moolenaar46fceaa2016-10-23 21:21:08 +0200324 " if there are fewer than 9 windows opened
325 :-quit " quit the previous window
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100326 :+quit " quit the next window
Bram Moolenaared32d942014-12-06 23:33:00 +0100327 :+2quit " quit the second next window
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100328<
Bram Moolenaar47e13952020-05-12 22:49:12 +0200329 When closing a help window, and this is not the only window,
330 Vim will try to restore the previous window layout, see
331 |:helpclose|.
Bram Moolenaar96f45c02019-10-26 19:53:45 +0200332
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100333:q[uit]!
334:{count}q[uit]!
335 Without {count}: Quit the current window. If {count} is
336 given quit the {count} window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000337
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100338 If this was the last window for a buffer, any changes to that
339 buffer are lost. When quitting the last window (not counting
340 help windows), exit Vim. The contents of the buffer are lost,
341 even when 'hidden' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000342
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100343:clo[se][!]
344:{count}clo[se][!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000345CTRL-W c *CTRL-W_c* *:clo* *:close*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100346 Without {count}: Close the current window. If {count} is
347 given close the {count} window.
348
349 When the 'hidden' option is set, or when the buffer was
350 changed and the [!] is used, the buffer becomes hidden (unless
351 there is another window editing it).
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100352
Bram Moolenaar47e13952020-05-12 22:49:12 +0200353 When there is only one |edit-window| in the current tab page
354 and there is another tab page, this closes the current tab
355 page. |tab-page|.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100356
Bram Moolenaar071d4272004-06-13 20:20:40 +0000357 This command fails when: *E444*
358 - There is only one window on the screen.
359 - When 'hidden' is not set, [!] is not used, the buffer has
360 changes, and there is no other window on this buffer.
361 Changes to the buffer are not written and won't get lost, so
362 this is a "safe" command.
363
364CTRL-W CTRL-C *CTRL-W_CTRL-C*
365 You might have expected that CTRL-W CTRL-C closes the current
366 window, but that does not work, because the CTRL-C cancels the
367 command.
368
369 *:hide*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100370:hid[e]
371:{count}hid[e]
Bram Moolenaarc572da52017-08-27 16:52:01 +0200372 Without {count}: Quit the current window, unless it is the
373 last window on the screen.
374 If {count} is given quit the {count} window.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100375
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100376 The buffer becomes hidden (unless there is another window
Bram Moolenaared32d942014-12-06 23:33:00 +0100377 editing it or 'bufhidden' is "unload", "delete" or "wipe").
378 If the window is the last one in the current tab page the tab
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100379 page is closed. |tab-page|
380
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100381 The value of 'hidden' is irrelevant for this command. Changes
382 to the buffer are not written and won't get lost, so this is a
383 "safe" command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000384
385:hid[e] {cmd} Execute {cmd} with 'hidden' is set. The previous value of
386 'hidden' is restored after {cmd} has been executed.
387 Example: >
388 :hide edit Makefile
389< This will edit "Makefile", and hide the current buffer if it
390 has any changes.
391
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100392:on[ly][!]
393:{count}on[ly][!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000394CTRL-W o *CTRL-W_o* *E445*
395CTRL-W CTRL-O *CTRL-W_CTRL-O* *:on* *:only*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100396 Make the current window the only one on the screen. All other
Bram Moolenaar6c391a72021-09-09 21:55:11 +0200397 windows are closed. For {count} see the `:quit` command
398 above |:count_quit|.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100399
Bram Moolenaar071d4272004-06-13 20:20:40 +0000400 When the 'hidden' option is set, all buffers in closed windows
401 become hidden.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100402
Bram Moolenaar071d4272004-06-13 20:20:40 +0000403 When 'hidden' is not set, and the 'autowrite' option is set,
404 modified buffers are written. Otherwise, windows that have
405 buffers that are modified are not removed, unless the [!] is
406 given, then they become hidden. But modified buffers are
407 never abandoned, so changes cannot get lost.
408
409==============================================================================
4104. Moving cursor to other windows *window-move-cursor*
411
412CTRL-W <Down> *CTRL-W_<Down>*
413CTRL-W CTRL-J *CTRL-W_CTRL-J* *CTRL-W_j*
414CTRL-W j Move cursor to Nth window below current one. Uses the cursor
415 position to select between alternatives.
416
417CTRL-W <Up> *CTRL-W_<Up>*
418CTRL-W CTRL-K *CTRL-W_CTRL-K* *CTRL-W_k*
419CTRL-W k Move cursor to Nth window above current one. Uses the cursor
420 position to select between alternatives.
421
422CTRL-W <Left> *CTRL-W_<Left>*
423CTRL-W CTRL-H *CTRL-W_CTRL-H*
424CTRL-W <BS> *CTRL-W_<BS>* *CTRL-W_h*
425CTRL-W h Move cursor to Nth window left of current one. Uses the
426 cursor position to select between alternatives.
427
428CTRL-W <Right> *CTRL-W_<Right>*
429CTRL-W CTRL-L *CTRL-W_CTRL-L* *CTRL-W_l*
430CTRL-W l Move cursor to Nth window right of current one. Uses the
431 cursor position to select between alternatives.
432
433CTRL-W w *CTRL-W_w* *CTRL-W_CTRL-W*
434CTRL-W CTRL-W Without count: move cursor to window below/right of the
435 current one. If there is no window below or right, go to
436 top-left window.
437 With count: go to Nth window (windows are numbered from
438 top-left to bottom-right). To obtain the window number see
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100439 |bufwinnr()| and |winnr()|. When N is larger than the number
440 of windows go to the last window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000441
442 *CTRL-W_W*
443CTRL-W W Without count: move cursor to window above/left of current
444 one. If there is no window above or left, go to bottom-right
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100445 window. With count: go to Nth window, like with CTRL-W w.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000446
447CTRL-W t *CTRL-W_t* *CTRL-W_CTRL-T*
448CTRL-W CTRL-T Move cursor to top-left window.
449
450CTRL-W b *CTRL-W_b* *CTRL-W_CTRL-B*
451CTRL-W CTRL-B Move cursor to bottom-right window.
452
453CTRL-W p *CTRL-W_p* *CTRL-W_CTRL-P*
454CTRL-W CTRL-P Go to previous (last accessed) window.
455
456 *CTRL-W_P* *E441*
457CTRL-W P Go to preview window. When there is no preview window this is
458 an error.
459 {not available when compiled without the |+quickfix| feature}
460
461If Visual mode is active and the new window is not for the same buffer, the
462Visual mode is ended. If the window is on the same buffer, the cursor
463position is set to keep the same Visual area selected.
464
465 *:winc* *:wincmd*
466These commands can also be executed with ":wincmd":
467
468:[count]winc[md] {arg}
469 Like executing CTRL-W [count] {arg}. Example: >
470 :wincmd j
471< Moves to the window below the current one.
472 This command is useful when a Normal mode cannot be used (for
473 the |CursorHold| autocommand event). Or when a Normal mode
474 command is inconvenient.
475 The count can also be a window number. Example: >
476 :exe nr . "wincmd w"
477< This goes to window "nr".
478
479==============================================================================
4805. Moving windows around *window-moving*
481
482CTRL-W r *CTRL-W_r* *CTRL-W_CTRL-R* *E443*
483CTRL-W CTRL-R Rotate windows downwards/rightwards. The first window becomes
484 the second one, the second one becomes the third one, etc.
485 The last window becomes the first window. The cursor remains
486 in the same window.
487 This only works within the row or column of windows that the
488 current window is in.
489
490 *CTRL-W_R*
491CTRL-W R Rotate windows upwards/leftwards. The second window becomes
492 the first one, the third one becomes the second one, etc. The
493 first window becomes the last window. The cursor remains in
494 the same window.
495 This only works within the row or column of windows that the
496 current window is in.
497
498CTRL-W x *CTRL-W_x* *CTRL-W_CTRL-X*
499CTRL-W CTRL-X Without count: Exchange current window with next one. If there
500 is no next window, exchange with previous window.
501 With count: Exchange current window with Nth window (first
502 window is 1). The cursor is put in the other window.
503 When vertical and horizontal window splits are mixed, the
504 exchange is only done in the row or column of windows that the
505 current window is in.
506
507The following commands can be used to change the window layout. For example,
508when there are two vertically split windows, CTRL-W K will change that in
509horizontally split windows. CTRL-W H does it the other way around.
510
511 *CTRL-W_K*
512CTRL-W K Move the current window to be at the very top, using the full
513 width of the screen. This works like closing the current
514 window and then creating another one with ":topleft split",
515 except that the current window contents is used for the new
516 window.
517
518 *CTRL-W_J*
519CTRL-W J Move the current window to be at the very bottom, using the
520 full width of the screen. This works like closing the current
521 window and then creating another one with ":botright split",
522 except that the current window contents is used for the new
523 window.
524
525 *CTRL-W_H*
526CTRL-W H Move the current window to be at the far left, using the
527 full height of the screen. This works like closing the
528 current window and then creating another one with
Bram Moolenaar56994d22021-04-17 16:31:09 +0200529 `:vert topleft split`, except that the current window contents
Bram Moolenaar071d4272004-06-13 20:20:40 +0000530 is used for the new window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000531
532 *CTRL-W_L*
533CTRL-W L Move the current window to be at the far right, using the full
534 height of the screen. This works like closing the
535 current window and then creating another one with
Bram Moolenaar56994d22021-04-17 16:31:09 +0200536 `:vert botright split`, except that the current window
Bram Moolenaar071d4272004-06-13 20:20:40 +0000537 contents is used for the new window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000538
Bram Moolenaar4c3f5362006-04-11 21:38:50 +0000539 *CTRL-W_T*
540CTRL-W T Move the current window to a new tab page. This fails if
541 there is only one window in the current tab page.
542 When a count is specified the new tab page will be opened
543 before the tab page with this index. Otherwise it comes after
544 the current tab page.
545
Bram Moolenaar071d4272004-06-13 20:20:40 +0000546==============================================================================
5476. Window resizing *window-resize*
548
549 *CTRL-W_=*
550CTRL-W = Make all windows (almost) equally high and wide, but use
551 'winheight' and 'winwidth' for the current window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000552 Windows with 'winfixheight' set keep their height and windows
553 with 'winfixwidth' set keep their width.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000554
555:res[ize] -N *:res* *:resize* *CTRL-W_-*
556CTRL-W - Decrease current window height by N (default 1).
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200557 If used after |:vertical|: decrease width by N.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000558
559:res[ize] +N *CTRL-W_+*
560CTRL-W + Increase current window height by N (default 1).
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200561 If used after |:vertical|: increase width by N.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000562
563:res[ize] [N]
564CTRL-W CTRL-_ *CTRL-W_CTRL-_* *CTRL-W__*
565CTRL-W _ Set current window height to N (default: highest possible).
566
Bram Moolenaar1ff14ba2019-11-02 14:09:23 +0100567:{winnr}res[ize] [+-]N
568 Like `:resize` above, but apply the size to window {winnr}
569 instead of the current window.
570
Bram Moolenaar071d4272004-06-13 20:20:40 +0000571z{nr}<CR> Set current window height to {nr}.
572
573 *CTRL-W_<*
574CTRL-W < Decrease current window width by N (default 1).
575
576 *CTRL-W_>*
577CTRL-W > Increase current window width by N (default 1).
578
Bram Moolenaar56994d22021-04-17 16:31:09 +0200579:vert[ical] res[ize] [N] *:vertical-resize* *CTRL-W_bar*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000580CTRL-W | Set current window width to N (default: widest possible).
581
582You can also resize a window by dragging a status line up or down with the
583mouse. Or by dragging a vertical separator line left or right. This only
584works if the version of Vim that is being used supports the mouse and the
585'mouse' option has been set to enable it.
586
587The option 'winheight' ('wh') is used to set the minimal window height of the
588current window. This option is used each time another window becomes the
589current window. If the option is '0', it is disabled. Set 'winheight' to a
590very large value, e.g., '9999', to make the current window always fill all
591available space. Set it to a reasonable value, e.g., '10', to make editing in
592the current window comfortable.
593
594The equivalent 'winwidth' ('wiw') option is used to set the minimal width of
595the current window.
596
597When the option 'equalalways' ('ea') is set, all the windows are automatically
598made the same size after splitting or closing a window. If you don't set this
599option, splitting a window will reduce the size of the current window and
600leave the other windows the same. When closing a window, the extra lines are
601given to the window above it.
602
603The 'eadirection' option limits the direction in which the 'equalalways'
604option is applied. The default "both" resizes in both directions. When the
605value is "ver" only the heights of windows are equalized. Use this when you
606have manually resized a vertically split window and want to keep this width.
607Likewise, "hor" causes only the widths of windows to be equalized.
608
609The option 'cmdheight' ('ch') is used to set the height of the command-line.
610If you are annoyed by the |hit-enter| prompt for long messages, set this
611option to 2 or 3.
612
613If there is only one window, resizing that window will also change the command
614line height. If there are several windows, resizing the current window will
615also change the height of the window below it (and sometimes the window above
616it).
617
618The minimal height and width of a window is set with 'winminheight' and
619'winminwidth'. These are hard values, a window will never become smaller.
620
621==============================================================================
6227. Argument and buffer list commands *buffer-list*
623
624 args list buffer list meaning ~
6251. :[N]argument [N] 11. :[N]buffer [N] to arg/buf N
6262. :[N]next [file ..] 12. :[N]bnext [N] to Nth next arg/buf
6273. :[N]Next [N] 13. :[N]bNext [N] to Nth previous arg/buf
6284. :[N]previous [N] 14. :[N]bprevious [N] to Nth previous arg/buf
6295. :rewind / :first 15. :brewind / :bfirst to first arg/buf
6306. :last 16. :blast to last arg/buf
6317. :all 17. :ball edit all args/buffers
632 18. :unhide edit all loaded buffers
633 19. :[N]bmod [N] to Nth modified buf
634
635 split & args list split & buffer list meaning ~
63621. :[N]sargument [N] 31. :[N]sbuffer [N] split + to arg/buf N
63722. :[N]snext [file ..] 32. :[N]sbnext [N] split + to Nth next arg/buf
63823. :[N]sNext [N] 33. :[N]sbNext [N] split + to Nth previous arg/buf
63924. :[N]sprevious [N] 34. :[N]sbprevious [N] split + to Nth previous arg/buf
64025. :srewind / :sfirst 35. :sbrewind / :sbfirst split + to first arg/buf
64126. :slast 36. :sblast split + to last arg/buf
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000064227. :sall 37. :sball edit all args/buffers
Bram Moolenaar071d4272004-06-13 20:20:40 +0000643 38. :sunhide edit all loaded buffers
644 39. :[N]sbmod [N] split + to Nth modified buf
645
64640. :args list of arguments
64741. :buffers list of buffers
648
649The meaning of [N] depends on the command:
Bram Moolenaar24a98a02017-09-27 22:23:55 +0200650 [N] is the number of buffers to go forward/backward on 2/12/22/32,
651 3/13/23/33, and 4/14/24/34
Bram Moolenaar071d4272004-06-13 20:20:40 +0000652 [N] is an argument number, defaulting to current argument, for 1 and 21
653 [N] is a buffer number, defaulting to current buffer, for 11 and 31
654 [N] is a count for 19 and 39
655
656Note: ":next" is an exception, because it must accept a list of file names
657for compatibility with Vi.
658
659
660The argument list and multiple windows
661--------------------------------------
662
663The current position in the argument list can be different for each window.
664Remember that when doing ":e file", the position in the argument list stays
665the same, but you are not editing the file at that position. To indicate
666this, the file message (and the title, if you have one) shows
667"(file (N) of M)", where "(N)" is the current position in the file list, and
668"M" the number of files in the file list.
669
670All the entries in the argument list are added to the buffer list. Thus, you
671can also get to them with the buffer list commands, like ":bnext".
672
673:[N]al[l][!] [N] *:al* *:all* *:sal* *:sall*
674:[N]sal[l][!] [N]
675 Rearrange the screen to open one window for each argument.
676 All other windows are closed. When a count is given, this is
677 the maximum number of windows to open.
Bram Moolenaarfd2ac762006-03-01 22:09:21 +0000678 With the |:tab| modifier open a tab page for each argument.
679 When there are more arguments than 'tabpagemax' further ones
680 become split windows in the last tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000681 When the 'hidden' option is set, all buffers in closed windows
682 become hidden.
683 When 'hidden' is not set, and the 'autowrite' option is set,
684 modified buffers are written. Otherwise, windows that have
685 buffers that are modified are not removed, unless the [!] is
686 given, then they become hidden. But modified buffers are
687 never abandoned, so changes cannot get lost.
688 [N] is the maximum number of windows to open. 'winheight'
689 also limits the number of windows opened ('winwidth' if
690 |:vertical| was prepended).
691 Buf/Win Enter/Leave autocommands are not executed for the new
692 windows here, that's only done when they are really entered.
Bram Moolenaar54775062019-07-31 21:07:14 +0200693 If autocommands change the window layout while this command is
694 busy an error will be given. *E249*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000695
696:[N]sa[rgument][!] [++opt] [+cmd] [N] *:sa* *:sargument*
697 Short for ":split | argument [N]": split window and go to Nth
698 argument. But when there is no such argument, the window is
699 not split. Also see |++opt| and |+cmd|.
700
701:[N]sn[ext][!] [++opt] [+cmd] [file ..] *:sn* *:snext*
702 Short for ":split | [N]next": split window and go to Nth next
703 argument. But when there is no next file, the window is not
704 split. Also see |++opt| and |+cmd|.
705
706:[N]spr[evious][!] [++opt] [+cmd] [N] *:spr* *:sprevious*
707:[N]sN[ext][!] [++opt] [+cmd] [N] *:sN* *:sNext*
708 Short for ":split | [N]Next": split window and go to Nth
709 previous argument. But when there is no previous file, the
710 window is not split. Also see |++opt| and |+cmd|.
711
712 *:sre* *:srewind*
713:sre[wind][!] [++opt] [+cmd]
714 Short for ":split | rewind": split window and go to first
715 argument. But when there is no argument list, the window is
716 not split. Also see |++opt| and |+cmd|.
717
718 *:sfir* *:sfirst*
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000719:sfir[st] [++opt] [+cmd]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000720 Same as ":srewind".
721
722 *:sla* *:slast*
723:sla[st][!] [++opt] [+cmd]
724 Short for ":split | last": split window and go to last
725 argument. But when there is no argument list, the window is
726 not split. Also see |++opt| and |+cmd|.
727
728 *:dr* *:drop*
Bram Moolenaared39e1d2008-08-09 17:55:22 +0000729:dr[op] [++opt] [+cmd] {file} ..
Bram Moolenaar071d4272004-06-13 20:20:40 +0000730 Edit the first {file} in a window.
731 - If the file is already open in a window change to that
732 window.
733 - If the file is not open in a window edit the file in the
734 current window. If the current buffer can't be |abandon|ed,
735 the window is split first.
Bram Moolenaar51628222016-12-01 23:03:28 +0100736 - Windows that are not in the argument list or are not full
737 width will be closed if possible.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000738 The |argument-list| is set, like with the |:next| command.
739 The purpose of this command is that it can be used from a
740 program that wants Vim to edit another file, e.g., a debugger.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000741 When using the |:tab| modifier each argument is opened in a
742 tab page. The last window is used if it's empty.
Bram Moolenaared39e1d2008-08-09 17:55:22 +0000743 Also see |++opt| and |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000744
745==============================================================================
7468. Do a command in all buffers or windows *list-repeat*
747
748 *:windo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100749:[range]windo {cmd} Execute {cmd} in each window or if [range] is given
750 only in windows for which the window number lies in
751 the [range]. It works like doing this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000752 CTRL-W t
753 :{cmd}
754 CTRL-W w
755 :{cmd}
756 etc.
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000757< This only operates in the current tab page.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000758 When an error is detected on one window, further
Bram Moolenaar071d4272004-06-13 20:20:40 +0000759 windows will not be visited.
760 The last window (or where an error occurred) becomes
761 the current window.
762 {cmd} can contain '|' to concatenate several commands.
763 {cmd} must not open or close windows or reorder them.
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200764
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200765 Also see |:tabdo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|,
766 |:cfdo| and |:lfdo|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000767
768 *:bufdo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100769:[range]bufdo[!] {cmd} Execute {cmd} in each buffer in the buffer list or if
770 [range] is given only for buffers for which their
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100771 buffer number is in the [range]. It works like doing
Bram Moolenaara162bc52015-01-07 16:54:21 +0100772 this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000773 :bfirst
774 :{cmd}
775 :bnext
776 :{cmd}
777 etc.
778< When the current file can't be |abandon|ed and the [!]
779 is not present, the command fails.
780 When an error is detected on one buffer, further
781 buffers will not be visited.
782 Unlisted buffers are skipped.
783 The last buffer (or where an error occurred) becomes
784 the current buffer.
785 {cmd} can contain '|' to concatenate several commands.
786 {cmd} must not delete buffers or add buffers to the
787 buffer list.
788 Note: While this command is executing, the Syntax
789 autocommand event is disabled by adding it to
790 'eventignore'. This considerably speeds up editing
791 each buffer.
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200792
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200793 Also see |:tabdo|, |:argdo|, |:windo|, |:cdo|, |:ldo|,
794 |:cfdo| and |:lfdo|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000795
796Examples: >
797
Bram Moolenaardad44732021-03-31 20:07:33 +0200798 :windo set nolist foldcolumn=0 | normal! zn
Bram Moolenaar071d4272004-06-13 20:20:40 +0000799
800This resets the 'list' option and disables folding in all windows. >
801
802 :bufdo set fileencoding= | update
803
804This resets the 'fileencoding' in each buffer and writes it if this changed
805the buffer. The result is that all buffers will use the 'encoding' encoding
Bram Moolenaardad44732021-03-31 20:07:33 +0200806(if conversion succeeds).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000807
808==============================================================================
8099. Tag or file name under the cursor *window-tag*
810
811 *:sta* *:stag*
812:sta[g][!] [tagname]
813 Does ":tag[!] [tagname]" and splits the window for the found
814 tag. See also |:tag|.
815
816CTRL-W ] *CTRL-W_]* *CTRL-W_CTRL-]*
817CTRL-W CTRL-] Split current window in two. Use identifier under cursor as a
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200818 tag and jump to it in the new upper window.
819 In Visual mode uses the Visually selected text as a tag.
820 Make new window N high.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000821
822 *CTRL-W_g]*
823CTRL-W g ] Split current window in two. Use identifier under cursor as a
824 tag and perform ":tselect" on it in the new upper window.
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200825 In Visual mode uses the Visually selected text as a tag.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000826 Make new window N high.
827
828 *CTRL-W_g_CTRL-]*
829CTRL-W g CTRL-] Split current window in two. Use identifier under cursor as a
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200830 tag and perform ":tjump" on it in the new upper window.
831 In Visual mode uses the Visually selected text as a tag.
832 Make new window N high.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000833
834CTRL-W f *CTRL-W_f* *CTRL-W_CTRL-F*
835CTRL-W CTRL-F Split current window in two. Edit file name under cursor.
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000836 Like ":split gf", but window isn't split if the file does not
Bram Moolenaar071d4272004-06-13 20:20:40 +0000837 exist.
838 Uses the 'path' variable as a list of directory names where to
839 look for the file. Also the path for current file is
840 used to search for the file name.
841 If the name is a hypertext link that looks like
842 "type://machine/path", only "/path" is used.
843 If a count is given, the count'th matching file is edited.
844 {not available when the |+file_in_path| feature was disabled
845 at compile time}
846
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000847CTRL-W F *CTRL-W_F*
848 Split current window in two. Edit file name under cursor and
849 jump to the line number following the file name. See |gF| for
850 details on how the line number is obtained.
Bram Moolenaar57657d82006-04-21 22:12:41 +0000851 {not available when the |+file_in_path| feature was disabled
852 at compile time}
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000853
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000854CTRL-W gf *CTRL-W_gf*
855 Open a new tab page and edit the file name under the cursor.
856 Like "tab split" and "gf", but the new tab page isn't created
857 if the file does not exist.
858 {not available when the |+file_in_path| feature was disabled
859 at compile time}
860
Bram Moolenaar57657d82006-04-21 22:12:41 +0000861CTRL-W gF *CTRL-W_gF*
862 Open a new tab page and edit the file name under the cursor
863 and jump to the line number following the file name. Like
864 "tab split" and "gF", but the new tab page isn't created if
865 the file does not exist.
866 {not available when the |+file_in_path| feature was disabled
867 at compile time}
868
Bram Moolenaar26967612019-03-17 17:13:16 +0100869CTRL-W gt *CTRL-W_gt*
870 Go to next tab page, same as `gt`.
871
872CTRL-W gT *CTRL-W_gT*
873 Go to previous tab page, same as `gT`.
874
Bram Moolenaar071d4272004-06-13 20:20:40 +0000875Also see |CTRL-W_CTRL-I|: open window for an included file that includes
876the keyword under the cursor.
877
878==============================================================================
87910. The preview window *preview-window*
880
881The preview window is a special window to show (preview) another file. It is
882normally a small window used to show an include file or definition of a
883function.
884{not available when compiled without the |+quickfix| feature}
885
Bram Moolenaarc270d802006-03-11 21:29:41 +0000886There can be only one preview window (per tab page). It is created with one
887of the commands below. The 'previewheight' option can be set to specify the
888height of the preview window when it's opened. The 'previewwindow' option is
889set in the preview window to be able to recognize it. The 'winfixheight'
890option is set to have it keep the same height when opening/closing other
891windows.
Bram Moolenaar79648732019-07-18 21:43:07 +0200892 *preview-popup*
893Alternatively, a popup window can be used by setting the 'previewpopup'
894option. When set, it overrules the 'previewwindow' and 'previewheight'
895settings. The option is a comma separated list of values:
896 height maximum height of the popup
Bram Moolenaar85850f32019-07-19 22:05:51 +0200897 width maximum width of the popup
Bram Moolenaar06fe74a2019-08-31 16:20:32 +0200898 highlight highlight group of the popup (default is Pmenu)
Bram Moolenaar79648732019-07-18 21:43:07 +0200899Example: >
900 :set previewpopup=height:10,width:60
Bram Moolenaar2debf1c2019-08-04 20:44:19 +0200901
902A few peculiarities:
903- If the file is in a buffer already, it will be re-used. This will allow for
904 editing the file while it's visible in the popup window.
905- No ATTENTION dialog will be used, since you can't edit the file in the popup
906 window. However, if you later open the same buffer in a normal window, you
907 may not notice it's edited elsewhere. And when then using ":edit" to
908 trigger the ATTENTION and responding "A" for Abort, the preview window will
909 become empty.
910
Bram Moolenaar071d4272004-06-13 20:20:40 +0000911 *:pta* *:ptag*
912:pta[g][!] [tagname]
913 Does ":tag[!] [tagname]" and shows the found tag in a
914 "Preview" window without changing the current buffer or cursor
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000915 position. If a "Preview" window already exists, it is re-used
Bram Moolenaar071d4272004-06-13 20:20:40 +0000916 (like a help window is). If a new one is opened,
917 'previewheight' is used for the height of the window. See
918 also |:tag|.
919 See below for an example. |CursorHold-example|
920 Small difference from |:tag|: When [tagname] is equal to the
921 already displayed tag, the position in the matching tag list
922 is not reset. This makes the CursorHold example work after a
923 |:ptnext|.
924
925CTRL-W z *CTRL-W_z*
926CTRL-W CTRL-Z *CTRL-W_CTRL-Z* *:pc* *:pclose*
927:pc[lose][!] Close any "Preview" window currently open. When the 'hidden'
928 option is set, or when the buffer was changed and the [!] is
929 used, the buffer becomes hidden (unless there is another
930 window editing it). The command fails if any "Preview" buffer
931 cannot be closed. See also |:close|.
932
933 *:pp* *:ppop*
934:[count]pp[op][!]
935 Does ":[count]pop[!]" in the preview window. See |:pop| and
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200936 |:ptag|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000937
938CTRL-W } *CTRL-W_}*
939 Use identifier under cursor as a tag and perform a :ptag on
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000940 it. Make the new Preview window (if required) N high. If N is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000941 not given, 'previewheight' is used.
942
943CTRL-W g } *CTRL-W_g}*
944 Use identifier under cursor as a tag and perform a :ptjump on
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000945 it. Make the new Preview window (if required) N high. If N is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000946 not given, 'previewheight' is used.
947
948 *:ped* *:pedit*
949:ped[it][!] [++opt] [+cmd] {file}
950 Edit {file} in the preview window. The preview window is
951 opened like with |:ptag|. The current window and cursor
952 position isn't changed. Useful example: >
953 :pedit +/fputc /usr/include/stdio.h
954<
955 *:ps* *:psearch*
956:[range]ps[earch][!] [count] [/]pattern[/]
957 Works like |:ijump| but shows the found match in the preview
958 window. The preview window is opened like with |:ptag|. The
959 current window and cursor position isn't changed. Useful
960 example: >
961 :psearch popen
962< Like with the |:ptag| command, you can use this to
963 automatically show information about the word under the
964 cursor. This is less clever than using |:ptag|, but you don't
965 need a tags file and it will also find matches in system
966 include files. Example: >
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200967 :au! CursorHold *.[ch] ++nested exe "silent! psearch " . expand("<cword>")
Bram Moolenaar071d4272004-06-13 20:20:40 +0000968< Warning: This can be slow.
969
970Example *CursorHold-example* >
971
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200972 :au! CursorHold *.[ch] ++nested exe "silent! ptag " . expand("<cword>")
Bram Moolenaar071d4272004-06-13 20:20:40 +0000973
974This will cause a ":ptag" to be executed for the keyword under the cursor,
975when the cursor hasn't moved for the time set with 'updatetime'. The "nested"
976makes other autocommands be executed, so that syntax highlighting works in the
977preview window. The "silent!" avoids an error message when the tag could not
978be found. Also see |CursorHold|. To disable this again: >
979
980 :au! CursorHold
981
982A nice addition is to highlight the found tag, avoid the ":ptag" when there
983is no word under the cursor, and a few other things: >
984
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200985 :au! CursorHold *.[ch] ++nested call PreviewWord()
Bram Moolenaar071d4272004-06-13 20:20:40 +0000986 :func PreviewWord()
987 : if &previewwindow " don't do this in the preview window
988 : return
989 : endif
990 : let w = expand("<cword>") " get the word under cursor
991 : if w =~ '\a' " if the word contains a letter
992 :
993 : " Delete any existing highlight before showing another tag
994 : silent! wincmd P " jump to preview window
995 : if &previewwindow " if we really get there...
996 : match none " delete existing highlight
997 : wincmd p " back to old window
998 : endif
999 :
1000 : " Try displaying a matching tag for the word under the cursor
1001 : try
1002 : exe "ptag " . w
1003 : catch
1004 : return
1005 : endtry
1006 :
1007 : silent! wincmd P " jump to preview window
1008 : if &previewwindow " if we really get there...
1009 : if has("folding")
1010 : silent! .foldopen " don't want a closed fold
1011 : endif
1012 : call search("$", "b") " to end of previous line
1013 : let w = substitute(w, '\\', '\\\\', "")
1014 : call search('\<\V' . w . '\>') " position cursor on match
1015 : " Add a match highlight to the word at this position
1016 : hi previewWord term=bold ctermbg=green guibg=green
1017 : exe 'match previewWord "\%' . line(".") . 'l\%' . col(".") . 'c\k*"'
1018 : wincmd p " back to old window
1019 : endif
1020 : endif
1021 :endfun
1022
1023==============================================================================
102411. Using hidden buffers *buffer-hidden*
1025
1026A hidden buffer is not displayed in a window, but is still loaded into memory.
1027This makes it possible to jump from file to file, without the need to read or
1028write the file every time you get another buffer in a window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001029
1030 *:buffer-!*
1031If the option 'hidden' ('hid') is set, abandoned buffers are kept for all
1032commands that start editing another file: ":edit", ":next", ":tag", etc. The
1033commands that move through the buffer list sometimes make the current buffer
1034hidden although the 'hidden' option is not set. This happens when a buffer is
1035modified, but is forced (with '!') to be removed from a window, and
1036'autowrite' is off or the buffer can't be written.
1037
1038You can make a hidden buffer not hidden by starting to edit it with any
1039command. Or by deleting it with the ":bdelete" command.
1040
1041The 'hidden' is global, it is used for all buffers. The 'bufhidden' option
1042can be used to make an exception for a specific buffer. It can take these
1043values:
1044 <empty> Use the value of 'hidden'.
1045 hide Hide this buffer, also when 'hidden' is not set.
1046 unload Don't hide but unload this buffer, also when 'hidden'
1047 is set.
1048 delete Delete the buffer.
1049
1050 *hidden-quit*
1051When you try to quit Vim while there is a hidden, modified buffer, you will
1052get an error message and Vim will make that buffer the current buffer. You
1053can then decide to write this buffer (":wq") or quit without writing (":q!").
1054Be careful: there may be more hidden, modified buffers!
1055
1056A buffer can also be unlisted. This means it exists, but it is not in the
1057list of buffers. |unlisted-buffer|
1058
1059
Bram Moolenaard51cb702015-07-21 15:03:06 +02001060:files[!] [flags] *:files*
1061:buffers[!] [flags] *:buffers* *:ls*
1062:ls[!] [flags]
1063 Show all buffers. Example:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001064
Bram Moolenaar97d62492012-11-15 21:28:22 +01001065 1 #h "/test/text" line 1 ~
1066 2u "asdf" line 0 ~
1067 3 %a + "version.c" line 1 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00001068
1069 When the [!] is included the list will show unlisted buffers
1070 (the term "unlisted" is a bit confusing then...).
1071
1072 Each buffer has a unique number. That number will not change,
Bram Moolenaar0122c402015-02-03 19:13:34 +01001073 thus you can always go to a specific buffer with ":buffer N"
1074 or "N CTRL-^", where N is the buffer number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001075
Bram Moolenaarc6896e22019-05-30 22:32:34 +02001076 For the file name these special values are used:
1077 [Prompt] |prompt-buffer|
1078 [Popup] buffer of a |popup-window|
1079 [Scratch] 'buftype' is "nofile"
1080 [No Name] no file name specified
1081 For a |terminal-window| buffer the status is used.
1082
Bram Moolenaar071d4272004-06-13 20:20:40 +00001083 Indicators (chars in the same column are mutually exclusive):
1084 u an unlisted buffer (only displayed when [!] is used)
1085 |unlisted-buffer|
1086 % the buffer in the current window
1087 # the alternate buffer for ":e #" and CTRL-^
1088 a an active buffer: it is loaded and visible
1089 h a hidden buffer: It is loaded, but currently not
1090 displayed in a window |hidden-buffer|
1091 - a buffer with 'modifiable' off
1092 = a readonly buffer
Bram Moolenaarc572da52017-08-27 16:52:01 +02001093 R a terminal buffer with a running job
1094 F a terminal buffer with a finished job
Bram Moolenaar37c64c72017-09-19 22:06:03 +02001095 ? a terminal buffer without a job: `:terminal NONE`
Bram Moolenaar071d4272004-06-13 20:20:40 +00001096 + a modified buffer
1097 x a buffer with read errors
1098
Bram Moolenaard51cb702015-07-21 15:03:06 +02001099 [flags] can be a combination of the following characters,
1100 which restrict the buffers to be listed:
1101 + modified buffers
1102 - buffers with 'modifiable' off
1103 = readonly buffers
1104 a active buffers
Bram Moolenaare392eb42015-11-19 20:38:09 +01001105 u unlisted buffers (overrides the "!")
Bram Moolenaard51cb702015-07-21 15:03:06 +02001106 h hidden buffers
1107 x buffers with a read error
1108 % current buffer
1109 # alternate buffer
Bram Moolenaar0751f512018-03-29 16:37:16 +02001110 R terminal buffers with a running job
1111 F terminal buffers with a finished job
1112 ? terminal buffers without a job: `:terminal NONE`
Bram Moolenaar52410572019-10-27 05:12:45 +01001113 t show time last used and sort buffers
Bram Moolenaard51cb702015-07-21 15:03:06 +02001114 Combining flags means they are "and"ed together, e.g.:
1115 h+ hidden buffers which are modified
1116 a+ active buffers which are modified
1117
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02001118 When using |:filter| the pattern is matched against the
1119 displayed buffer name, e.g.: >
1120 filter /\.vim/ ls
1121<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001122 *:bad* *:badd*
1123:bad[d] [+lnum] {fname}
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02001124 Add file name {fname} to the buffer list, without loading it,
1125 if it wasn't listed yet. If the buffer was previously
1126 deleted, not wiped, it will be made listed again.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001127 If "lnum" is specified, the cursor will be positioned at that
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001128 line when the buffer is first entered. Note that other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001129 commands after the + will be ignored.
1130
Bram Moolenaar59d8e562020-11-07 18:41:10 +01001131 *:balt*
1132:balt [+lnum] {fname}
1133 Like `:badd` and also set the alternate file for the current
1134 window to {fname}.
1135
Bram Moolenaar071d4272004-06-13 20:20:40 +00001136:[N]bd[elete][!] *:bd* *:bdel* *:bdelete* *E516*
1137:bd[elete][!] [N]
1138 Unload buffer [N] (default: current buffer) and delete it from
1139 the buffer list. If the buffer was changed, this fails,
1140 unless when [!] is specified, in which case changes are lost.
1141 The file remains unaffected. Any windows for this buffer are
1142 closed. If buffer [N] is the current buffer, another buffer
1143 will be displayed instead. This is the most recent entry in
1144 the jump list that points into a loaded buffer.
1145 Actually, the buffer isn't completely deleted, it is removed
1146 from the buffer list |unlisted-buffer| and option values,
1147 variables and mappings/abbreviations for the buffer are
Bram Moolenaar4d84d932014-11-30 14:50:16 +01001148 cleared. Examples: >
1149 :.,$-bdelete " delete buffers from the current one to
1150 " last but one
1151 :%bdelete " delete all buffers
1152<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001153
1154:bdelete[!] {bufname} *E93* *E94*
Bram Moolenaar15142e22018-04-30 22:19:58 +02001155 Like ":bdelete[!] [N]", but buffer given by name, see
1156 |{bufname}|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001157
1158:bdelete[!] N1 N2 ...
1159 Do ":bdelete[!]" for buffer N1, N2, etc. The arguments can be
1160 buffer numbers or buffer names (but not buffer names that are
1161 a number). Insert a backslash before a space in a buffer
1162 name.
1163
1164:N,Mbdelete[!] Do ":bdelete[!]" for all buffers in the range N to M
1165 |inclusive|.
1166
1167:[N]bw[ipeout][!] *:bw* *:bwipe* *:bwipeout* *E517*
1168:bw[ipeout][!] {bufname}
1169:N,Mbw[ipeout][!]
1170:bw[ipeout][!] N1 N2 ...
Bram Moolenaardf1bdc92006-02-23 21:32:16 +00001171 Like |:bdelete|, but really delete the buffer. Everything
1172 related to the buffer is lost. All marks in this buffer
1173 become invalid, option settings are lost, etc. Don't use this
Bram Moolenaar4d84d932014-11-30 14:50:16 +01001174 unless you know what you are doing. Examples: >
1175 :.+,$bwipeout " wipe out all buffers after the current
1176 " one
1177 :%bwipeout " wipe out all buffers
1178<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001179
1180:[N]bun[load][!] *:bun* *:bunload* *E515*
1181:bun[load][!] [N]
1182 Unload buffer [N] (default: current buffer). The memory
1183 allocated for this buffer will be freed. The buffer remains
1184 in the buffer list.
1185 If the buffer was changed, this fails, unless when [!] is
1186 specified, in which case the changes are lost.
1187 Any windows for this buffer are closed. If buffer [N] is the
1188 current buffer, another buffer will be displayed instead.
1189 This is the most recent entry in the jump list that points
1190 into a loaded buffer.
1191
1192:bunload[!] {bufname}
Bram Moolenaar15142e22018-04-30 22:19:58 +02001193 Like ":bunload[!] [N]", but buffer given by name.
1194 Also see |{bufname}|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001195
1196:N,Mbunload[!] Do ":bunload[!]" for all buffers in the range N to M
1197 |inclusive|.
1198
1199:bunload[!] N1 N2 ...
1200 Do ":bunload[!]" for buffer N1, N2, etc. The arguments can be
1201 buffer numbers or buffer names (but not buffer names that are
1202 a number). Insert a backslash before a space in a buffer
1203 name.
1204
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001205:[N]b[uffer][!] [+cmd] [N] *:b* *:bu* *:buf* *:buffer* *E86*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001206 Edit buffer [N] from the buffer list. If [N] is not given,
1207 the current buffer remains being edited. See |:buffer-!| for
1208 [!]. This will also edit a buffer that is not in the buffer
1209 list, without setting the 'buflisted' flag.
Bram Moolenaar47003982021-12-05 21:54:04 +00001210 The notation with single quotes does not work here,
1211 `:buf 12'345'` uses 12'345 as a buffer name.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001212 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001213
Bram Moolenaar15142e22018-04-30 22:19:58 +02001214:[N]b[uffer][!] [+cmd] {bufname} *{bufname}*
1215 Edit buffer for {bufname} from the buffer list. A partial
1216 name also works, so long as it is unique in the list of
1217 buffers.
1218 Note that a buffer whose name is a number cannot be referenced
1219 by that name; use the buffer number instead.
1220 Insert a backslash before a space in a buffer name.
1221 See |:buffer-!| for [!].
1222 This will also edit a buffer that is not in the buffer list,
1223 without setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001224 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001225
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001226:[N]sb[uffer] [+cmd] [N] *:sb* *:sbuffer*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001227 Split window and edit buffer [N] from the buffer list. If [N]
1228 is not given, the current buffer is edited. Respects the
1229 "useopen" setting of 'switchbuf' when splitting. This will
1230 also edit a buffer that is not in the buffer list, without
1231 setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001232 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001233
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001234:[N]sb[uffer] [+cmd] {bufname}
Bram Moolenaar15142e22018-04-30 22:19:58 +02001235 Split window and edit buffer for |{bufname}| from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001236 list. This will also edit a buffer that is not in the buffer
1237 list, without setting the 'buflisted' flag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001238 Note: If what you want to do is split the buffer, make a copy
1239 under another name, you can do it this way: >
1240 :w foobar | sp #
Bram Moolenaar12969c02015-09-08 23:36:10 +02001241< Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001242
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001243:[N]bn[ext][!] [+cmd] [N] *:bn* *:bnext* *E87*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001244 Go to [N]th next buffer in buffer list. [N] defaults to one.
1245 Wraps around the end of the buffer list.
1246 See |:buffer-!| for [!].
Bram Moolenaar12969c02015-09-08 23:36:10 +02001247 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001248 If you are in a help buffer, this takes you to the next help
1249 buffer (if there is one). Similarly, if you are in a normal
1250 (non-help) buffer, this takes you to the next normal buffer.
1251 This is so that if you have invoked help, it doesn't get in
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001252 the way when you're browsing code/text buffers. The next three
Bram Moolenaar071d4272004-06-13 20:20:40 +00001253 commands also work like this.
1254
1255 *:sbn* *:sbnext*
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001256:[N]sbn[ext] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001257 Split window and go to [N]th next buffer in buffer list.
1258 Wraps around the end of the buffer list. Uses 'switchbuf'
Bram Moolenaar12969c02015-09-08 23:36:10 +02001259 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001260
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001261:[N]bN[ext][!] [+cmd] [N] *:bN* *:bNext* *:bp* *:bprevious* *E88*
1262:[N]bp[revious][!] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001263 Go to [N]th previous buffer in buffer list. [N] defaults to
1264 one. Wraps around the start of the buffer list.
1265 See |:buffer-!| for [!] and 'switchbuf'.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001266 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001267
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001268:[N]sbN[ext] [+cmd] [N] *:sbN* *:sbNext* *:sbp* *:sbprevious*
1269:[N]sbp[revious] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001270 Split window and go to [N]th previous buffer in buffer list.
1271 Wraps around the start of the buffer list.
1272 Uses 'switchbuf'.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001273 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001274
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02001275:br[ewind][!] [+cmd] *:br* *:bre* *:brewind*
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001276 Go to first buffer in buffer list. If the buffer list is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001277 empty, go to the first unlisted buffer.
1278 See |:buffer-!| for [!].
1279
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001280:bf[irst] [+cmd] *:bf* *:bfirst*
1281 Same as |:brewind|.
1282 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001283
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001284:sbr[ewind] [+cmd] *:sbr* *:sbrewind*
1285 Split window and go to first buffer in buffer list. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001286 buffer list is empty, go to the first unlisted buffer.
1287 Respects the 'switchbuf' option.
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001288 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001289
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001290:sbf[irst] [+cmd] *:sbf* *:sbfirst*
1291 Same as ":sbrewind".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001292
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001293:bl[ast][!] [+cmd] *:bl* *:blast*
1294 Go to last buffer in buffer list. If the buffer list is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001295 empty, go to the last unlisted buffer.
1296 See |:buffer-!| for [!].
1297
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001298:sbl[ast] [+cmd] *:sbl* *:sblast*
1299 Split window and go to last buffer in buffer list. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001300 buffer list is empty, go to the last unlisted buffer.
1301 Respects 'switchbuf' option.
1302
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001303:[N]bm[odified][!] [+cmd] [N] *:bm* *:bmodified* *E84*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001304 Go to [N]th next modified buffer. Note: this command also
1305 finds unlisted buffers. If there is no modified buffer the
1306 command fails.
1307
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001308:[N]sbm[odified] [+cmd] [N] *:sbm* *:sbmodified*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001309 Split window and go to [N]th next modified buffer.
1310 Respects 'switchbuf' option.
1311 Note: this command also finds buffers not in the buffer list.
1312
1313:[N]unh[ide] [N] *:unh* *:unhide* *:sun* *:sunhide*
1314:[N]sun[hide] [N]
1315 Rearrange the screen to open one window for each loaded buffer
1316 in the buffer list. When a count is given, this is the
1317 maximum number of windows to open.
1318
1319:[N]ba[ll] [N] *:ba* *:ball* *:sba* *:sball*
1320:[N]sba[ll] [N] Rearrange the screen to open one window for each buffer in
1321 the buffer list. When a count is given, this is the maximum
1322 number of windows to open. 'winheight' also limits the number
1323 of windows opened ('winwidth' if |:vertical| was prepended).
1324 Buf/Win Enter/Leave autocommands are not executed for the new
1325 windows here, that's only done when they are really entered.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +00001326 When the |:tab| modifier is used new windows are opened in a
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00001327 new tab, up to 'tabpagemax'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001328
1329Note: All the commands above that start editing another buffer, keep the
1330'readonly' flag as it was. This differs from the ":edit" command, which sets
1331the 'readonly' flag each time the file is read.
1332
1333==============================================================================
133412. Special kinds of buffers *special-buffers*
1335
1336Instead of containing the text of a file, buffers can also be used for other
1337purposes. A few options can be set to change the behavior of a buffer:
1338 'bufhidden' what happens when the buffer is no longer displayed
1339 in a window.
1340 'buftype' what kind of a buffer this is
1341 'swapfile' whether the buffer will have a swap file
1342 'buflisted' buffer shows up in the buffer list
1343
1344A few useful kinds of a buffer:
1345
Bram Moolenaar280f1262006-01-30 00:14:18 +00001346quickfix Used to contain the error list or the location list. See
1347 |:cwindow| and |:lwindow|. This command sets the 'buftype'
1348 option to "quickfix". You are not supposed to change this!
1349 'swapfile' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001350
1351help Contains a help file. Will only be created with the |:help|
1352 command. The flag that indicates a help buffer is internal
1353 and can't be changed. The 'buflisted' option will be reset
1354 for a help buffer.
1355
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001356terminal A terminal window buffer, see |terminal|. The contents cannot
1357 be read or changed until the job ends.
1358
Bram Moolenaar677ee682005-01-27 14:41:15 +00001359directory Displays directory contents. Can be used by a file explorer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001360 plugin. The buffer is created with these settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001361 :setlocal buftype=nowrite
1362 :setlocal bufhidden=delete
1363 :setlocal noswapfile
Bram Moolenaar071d4272004-06-13 20:20:40 +00001364< The buffer name is the name of the directory and is adjusted
1365 when using the |:cd| command.
1366
Yegappan Lakshmanand1a8d652021-11-03 21:56:45 +00001367 *scratch-buffer*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001368scratch Contains text that can be discarded at any time. It is kept
1369 when closing the window, it must be deleted explicitly.
1370 Settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001371 :setlocal buftype=nofile
1372 :setlocal bufhidden=hide
1373 :setlocal noswapfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001374< The buffer name can be used to identify the buffer, if you
1375 give it a meaningful name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001376
1377 *unlisted-buffer*
1378unlisted The buffer is not in the buffer list. It is not used for
1379 normal editing, but to show a help file, remember a file name
1380 or marks. The ":bdelete" command will also set this option,
1381 thus it doesn't completely delete the buffer. Settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001382 :setlocal nobuflisted
Bram Moolenaar071d4272004-06-13 20:20:40 +00001383<
1384
Bram Moolenaard473c8c2018-08-11 18:00:22 +02001385 vim:tw=78:ts=8:noet:ft=help:norl: