blob: 824efe7095becdc7ff1b144d80686446d8ede945 [file] [log] [blame]
Bram Moolenaarb1c91982018-05-17 17:04:55 +02001*windows.txt* For Vim version 8.1. Last change: 2018 Apr 24
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
29{Vi does not have any of these commands}
30{not able to use multiple windows when the |+windows| feature was disabled at
31compile time}
32{not able to use vertically split windows when the |+vertsplit| feature was
33disabled at compile time}
34
35==============================================================================
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000361. Introduction *windows-intro* *window*
Bram Moolenaar071d4272004-06-13 20:20:40 +000037
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010038Summary:
39 A buffer is the in-memory text of a file.
40 A window is a viewport on a buffer.
41 A tab page is a collection of windows.
42
Bram Moolenaar071d4272004-06-13 20:20:40 +000043A window is a viewport onto a buffer. You can use multiple windows on one
44buffer, or several windows on different buffers.
45
46A buffer is a file loaded into memory for editing. The original file remains
47unchanged until you write the buffer to the file.
48
49A buffer can be in one of three states:
50
51 *active-buffer*
52active: The buffer is displayed in a window. If there is a file for this
53 buffer, it has been read into the buffer. The buffer may have been
54 modified since then and thus be different from the file.
55 *hidden-buffer*
56hidden: The buffer is not displayed. If there is a file for this buffer, it
57 has been read into the buffer. Otherwise it's the same as an active
58 buffer, you just can't see it.
59 *inactive-buffer*
60inactive: The buffer is not displayed and does not contain anything. Options
61 for the buffer are remembered if the file was once loaded. It can
62 contain marks from the |viminfo| file. But the buffer doesn't
63 contain text.
64
65In a table:
66
67state displayed loaded ":buffers" ~
68 in window shows ~
69active yes yes 'a'
70hidden no yes 'h'
71inactive no no ' '
72
73Note: All CTRL-W commands can also be executed with |:wincmd|, for those
74places where a Normal mode command can't be used or is inconvenient.
75
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000076The main Vim window can hold several split windows. There are also tab pages
77|tab-page|, each of which can hold multiple windows.
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +020078 *window-ID* *winid* *windowid*
Bram Moolenaarc95a3022016-06-12 23:01:46 +020079Each window has a unique identifier called the window ID. This identifier
80will not change within a Vim session. The |win_getid()| and |win_id2tabwin()|
81functions can be used to convert between the window/tab number and the
82identifier. There is also the window number, which may change whenever
83windows are opened or closed, see |winnr()|.
Bram Moolenaarba3ff532018-11-04 14:45:49 +010084The window number is only valid in one specific tab. The window ID is valid
85across tabs. For most functions that take a window ID or a window number, the
86window number only applies to the current tab, while the window ID can refer
87to a window in any tab.
Bram Moolenaarc95a3022016-06-12 23:01:46 +020088
89Each buffer has a unique number and the number will not change within a Vim
90session. The |bufnr()| and |bufname()| functions can be used to convert
91between a buffer name and the buffer number.
92
Bram Moolenaar071d4272004-06-13 20:20:40 +000093==============================================================================
942. Starting Vim *windows-starting*
95
96By default, Vim starts with one window, just like Vi.
97
98The "-o" and "-O" arguments to Vim can be used to open a window for each file
99in the argument list. The "-o" argument will split the windows horizontally;
100the "-O" argument will split the windows vertically. If both "-o" and "-O"
101are given, the last one encountered will be used to determine the split
102orientation. For example, this will open three windows, split horizontally: >
103 vim -o file1 file2 file3
104
105"-oN", where N is a decimal number, opens N windows split horizontally. If
106there are more file names than windows, only N windows are opened and some
107files do not get a window. If there are more windows than file names, the
108last few windows will be editing empty buffers. Similarly, "-ON" opens N
109windows split vertically, with the same restrictions.
110
111If there are many file names, the windows will become very small. You might
112want to set the 'winheight' and/or 'winwidth' options to create a workable
113situation.
114
115Buf/Win Enter/Leave |autocommand|s are not executed when opening the new
116windows and reading the files, that's only done when they are really entered.
117
118 *status-line*
119A status line will be used to separate windows. The 'laststatus' option tells
120when the last window also has a status line:
121 'laststatus' = 0 never a status line
122 'laststatus' = 1 status line if there is more than one window
123 'laststatus' = 2 always a status line
124
125You can change the contents of the status line with the 'statusline' option.
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000126This option can be local to the window, so that you can have a different
127status line in each window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000128
129Normally, inversion is used to display the status line. This can be changed
130with the 's' character in the 'highlight' option. For example, "sb" sets it to
131bold characters. If no highlighting is used for the status line ("sn"), the
132'^' character is used for the current window, and '=' for other windows. If
133the mouse is supported and enabled with the 'mouse' option, a status line can
134be dragged to resize windows.
135
136Note: If you expect your status line to be in reverse video and it isn't,
137check if the 'highlight' option contains "si". In version 3.0, this meant to
138invert the status line. Now it should be "sr", reverse the status line, as
139"si" now stands for italic! If italic is not available on your terminal, the
140status line is inverted anyway; you will only see this problem on terminals
141that have termcap codes for italics.
142
143==============================================================================
1443. Opening and closing a window *opening-window* *E36*
145
146CTRL-W s *CTRL-W_s*
147CTRL-W S *CTRL-W_S*
148CTRL-W CTRL-S *CTRL-W_CTRL-S*
Bram Moolenaar7b449342014-03-25 13:03:48 +0100149:[N]sp[lit] [++opt] [+cmd] [file] *:sp* *:split*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000150 Split current window in two. The result is two viewports on
Bram Moolenaar7b449342014-03-25 13:03:48 +0100151 the same file.
152
153 Make the new window N high (default is to use half the height
154 of the current window). Reduces the current window height to
155 create room (and others, if the 'equalalways' option is set,
156 'eadirection' isn't "hor", and one of them is higher than the
157 current or the new window).
158
159 If [file] is given it will be edited in the new window. If it
160 is not loaded in any buffer, it will be read. Else the new
161 window will use the already loaded buffer.
162
Bram Moolenaar071d4272004-06-13 20:20:40 +0000163 Note: CTRL-S does not work on all terminals and might block
164 further input, use CTRL-Q to get going again.
165 Also see |++opt| and |+cmd|.
166
167CTRL-W CTRL-V *CTRL-W_CTRL-V*
168CTRL-W v *CTRL-W_v*
169:[N]vs[plit] [++opt] [+cmd] [file] *:vs* *:vsplit*
Bram Moolenaar67f71312007-08-12 14:55:56 +0000170 Like |:split|, but split vertically. The windows will be
171 spread out horizontally if
172 1. a width was not specified,
173 2. 'equalalways' is set,
174 3. 'eadirection' isn't "ver", and
Bram Moolenaarc1a11ed2008-06-24 22:09:24 +0000175 4. one of the other windows is wider than the current or new
Bram Moolenaar67f71312007-08-12 14:55:56 +0000176 window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000177 Note: In other places CTRL-Q does the same as CTRL-V, but here
178 it doesn't!
179
180CTRL-W n *CTRL-W_n*
181CTRL-W CTRL_N *CTRL-W_CTRL-N*
182:[N]new [++opt] [+cmd] *:new*
183 Create a new window and start editing an empty file in it.
184 Make new window N high (default is to use half the existing
185 height). Reduces the current window height to create room (and
186 others, if the 'equalalways' option is set and 'eadirection'
187 isn't "hor").
188 Also see |++opt| and |+cmd|.
189 If 'fileformats' is not empty, the first format given will be
190 used for the new buffer. If 'fileformats' is empty, the
191 'fileformat' of the current buffer is used. This can be
192 overridden with the |++opt| argument.
193 Autocommands are executed in this order:
194 1. WinLeave for the current window
195 2. WinEnter for the new window
196 3. BufLeave for the current buffer
197 4. BufEnter for the new buffer
Bram Moolenaar53bfca22012-04-13 23:04:47 +0200198 This behaves like a ":split" first, and then an ":enew"
199 command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000200
201:[N]vne[w] [++opt] [+cmd] [file] *:vne* *:vnew*
202 Like |:new|, but split vertically. If 'equalalways' is set
203 and 'eadirection' isn't "ver" the windows will be spread out
204 horizontally, unless a width was specified.
205
206:[N]new [++opt] [+cmd] {file}
207:[N]sp[lit] [++opt] [+cmd] {file} *:split_f*
Bram Moolenaar53bfca22012-04-13 23:04:47 +0200208 Create a new window and start editing file {file} in it. This
209 behaves like a ":split" first, and then an ":e" command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000210 If [+cmd] is given, execute the command when the file has been
211 loaded |+cmd|.
212 Also see |++opt|.
213 Make new window N high (default is to use half the existing
214 height). Reduces the current window height to create room
215 (and others, if the 'equalalways' option is set).
216
217:[N]sv[iew] [++opt] [+cmd] {file} *:sv* *:sview* *splitview*
218 Same as ":split", but set 'readonly' option for this buffer.
219
220:[N]sf[ind] [++opt] [+cmd] {file} *:sf* *:sfind* *splitfind*
Bram Moolenaarc236c162008-07-13 17:41:49 +0000221 Same as ":split", but search for {file} in 'path' like in
222 |:find|. Doesn't split if {file} is not found.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000223
224CTRL-W CTRL-^ *CTRL-W_CTRL-^* *CTRL-W_^*
225CTRL-W ^ Does ":split #", split window in two and edit alternate file.
226 When a count is given, it becomes ":split #N", split window
227 and edit buffer N.
228
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200229 *CTRL-W_:*
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +0200230CTRL-W : Does the same as typing |:| - enter a command line. Useful in a
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200231 terminal window, where all Vim commands must be preceded with
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +0200232 CTRL-W or 'termwinkey'.
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200233
Bram Moolenaar071d4272004-06-13 20:20:40 +0000234Note that the 'splitbelow' and 'splitright' options influence where a new
235window will appear.
236
237 *:vert* *:vertical*
238:vert[ical] {cmd}
239 Execute {cmd}. If it contains a command that splits a window,
240 it will be split vertically.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000241 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000242
243:lefta[bove] {cmd} *:lefta* *:leftabove*
244:abo[veleft] {cmd} *:abo* *:aboveleft*
245 Execute {cmd}. If it contains a command that splits a window,
246 it will be opened left (vertical split) or above (horizontal
247 split) the current window. Overrules 'splitbelow' and
248 'splitright'.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000249 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000250
251:rightb[elow] {cmd} *:rightb* *:rightbelow*
252:bel[owright] {cmd} *:bel* *:belowright*
253 Execute {cmd}. If it contains a command that splits a window,
254 it will be opened right (vertical split) or below (horizontal
255 split) the current window. Overrules 'splitbelow' and
256 'splitright'.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000257 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000258
259 *:topleft* *E442*
260:to[pleft] {cmd}
261 Execute {cmd}. If it contains a command that splits a window,
262 it will appear at the top and occupy the full width of the Vim
263 window. When the split is vertical the window appears at the
264 far left and occupies the full height of the Vim window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000265 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000266
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200267 *:bo* *:botright*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000268:bo[tright] {cmd}
269 Execute {cmd}. If it contains a command that splits a window,
270 it will appear at the bottom and occupy the full width of the
271 Vim window. When the split is vertical the window appears at
272 the far right and occupies the full height of the Vim window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000273 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000274
275These command modifiers can be combined to make a vertically split window
276occupy the full height. Example: >
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200277 :vertical topleft split tags
Bram Moolenaar071d4272004-06-13 20:20:40 +0000278Opens a vertically split, full-height window on the "tags" file at the far
279left of the Vim window.
280
281
282Closing a window
283----------------
284
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100285:q[uit]
286:{count}q[uit]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000287CTRL-W q *CTRL-W_q*
288CTRL-W CTRL-Q *CTRL-W_CTRL-Q*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100289 Without {count}: Quit the current window. If {count} is
290 given quit the {count} window.
291
292 When quitting the last window (not counting a help window),
293 exit Vim.
294
Bram Moolenaar071d4272004-06-13 20:20:40 +0000295 When 'hidden' is set, and there is only one window for the
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100296 current buffer, it becomes hidden. When 'hidden' is not set,
297 and there is only one window for the current buffer, and the
298 buffer was changed, the command fails.
299
Bram Moolenaared32d942014-12-06 23:33:00 +0100300 (Note: CTRL-Q does not work on all terminals).
301
302 If [count] is greater than the last window number the last
303 window will be closed: >
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100304 :1quit " quit the first window
305 :$quit " quit the last window
306 :9quit " quit the last window
Bram Moolenaar46fceaa2016-10-23 21:21:08 +0200307 " if there are fewer than 9 windows opened
308 :-quit " quit the previous window
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100309 :+quit " quit the next window
Bram Moolenaared32d942014-12-06 23:33:00 +0100310 :+2quit " quit the second next window
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100311<
312:q[uit]!
313:{count}q[uit]!
314 Without {count}: Quit the current window. If {count} is
315 given quit the {count} window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000316
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100317 If this was the last window for a buffer, any changes to that
318 buffer are lost. When quitting the last window (not counting
319 help windows), exit Vim. The contents of the buffer are lost,
320 even when 'hidden' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000321
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100322:clo[se][!]
323:{count}clo[se][!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000324CTRL-W c *CTRL-W_c* *:clo* *:close*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100325 Without {count}: Close the current window. If {count} is
326 given close the {count} window.
327
328 When the 'hidden' option is set, or when the buffer was
329 changed and the [!] is used, the buffer becomes hidden (unless
330 there is another window editing it).
331
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000332 When there is only one window in the current tab page and
333 there is another tab page, this closes the current tab page.
334 |tab-page|.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100335
Bram Moolenaar071d4272004-06-13 20:20:40 +0000336 This command fails when: *E444*
337 - There is only one window on the screen.
338 - When 'hidden' is not set, [!] is not used, the buffer has
339 changes, and there is no other window on this buffer.
340 Changes to the buffer are not written and won't get lost, so
341 this is a "safe" command.
342
343CTRL-W CTRL-C *CTRL-W_CTRL-C*
344 You might have expected that CTRL-W CTRL-C closes the current
345 window, but that does not work, because the CTRL-C cancels the
346 command.
347
348 *:hide*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100349:hid[e]
350:{count}hid[e]
Bram Moolenaarc572da52017-08-27 16:52:01 +0200351 Without {count}: Quit the current window, unless it is the
352 last window on the screen.
353 If {count} is given quit the {count} window.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100354
355 The buffer becomes hidden (unless there is another window
Bram Moolenaared32d942014-12-06 23:33:00 +0100356 editing it or 'bufhidden' is "unload", "delete" or "wipe").
357 If the window is the last one in the current tab page the tab
358 page is closed. |tab-page|
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100359
360 The value of 'hidden' is irrelevant for this command. Changes
361 to the buffer are not written and won't get lost, so this is a
362 "safe" command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000363
364:hid[e] {cmd} Execute {cmd} with 'hidden' is set. The previous value of
365 'hidden' is restored after {cmd} has been executed.
366 Example: >
367 :hide edit Makefile
368< This will edit "Makefile", and hide the current buffer if it
369 has any changes.
370
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100371:on[ly][!]
372:{count}on[ly][!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000373CTRL-W o *CTRL-W_o* *E445*
374CTRL-W CTRL-O *CTRL-W_CTRL-O* *:on* *:only*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100375 Make the current window the only one on the screen. All other
376 windows are closed. For {count} see |:quit| command.
377
Bram Moolenaar071d4272004-06-13 20:20:40 +0000378 When the 'hidden' option is set, all buffers in closed windows
379 become hidden.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100380
Bram Moolenaar071d4272004-06-13 20:20:40 +0000381 When 'hidden' is not set, and the 'autowrite' option is set,
382 modified buffers are written. Otherwise, windows that have
383 buffers that are modified are not removed, unless the [!] is
384 given, then they become hidden. But modified buffers are
385 never abandoned, so changes cannot get lost.
386
387==============================================================================
3884. Moving cursor to other windows *window-move-cursor*
389
390CTRL-W <Down> *CTRL-W_<Down>*
391CTRL-W CTRL-J *CTRL-W_CTRL-J* *CTRL-W_j*
392CTRL-W j Move cursor to Nth window below current one. Uses the cursor
393 position to select between alternatives.
394
395CTRL-W <Up> *CTRL-W_<Up>*
396CTRL-W CTRL-K *CTRL-W_CTRL-K* *CTRL-W_k*
397CTRL-W k Move cursor to Nth window above current one. Uses the cursor
398 position to select between alternatives.
399
400CTRL-W <Left> *CTRL-W_<Left>*
401CTRL-W CTRL-H *CTRL-W_CTRL-H*
402CTRL-W <BS> *CTRL-W_<BS>* *CTRL-W_h*
403CTRL-W h Move cursor to Nth window left of current one. Uses the
404 cursor position to select between alternatives.
405
406CTRL-W <Right> *CTRL-W_<Right>*
407CTRL-W CTRL-L *CTRL-W_CTRL-L* *CTRL-W_l*
408CTRL-W l Move cursor to Nth window right of current one. Uses the
409 cursor position to select between alternatives.
410
411CTRL-W w *CTRL-W_w* *CTRL-W_CTRL-W*
412CTRL-W CTRL-W Without count: move cursor to window below/right of the
413 current one. If there is no window below or right, go to
414 top-left window.
415 With count: go to Nth window (windows are numbered from
416 top-left to bottom-right). To obtain the window number see
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100417 |bufwinnr()| and |winnr()|. When N is larger than the number
418 of windows go to the last window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000419
420 *CTRL-W_W*
421CTRL-W W Without count: move cursor to window above/left of current
422 one. If there is no window above or left, go to bottom-right
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100423 window. With count: go to Nth window, like with CTRL-W w.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000424
425CTRL-W t *CTRL-W_t* *CTRL-W_CTRL-T*
426CTRL-W CTRL-T Move cursor to top-left window.
427
428CTRL-W b *CTRL-W_b* *CTRL-W_CTRL-B*
429CTRL-W CTRL-B Move cursor to bottom-right window.
430
431CTRL-W p *CTRL-W_p* *CTRL-W_CTRL-P*
432CTRL-W CTRL-P Go to previous (last accessed) window.
433
434 *CTRL-W_P* *E441*
435CTRL-W P Go to preview window. When there is no preview window this is
436 an error.
437 {not available when compiled without the |+quickfix| feature}
438
439If Visual mode is active and the new window is not for the same buffer, the
440Visual mode is ended. If the window is on the same buffer, the cursor
441position is set to keep the same Visual area selected.
442
443 *:winc* *:wincmd*
444These commands can also be executed with ":wincmd":
445
446:[count]winc[md] {arg}
447 Like executing CTRL-W [count] {arg}. Example: >
448 :wincmd j
449< Moves to the window below the current one.
450 This command is useful when a Normal mode cannot be used (for
451 the |CursorHold| autocommand event). Or when a Normal mode
452 command is inconvenient.
453 The count can also be a window number. Example: >
454 :exe nr . "wincmd w"
455< This goes to window "nr".
456
457==============================================================================
4585. Moving windows around *window-moving*
459
460CTRL-W r *CTRL-W_r* *CTRL-W_CTRL-R* *E443*
461CTRL-W CTRL-R Rotate windows downwards/rightwards. The first window becomes
462 the second one, the second one becomes the third one, etc.
463 The last window becomes the first window. The cursor remains
464 in the same window.
465 This only works within the row or column of windows that the
466 current window is in.
467
468 *CTRL-W_R*
469CTRL-W R Rotate windows upwards/leftwards. The second window becomes
470 the first one, the third one becomes the second one, etc. The
471 first window becomes the last window. The cursor remains in
472 the same window.
473 This only works within the row or column of windows that the
474 current window is in.
475
476CTRL-W x *CTRL-W_x* *CTRL-W_CTRL-X*
477CTRL-W CTRL-X Without count: Exchange current window with next one. If there
478 is no next window, exchange with previous window.
479 With count: Exchange current window with Nth window (first
480 window is 1). The cursor is put in the other window.
481 When vertical and horizontal window splits are mixed, the
482 exchange is only done in the row or column of windows that the
483 current window is in.
484
485The following commands can be used to change the window layout. For example,
486when there are two vertically split windows, CTRL-W K will change that in
487horizontally split windows. CTRL-W H does it the other way around.
488
489 *CTRL-W_K*
490CTRL-W K Move the current window to be at the very top, using the full
491 width of the screen. This works like closing the current
492 window and then creating another one with ":topleft split",
493 except that the current window contents is used for the new
494 window.
495
496 *CTRL-W_J*
497CTRL-W J Move the current window to be at the very bottom, using the
498 full width of the screen. This works like closing the current
499 window and then creating another one with ":botright split",
500 except that the current window contents is used for the new
501 window.
502
503 *CTRL-W_H*
504CTRL-W H Move the current window to be at the far left, using the
505 full height of the screen. This works like closing the
506 current window and then creating another one with
507 ":vert topleft split", except that the current window contents
508 is used for the new window.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200509 {not available when compiled without the |+vertsplit| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000510
511 *CTRL-W_L*
512CTRL-W L Move the current window to be at the far right, using the full
513 height of the screen. This works like closing the
514 current window and then creating another one with
515 ":vert botright split", except that the current window
516 contents is used for the new window.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200517 {not available when compiled without the |+vertsplit| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000518
Bram Moolenaar4c3f5362006-04-11 21:38:50 +0000519 *CTRL-W_T*
520CTRL-W T Move the current window to a new tab page. This fails if
521 there is only one window in the current tab page.
522 When a count is specified the new tab page will be opened
523 before the tab page with this index. Otherwise it comes after
524 the current tab page.
525
Bram Moolenaar071d4272004-06-13 20:20:40 +0000526==============================================================================
5276. Window resizing *window-resize*
528
529 *CTRL-W_=*
530CTRL-W = Make all windows (almost) equally high and wide, but use
531 'winheight' and 'winwidth' for the current window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000532 Windows with 'winfixheight' set keep their height and windows
533 with 'winfixwidth' set keep their width.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000534
535:res[ize] -N *:res* *:resize* *CTRL-W_-*
536CTRL-W - Decrease current window height by N (default 1).
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200537 If used after |:vertical|: decrease width by N.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000538
539:res[ize] +N *CTRL-W_+*
540CTRL-W + Increase current window height by N (default 1).
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200541 If used after |:vertical|: increase width by N.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000542
543:res[ize] [N]
544CTRL-W CTRL-_ *CTRL-W_CTRL-_* *CTRL-W__*
545CTRL-W _ Set current window height to N (default: highest possible).
546
547z{nr}<CR> Set current window height to {nr}.
548
549 *CTRL-W_<*
550CTRL-W < Decrease current window width by N (default 1).
551
552 *CTRL-W_>*
553CTRL-W > Increase current window width by N (default 1).
554
555:vertical res[ize] [N] *:vertical-resize* *CTRL-W_bar*
556CTRL-W | Set current window width to N (default: widest possible).
557
558You can also resize a window by dragging a status line up or down with the
559mouse. Or by dragging a vertical separator line left or right. This only
560works if the version of Vim that is being used supports the mouse and the
561'mouse' option has been set to enable it.
562
563The option 'winheight' ('wh') is used to set the minimal window height of the
564current window. This option is used each time another window becomes the
565current window. If the option is '0', it is disabled. Set 'winheight' to a
566very large value, e.g., '9999', to make the current window always fill all
567available space. Set it to a reasonable value, e.g., '10', to make editing in
568the current window comfortable.
569
570The equivalent 'winwidth' ('wiw') option is used to set the minimal width of
571the current window.
572
573When the option 'equalalways' ('ea') is set, all the windows are automatically
574made the same size after splitting or closing a window. If you don't set this
575option, splitting a window will reduce the size of the current window and
576leave the other windows the same. When closing a window, the extra lines are
577given to the window above it.
578
579The 'eadirection' option limits the direction in which the 'equalalways'
580option is applied. The default "both" resizes in both directions. When the
581value is "ver" only the heights of windows are equalized. Use this when you
582have manually resized a vertically split window and want to keep this width.
583Likewise, "hor" causes only the widths of windows to be equalized.
584
585The option 'cmdheight' ('ch') is used to set the height of the command-line.
586If you are annoyed by the |hit-enter| prompt for long messages, set this
587option to 2 or 3.
588
589If there is only one window, resizing that window will also change the command
590line height. If there are several windows, resizing the current window will
591also change the height of the window below it (and sometimes the window above
592it).
593
594The minimal height and width of a window is set with 'winminheight' and
595'winminwidth'. These are hard values, a window will never become smaller.
596
597==============================================================================
5987. Argument and buffer list commands *buffer-list*
599
600 args list buffer list meaning ~
6011. :[N]argument [N] 11. :[N]buffer [N] to arg/buf N
6022. :[N]next [file ..] 12. :[N]bnext [N] to Nth next arg/buf
6033. :[N]Next [N] 13. :[N]bNext [N] to Nth previous arg/buf
6044. :[N]previous [N] 14. :[N]bprevious [N] to Nth previous arg/buf
6055. :rewind / :first 15. :brewind / :bfirst to first arg/buf
6066. :last 16. :blast to last arg/buf
6077. :all 17. :ball edit all args/buffers
608 18. :unhide edit all loaded buffers
609 19. :[N]bmod [N] to Nth modified buf
610
611 split & args list split & buffer list meaning ~
61221. :[N]sargument [N] 31. :[N]sbuffer [N] split + to arg/buf N
61322. :[N]snext [file ..] 32. :[N]sbnext [N] split + to Nth next arg/buf
61423. :[N]sNext [N] 33. :[N]sbNext [N] split + to Nth previous arg/buf
61524. :[N]sprevious [N] 34. :[N]sbprevious [N] split + to Nth previous arg/buf
61625. :srewind / :sfirst 35. :sbrewind / :sbfirst split + to first arg/buf
61726. :slast 36. :sblast split + to last arg/buf
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000061827. :sall 37. :sball edit all args/buffers
Bram Moolenaar071d4272004-06-13 20:20:40 +0000619 38. :sunhide edit all loaded buffers
620 39. :[N]sbmod [N] split + to Nth modified buf
621
62240. :args list of arguments
62341. :buffers list of buffers
624
625The meaning of [N] depends on the command:
Bram Moolenaar24a98a02017-09-27 22:23:55 +0200626 [N] is the number of buffers to go forward/backward on 2/12/22/32,
627 3/13/23/33, and 4/14/24/34
Bram Moolenaar071d4272004-06-13 20:20:40 +0000628 [N] is an argument number, defaulting to current argument, for 1 and 21
629 [N] is a buffer number, defaulting to current buffer, for 11 and 31
630 [N] is a count for 19 and 39
631
632Note: ":next" is an exception, because it must accept a list of file names
633for compatibility with Vi.
634
635
636The argument list and multiple windows
637--------------------------------------
638
639The current position in the argument list can be different for each window.
640Remember that when doing ":e file", the position in the argument list stays
641the same, but you are not editing the file at that position. To indicate
642this, the file message (and the title, if you have one) shows
643"(file (N) of M)", where "(N)" is the current position in the file list, and
644"M" the number of files in the file list.
645
646All the entries in the argument list are added to the buffer list. Thus, you
647can also get to them with the buffer list commands, like ":bnext".
648
649:[N]al[l][!] [N] *:al* *:all* *:sal* *:sall*
650:[N]sal[l][!] [N]
651 Rearrange the screen to open one window for each argument.
652 All other windows are closed. When a count is given, this is
653 the maximum number of windows to open.
Bram Moolenaarfd2ac762006-03-01 22:09:21 +0000654 With the |:tab| modifier open a tab page for each argument.
655 When there are more arguments than 'tabpagemax' further ones
656 become split windows in the last tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000657 When the 'hidden' option is set, all buffers in closed windows
658 become hidden.
659 When 'hidden' is not set, and the 'autowrite' option is set,
660 modified buffers are written. Otherwise, windows that have
661 buffers that are modified are not removed, unless the [!] is
662 given, then they become hidden. But modified buffers are
663 never abandoned, so changes cannot get lost.
664 [N] is the maximum number of windows to open. 'winheight'
665 also limits the number of windows opened ('winwidth' if
666 |:vertical| was prepended).
667 Buf/Win Enter/Leave autocommands are not executed for the new
668 windows here, that's only done when they are really entered.
669
670:[N]sa[rgument][!] [++opt] [+cmd] [N] *:sa* *:sargument*
671 Short for ":split | argument [N]": split window and go to Nth
672 argument. But when there is no such argument, the window is
673 not split. Also see |++opt| and |+cmd|.
674
675:[N]sn[ext][!] [++opt] [+cmd] [file ..] *:sn* *:snext*
676 Short for ":split | [N]next": split window and go to Nth next
677 argument. But when there is no next file, the window is not
678 split. Also see |++opt| and |+cmd|.
679
680:[N]spr[evious][!] [++opt] [+cmd] [N] *:spr* *:sprevious*
681:[N]sN[ext][!] [++opt] [+cmd] [N] *:sN* *:sNext*
682 Short for ":split | [N]Next": split window and go to Nth
683 previous argument. But when there is no previous file, the
684 window is not split. Also see |++opt| and |+cmd|.
685
686 *:sre* *:srewind*
687:sre[wind][!] [++opt] [+cmd]
688 Short for ":split | rewind": split window and go to first
689 argument. But when there is no argument list, the window is
690 not split. Also see |++opt| and |+cmd|.
691
692 *:sfir* *:sfirst*
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000693:sfir[st] [++opt] [+cmd]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000694 Same as ":srewind".
695
696 *:sla* *:slast*
697:sla[st][!] [++opt] [+cmd]
698 Short for ":split | last": split window and go to last
699 argument. But when there is no argument list, the window is
700 not split. Also see |++opt| and |+cmd|.
701
702 *:dr* *:drop*
Bram Moolenaared39e1d2008-08-09 17:55:22 +0000703:dr[op] [++opt] [+cmd] {file} ..
Bram Moolenaar071d4272004-06-13 20:20:40 +0000704 Edit the first {file} in a window.
705 - If the file is already open in a window change to that
706 window.
707 - If the file is not open in a window edit the file in the
708 current window. If the current buffer can't be |abandon|ed,
709 the window is split first.
Bram Moolenaar51628222016-12-01 23:03:28 +0100710 - Windows that are not in the argument list or are not full
711 width will be closed if possible.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000712 The |argument-list| is set, like with the |:next| command.
713 The purpose of this command is that it can be used from a
714 program that wants Vim to edit another file, e.g., a debugger.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000715 When using the |:tab| modifier each argument is opened in a
716 tab page. The last window is used if it's empty.
Bram Moolenaared39e1d2008-08-09 17:55:22 +0000717 Also see |++opt| and |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000718
719==============================================================================
7208. Do a command in all buffers or windows *list-repeat*
721
722 *:windo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100723:[range]windo {cmd} Execute {cmd} in each window or if [range] is given
724 only in windows for which the window number lies in
725 the [range]. It works like doing this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000726 CTRL-W t
727 :{cmd}
728 CTRL-W w
729 :{cmd}
730 etc.
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000731< This only operates in the current tab page.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000732 When an error is detected on one window, further
Bram Moolenaar071d4272004-06-13 20:20:40 +0000733 windows will not be visited.
734 The last window (or where an error occurred) becomes
735 the current window.
736 {cmd} can contain '|' to concatenate several commands.
737 {cmd} must not open or close windows or reorder them.
Bram Moolenaar0751f512018-03-29 16:37:16 +0200738 {not in Vi}
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200739 Also see |:tabdo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|,
740 |:cfdo| and |:lfdo|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000741
742 *:bufdo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100743:[range]bufdo[!] {cmd} Execute {cmd} in each buffer in the buffer list or if
744 [range] is given only for buffers for which their
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100745 buffer number is in the [range]. It works like doing
Bram Moolenaara162bc52015-01-07 16:54:21 +0100746 this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000747 :bfirst
748 :{cmd}
749 :bnext
750 :{cmd}
751 etc.
752< When the current file can't be |abandon|ed and the [!]
753 is not present, the command fails.
754 When an error is detected on one buffer, further
755 buffers will not be visited.
756 Unlisted buffers are skipped.
757 The last buffer (or where an error occurred) becomes
758 the current buffer.
759 {cmd} can contain '|' to concatenate several commands.
760 {cmd} must not delete buffers or add buffers to the
761 buffer list.
762 Note: While this command is executing, the Syntax
763 autocommand event is disabled by adding it to
764 'eventignore'. This considerably speeds up editing
765 each buffer.
Bram Moolenaar0751f512018-03-29 16:37:16 +0200766 {not in Vi}
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200767 Also see |:tabdo|, |:argdo|, |:windo|, |:cdo|, |:ldo|,
768 |:cfdo| and |:lfdo|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000769
770Examples: >
771
772 :windo set nolist nofoldcolumn | normal zn
773
774This resets the 'list' option and disables folding in all windows. >
775
776 :bufdo set fileencoding= | update
777
778This resets the 'fileencoding' in each buffer and writes it if this changed
779the buffer. The result is that all buffers will use the 'encoding' encoding
780(if conversion works properly).
781
782==============================================================================
7839. Tag or file name under the cursor *window-tag*
784
785 *:sta* *:stag*
786:sta[g][!] [tagname]
787 Does ":tag[!] [tagname]" and splits the window for the found
788 tag. See also |:tag|.
789
790CTRL-W ] *CTRL-W_]* *CTRL-W_CTRL-]*
791CTRL-W CTRL-] Split current window in two. Use identifier under cursor as a
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200792 tag and jump to it in the new upper window.
793 In Visual mode uses the Visually selected text as a tag.
794 Make new window N high.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000795
796 *CTRL-W_g]*
797CTRL-W g ] Split current window in two. Use identifier under cursor as a
798 tag and perform ":tselect" on it in the new upper window.
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200799 In Visual mode uses the Visually selected text as a tag.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000800 Make new window N high.
801
802 *CTRL-W_g_CTRL-]*
803CTRL-W g CTRL-] Split current window in two. Use identifier under cursor as a
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200804 tag and perform ":tjump" on it in the new upper window.
805 In Visual mode uses the Visually selected text as a tag.
806 Make new window N high.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000807
808CTRL-W f *CTRL-W_f* *CTRL-W_CTRL-F*
809CTRL-W CTRL-F Split current window in two. Edit file name under cursor.
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000810 Like ":split gf", but window isn't split if the file does not
Bram Moolenaar071d4272004-06-13 20:20:40 +0000811 exist.
812 Uses the 'path' variable as a list of directory names where to
813 look for the file. Also the path for current file is
814 used to search for the file name.
815 If the name is a hypertext link that looks like
816 "type://machine/path", only "/path" is used.
817 If a count is given, the count'th matching file is edited.
818 {not available when the |+file_in_path| feature was disabled
819 at compile time}
820
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000821CTRL-W F *CTRL-W_F*
822 Split current window in two. Edit file name under cursor and
823 jump to the line number following the file name. See |gF| for
824 details on how the line number is obtained.
Bram Moolenaar57657d82006-04-21 22:12:41 +0000825 {not available when the |+file_in_path| feature was disabled
826 at compile time}
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000827
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000828CTRL-W gf *CTRL-W_gf*
829 Open a new tab page and edit the file name under the cursor.
830 Like "tab split" and "gf", but the new tab page isn't created
831 if the file does not exist.
832 {not available when the |+file_in_path| feature was disabled
833 at compile time}
834
Bram Moolenaar57657d82006-04-21 22:12:41 +0000835CTRL-W gF *CTRL-W_gF*
836 Open a new tab page and edit the file name under the cursor
837 and jump to the line number following the file name. Like
838 "tab split" and "gF", but the new tab page isn't created if
839 the file does not exist.
840 {not available when the |+file_in_path| feature was disabled
841 at compile time}
842
Bram Moolenaar071d4272004-06-13 20:20:40 +0000843Also see |CTRL-W_CTRL-I|: open window for an included file that includes
844the keyword under the cursor.
845
846==============================================================================
84710. The preview window *preview-window*
848
849The preview window is a special window to show (preview) another file. It is
850normally a small window used to show an include file or definition of a
851function.
852{not available when compiled without the |+quickfix| feature}
853
Bram Moolenaarc270d802006-03-11 21:29:41 +0000854There can be only one preview window (per tab page). It is created with one
855of the commands below. The 'previewheight' option can be set to specify the
856height of the preview window when it's opened. The 'previewwindow' option is
857set in the preview window to be able to recognize it. The 'winfixheight'
858option is set to have it keep the same height when opening/closing other
859windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000860
861 *:pta* *:ptag*
862:pta[g][!] [tagname]
863 Does ":tag[!] [tagname]" and shows the found tag in a
864 "Preview" window without changing the current buffer or cursor
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000865 position. If a "Preview" window already exists, it is re-used
Bram Moolenaar071d4272004-06-13 20:20:40 +0000866 (like a help window is). If a new one is opened,
867 'previewheight' is used for the height of the window. See
868 also |:tag|.
869 See below for an example. |CursorHold-example|
870 Small difference from |:tag|: When [tagname] is equal to the
871 already displayed tag, the position in the matching tag list
872 is not reset. This makes the CursorHold example work after a
873 |:ptnext|.
874
875CTRL-W z *CTRL-W_z*
876CTRL-W CTRL-Z *CTRL-W_CTRL-Z* *:pc* *:pclose*
877:pc[lose][!] Close any "Preview" window currently open. When the 'hidden'
878 option is set, or when the buffer was changed and the [!] is
879 used, the buffer becomes hidden (unless there is another
880 window editing it). The command fails if any "Preview" buffer
881 cannot be closed. See also |:close|.
882
883 *:pp* *:ppop*
884:[count]pp[op][!]
885 Does ":[count]pop[!]" in the preview window. See |:pop| and
886 |:ptag|. {not in Vi}
887
888CTRL-W } *CTRL-W_}*
889 Use identifier under cursor as a tag and perform a :ptag on
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000890 it. Make the new Preview window (if required) N high. If N is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000891 not given, 'previewheight' is used.
892
893CTRL-W g } *CTRL-W_g}*
894 Use identifier under cursor as a tag and perform a :ptjump on
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000895 it. Make the new Preview window (if required) N high. If N is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000896 not given, 'previewheight' is used.
897
898 *:ped* *:pedit*
899:ped[it][!] [++opt] [+cmd] {file}
900 Edit {file} in the preview window. The preview window is
901 opened like with |:ptag|. The current window and cursor
902 position isn't changed. Useful example: >
903 :pedit +/fputc /usr/include/stdio.h
904<
905 *:ps* *:psearch*
906:[range]ps[earch][!] [count] [/]pattern[/]
907 Works like |:ijump| but shows the found match in the preview
908 window. The preview window is opened like with |:ptag|. The
909 current window and cursor position isn't changed. Useful
910 example: >
911 :psearch popen
912< Like with the |:ptag| command, you can use this to
913 automatically show information about the word under the
914 cursor. This is less clever than using |:ptag|, but you don't
915 need a tags file and it will also find matches in system
916 include files. Example: >
917 :au! CursorHold *.[ch] nested exe "silent! psearch " . expand("<cword>")
918< Warning: This can be slow.
919
920Example *CursorHold-example* >
921
922 :au! CursorHold *.[ch] nested exe "silent! ptag " . expand("<cword>")
923
924This will cause a ":ptag" to be executed for the keyword under the cursor,
925when the cursor hasn't moved for the time set with 'updatetime'. The "nested"
926makes other autocommands be executed, so that syntax highlighting works in the
927preview window. The "silent!" avoids an error message when the tag could not
928be found. Also see |CursorHold|. To disable this again: >
929
930 :au! CursorHold
931
932A nice addition is to highlight the found tag, avoid the ":ptag" when there
933is no word under the cursor, and a few other things: >
934
935 :au! CursorHold *.[ch] nested call PreviewWord()
936 :func PreviewWord()
937 : if &previewwindow " don't do this in the preview window
938 : return
939 : endif
940 : let w = expand("<cword>") " get the word under cursor
941 : if w =~ '\a' " if the word contains a letter
942 :
943 : " Delete any existing highlight before showing another tag
944 : silent! wincmd P " jump to preview window
945 : if &previewwindow " if we really get there...
946 : match none " delete existing highlight
947 : wincmd p " back to old window
948 : endif
949 :
950 : " Try displaying a matching tag for the word under the cursor
951 : try
952 : exe "ptag " . w
953 : catch
954 : return
955 : endtry
956 :
957 : silent! wincmd P " jump to preview window
958 : if &previewwindow " if we really get there...
959 : if has("folding")
960 : silent! .foldopen " don't want a closed fold
961 : endif
962 : call search("$", "b") " to end of previous line
963 : let w = substitute(w, '\\', '\\\\', "")
964 : call search('\<\V' . w . '\>') " position cursor on match
965 : " Add a match highlight to the word at this position
966 : hi previewWord term=bold ctermbg=green guibg=green
967 : exe 'match previewWord "\%' . line(".") . 'l\%' . col(".") . 'c\k*"'
968 : wincmd p " back to old window
969 : endif
970 : endif
971 :endfun
972
973==============================================================================
97411. Using hidden buffers *buffer-hidden*
975
976A hidden buffer is not displayed in a window, but is still loaded into memory.
977This makes it possible to jump from file to file, without the need to read or
978write the file every time you get another buffer in a window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000979
980 *:buffer-!*
981If the option 'hidden' ('hid') is set, abandoned buffers are kept for all
982commands that start editing another file: ":edit", ":next", ":tag", etc. The
983commands that move through the buffer list sometimes make the current buffer
984hidden although the 'hidden' option is not set. This happens when a buffer is
985modified, but is forced (with '!') to be removed from a window, and
986'autowrite' is off or the buffer can't be written.
987
988You can make a hidden buffer not hidden by starting to edit it with any
989command. Or by deleting it with the ":bdelete" command.
990
991The 'hidden' is global, it is used for all buffers. The 'bufhidden' option
992can be used to make an exception for a specific buffer. It can take these
993values:
994 <empty> Use the value of 'hidden'.
995 hide Hide this buffer, also when 'hidden' is not set.
996 unload Don't hide but unload this buffer, also when 'hidden'
997 is set.
998 delete Delete the buffer.
999
1000 *hidden-quit*
1001When you try to quit Vim while there is a hidden, modified buffer, you will
1002get an error message and Vim will make that buffer the current buffer. You
1003can then decide to write this buffer (":wq") or quit without writing (":q!").
1004Be careful: there may be more hidden, modified buffers!
1005
1006A buffer can also be unlisted. This means it exists, but it is not in the
1007list of buffers. |unlisted-buffer|
1008
1009
Bram Moolenaard51cb702015-07-21 15:03:06 +02001010:files[!] [flags] *:files*
1011:buffers[!] [flags] *:buffers* *:ls*
1012:ls[!] [flags]
1013 Show all buffers. Example:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001014
Bram Moolenaar97d62492012-11-15 21:28:22 +01001015 1 #h "/test/text" line 1 ~
1016 2u "asdf" line 0 ~
1017 3 %a + "version.c" line 1 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00001018
1019 When the [!] is included the list will show unlisted buffers
1020 (the term "unlisted" is a bit confusing then...).
1021
1022 Each buffer has a unique number. That number will not change,
Bram Moolenaar0122c402015-02-03 19:13:34 +01001023 thus you can always go to a specific buffer with ":buffer N"
1024 or "N CTRL-^", where N is the buffer number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001025
1026 Indicators (chars in the same column are mutually exclusive):
1027 u an unlisted buffer (only displayed when [!] is used)
1028 |unlisted-buffer|
1029 % the buffer in the current window
1030 # the alternate buffer for ":e #" and CTRL-^
1031 a an active buffer: it is loaded and visible
1032 h a hidden buffer: It is loaded, but currently not
1033 displayed in a window |hidden-buffer|
1034 - a buffer with 'modifiable' off
1035 = a readonly buffer
Bram Moolenaarc572da52017-08-27 16:52:01 +02001036 R a terminal buffer with a running job
1037 F a terminal buffer with a finished job
Bram Moolenaar37c64c72017-09-19 22:06:03 +02001038 ? a terminal buffer without a job: `:terminal NONE`
Bram Moolenaar071d4272004-06-13 20:20:40 +00001039 + a modified buffer
1040 x a buffer with read errors
1041
Bram Moolenaard51cb702015-07-21 15:03:06 +02001042 [flags] can be a combination of the following characters,
1043 which restrict the buffers to be listed:
1044 + modified buffers
1045 - buffers with 'modifiable' off
1046 = readonly buffers
1047 a active buffers
Bram Moolenaare392eb42015-11-19 20:38:09 +01001048 u unlisted buffers (overrides the "!")
Bram Moolenaard51cb702015-07-21 15:03:06 +02001049 h hidden buffers
1050 x buffers with a read error
1051 % current buffer
1052 # alternate buffer
Bram Moolenaar0751f512018-03-29 16:37:16 +02001053 R terminal buffers with a running job
1054 F terminal buffers with a finished job
1055 ? terminal buffers without a job: `:terminal NONE`
Bram Moolenaard51cb702015-07-21 15:03:06 +02001056 Combining flags means they are "and"ed together, e.g.:
1057 h+ hidden buffers which are modified
1058 a+ active buffers which are modified
1059
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02001060 When using |:filter| the pattern is matched against the
1061 displayed buffer name, e.g.: >
1062 filter /\.vim/ ls
1063<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001064 *:bad* *:badd*
1065:bad[d] [+lnum] {fname}
1066 Add file name {fname} to the buffer list, without loading it.
1067 If "lnum" is specified, the cursor will be positioned at that
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001068 line when the buffer is first entered. Note that other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001069 commands after the + will be ignored.
1070
1071:[N]bd[elete][!] *:bd* *:bdel* *:bdelete* *E516*
1072:bd[elete][!] [N]
1073 Unload buffer [N] (default: current buffer) and delete it from
1074 the buffer list. If the buffer was changed, this fails,
1075 unless when [!] is specified, in which case changes are lost.
1076 The file remains unaffected. Any windows for this buffer are
1077 closed. If buffer [N] is the current buffer, another buffer
1078 will be displayed instead. This is the most recent entry in
1079 the jump list that points into a loaded buffer.
1080 Actually, the buffer isn't completely deleted, it is removed
1081 from the buffer list |unlisted-buffer| and option values,
1082 variables and mappings/abbreviations for the buffer are
Bram Moolenaar4d84d932014-11-30 14:50:16 +01001083 cleared. Examples: >
1084 :.,$-bdelete " delete buffers from the current one to
1085 " last but one
1086 :%bdelete " delete all buffers
1087<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001088
1089:bdelete[!] {bufname} *E93* *E94*
Bram Moolenaar15142e22018-04-30 22:19:58 +02001090 Like ":bdelete[!] [N]", but buffer given by name, see
1091 |{bufname}|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001092
1093:bdelete[!] N1 N2 ...
1094 Do ":bdelete[!]" for buffer N1, N2, etc. The arguments can be
1095 buffer numbers or buffer names (but not buffer names that are
1096 a number). Insert a backslash before a space in a buffer
1097 name.
1098
1099:N,Mbdelete[!] Do ":bdelete[!]" for all buffers in the range N to M
1100 |inclusive|.
1101
1102:[N]bw[ipeout][!] *:bw* *:bwipe* *:bwipeout* *E517*
1103:bw[ipeout][!] {bufname}
1104:N,Mbw[ipeout][!]
1105:bw[ipeout][!] N1 N2 ...
Bram Moolenaardf1bdc92006-02-23 21:32:16 +00001106 Like |:bdelete|, but really delete the buffer. Everything
1107 related to the buffer is lost. All marks in this buffer
1108 become invalid, option settings are lost, etc. Don't use this
Bram Moolenaar4d84d932014-11-30 14:50:16 +01001109 unless you know what you are doing. Examples: >
1110 :.+,$bwipeout " wipe out all buffers after the current
1111 " one
1112 :%bwipeout " wipe out all buffers
1113<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001114
1115:[N]bun[load][!] *:bun* *:bunload* *E515*
1116:bun[load][!] [N]
1117 Unload buffer [N] (default: current buffer). The memory
1118 allocated for this buffer will be freed. The buffer remains
1119 in the buffer list.
1120 If the buffer was changed, this fails, unless when [!] is
1121 specified, in which case the changes are lost.
1122 Any windows for this buffer are closed. If buffer [N] is the
1123 current buffer, another buffer will be displayed instead.
1124 This is the most recent entry in the jump list that points
1125 into a loaded buffer.
1126
1127:bunload[!] {bufname}
Bram Moolenaar15142e22018-04-30 22:19:58 +02001128 Like ":bunload[!] [N]", but buffer given by name.
1129 Also see |{bufname}|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001130
1131:N,Mbunload[!] Do ":bunload[!]" for all buffers in the range N to M
1132 |inclusive|.
1133
1134:bunload[!] N1 N2 ...
1135 Do ":bunload[!]" for buffer N1, N2, etc. The arguments can be
1136 buffer numbers or buffer names (but not buffer names that are
1137 a number). Insert a backslash before a space in a buffer
1138 name.
1139
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001140:[N]b[uffer][!] [+cmd] [N] *:b* *:bu* *:buf* *:buffer* *E86*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001141 Edit buffer [N] from the buffer list. If [N] is not given,
1142 the current buffer remains being edited. See |:buffer-!| for
1143 [!]. This will also edit a buffer that is not in the buffer
1144 list, without setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001145 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001146
Bram Moolenaar15142e22018-04-30 22:19:58 +02001147:[N]b[uffer][!] [+cmd] {bufname} *{bufname}*
1148 Edit buffer for {bufname} from the buffer list. A partial
1149 name also works, so long as it is unique in the list of
1150 buffers.
1151 Note that a buffer whose name is a number cannot be referenced
1152 by that name; use the buffer number instead.
1153 Insert a backslash before a space in a buffer name.
1154 See |:buffer-!| for [!].
1155 This will also edit a buffer that is not in the buffer list,
1156 without setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001157 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001158
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001159:[N]sb[uffer] [+cmd] [N] *:sb* *:sbuffer*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001160 Split window and edit buffer [N] from the buffer list. If [N]
1161 is not given, the current buffer is edited. Respects the
1162 "useopen" setting of 'switchbuf' when splitting. This will
1163 also edit a buffer that is not in the buffer list, without
1164 setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001165 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001166
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001167:[N]sb[uffer] [+cmd] {bufname}
Bram Moolenaar15142e22018-04-30 22:19:58 +02001168 Split window and edit buffer for |{bufname}| from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001169 list. This will also edit a buffer that is not in the buffer
1170 list, without setting the 'buflisted' flag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001171 Note: If what you want to do is split the buffer, make a copy
1172 under another name, you can do it this way: >
1173 :w foobar | sp #
Bram Moolenaar12969c02015-09-08 23:36:10 +02001174< Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001175
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001176:[N]bn[ext][!] [+cmd] [N] *:bn* *:bnext* *E87*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001177 Go to [N]th next buffer in buffer list. [N] defaults to one.
1178 Wraps around the end of the buffer list.
1179 See |:buffer-!| for [!].
Bram Moolenaar12969c02015-09-08 23:36:10 +02001180 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001181 If you are in a help buffer, this takes you to the next help
1182 buffer (if there is one). Similarly, if you are in a normal
1183 (non-help) buffer, this takes you to the next normal buffer.
1184 This is so that if you have invoked help, it doesn't get in
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001185 the way when you're browsing code/text buffers. The next three
Bram Moolenaar071d4272004-06-13 20:20:40 +00001186 commands also work like this.
1187
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001188
Bram Moolenaar071d4272004-06-13 20:20:40 +00001189 *:sbn* *:sbnext*
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001190:[N]sbn[ext] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001191 Split window and go to [N]th next buffer in buffer list.
1192 Wraps around the end of the buffer list. Uses 'switchbuf'
Bram Moolenaar12969c02015-09-08 23:36:10 +02001193 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001194
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001195:[N]bN[ext][!] [+cmd] [N] *:bN* *:bNext* *:bp* *:bprevious* *E88*
1196:[N]bp[revious][!] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001197 Go to [N]th previous buffer in buffer list. [N] defaults to
1198 one. Wraps around the start of the buffer list.
1199 See |:buffer-!| for [!] and 'switchbuf'.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001200 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001201
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001202:[N]sbN[ext] [+cmd] [N] *:sbN* *:sbNext* *:sbp* *:sbprevious*
1203:[N]sbp[revious] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001204 Split window and go to [N]th previous buffer in buffer list.
1205 Wraps around the start of the buffer list.
1206 Uses 'switchbuf'.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001207 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001208
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001209:br[ewind][!] [+cmd] *:br* *:brewind*
1210 Go to first buffer in buffer list. If the buffer list is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001211 empty, go to the first unlisted buffer.
1212 See |:buffer-!| for [!].
1213
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001214:bf[irst] [+cmd] *:bf* *:bfirst*
1215 Same as |:brewind|.
1216 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001217
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001218:sbr[ewind] [+cmd] *:sbr* *:sbrewind*
1219 Split window and go to first buffer in buffer list. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001220 buffer list is empty, go to the first unlisted buffer.
1221 Respects the 'switchbuf' option.
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001222 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001223
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001224:sbf[irst] [+cmd] *:sbf* *:sbfirst*
1225 Same as ":sbrewind".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001226
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001227:bl[ast][!] [+cmd] *:bl* *:blast*
1228 Go to last buffer in buffer list. If the buffer list is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001229 empty, go to the last unlisted buffer.
1230 See |:buffer-!| for [!].
1231
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001232:sbl[ast] [+cmd] *:sbl* *:sblast*
1233 Split window and go to last buffer in buffer list. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001234 buffer list is empty, go to the last unlisted buffer.
1235 Respects 'switchbuf' option.
1236
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001237:[N]bm[odified][!] [+cmd] [N] *:bm* *:bmodified* *E84*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001238 Go to [N]th next modified buffer. Note: this command also
1239 finds unlisted buffers. If there is no modified buffer the
1240 command fails.
1241
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001242:[N]sbm[odified] [+cmd] [N] *:sbm* *:sbmodified*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001243 Split window and go to [N]th next modified buffer.
1244 Respects 'switchbuf' option.
1245 Note: this command also finds buffers not in the buffer list.
1246
1247:[N]unh[ide] [N] *:unh* *:unhide* *:sun* *:sunhide*
1248:[N]sun[hide] [N]
1249 Rearrange the screen to open one window for each loaded buffer
1250 in the buffer list. When a count is given, this is the
1251 maximum number of windows to open.
1252
1253:[N]ba[ll] [N] *:ba* *:ball* *:sba* *:sball*
1254:[N]sba[ll] [N] Rearrange the screen to open one window for each buffer in
1255 the buffer list. When a count is given, this is the maximum
1256 number of windows to open. 'winheight' also limits the number
1257 of windows opened ('winwidth' if |:vertical| was prepended).
1258 Buf/Win Enter/Leave autocommands are not executed for the new
1259 windows here, that's only done when they are really entered.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +00001260 When the |:tab| modifier is used new windows are opened in a
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00001261 new tab, up to 'tabpagemax'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001262
1263Note: All the commands above that start editing another buffer, keep the
1264'readonly' flag as it was. This differs from the ":edit" command, which sets
1265the 'readonly' flag each time the file is read.
1266
1267==============================================================================
126812. Special kinds of buffers *special-buffers*
1269
1270Instead of containing the text of a file, buffers can also be used for other
1271purposes. A few options can be set to change the behavior of a buffer:
1272 'bufhidden' what happens when the buffer is no longer displayed
1273 in a window.
1274 'buftype' what kind of a buffer this is
1275 'swapfile' whether the buffer will have a swap file
1276 'buflisted' buffer shows up in the buffer list
1277
1278A few useful kinds of a buffer:
1279
Bram Moolenaar280f1262006-01-30 00:14:18 +00001280quickfix Used to contain the error list or the location list. See
1281 |:cwindow| and |:lwindow|. This command sets the 'buftype'
1282 option to "quickfix". You are not supposed to change this!
1283 'swapfile' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001284
1285help Contains a help file. Will only be created with the |:help|
1286 command. The flag that indicates a help buffer is internal
1287 and can't be changed. The 'buflisted' option will be reset
1288 for a help buffer.
1289
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001290terminal A terminal window buffer, see |terminal|. The contents cannot
1291 be read or changed until the job ends.
1292
Bram Moolenaar677ee682005-01-27 14:41:15 +00001293directory Displays directory contents. Can be used by a file explorer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001294 plugin. The buffer is created with these settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001295 :setlocal buftype=nowrite
1296 :setlocal bufhidden=delete
1297 :setlocal noswapfile
Bram Moolenaar071d4272004-06-13 20:20:40 +00001298< The buffer name is the name of the directory and is adjusted
1299 when using the |:cd| command.
1300
1301scratch Contains text that can be discarded at any time. It is kept
1302 when closing the window, it must be deleted explicitly.
1303 Settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001304 :setlocal buftype=nofile
1305 :setlocal bufhidden=hide
1306 :setlocal noswapfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001307< The buffer name can be used to identify the buffer, if you
1308 give it a meaningful name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001309
1310 *unlisted-buffer*
1311unlisted The buffer is not in the buffer list. It is not used for
1312 normal editing, but to show a help file, remember a file name
1313 or marks. The ":bdelete" command will also set this option,
1314 thus it doesn't completely delete the buffer. Settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001315 :setlocal nobuflisted
Bram Moolenaar071d4272004-06-13 20:20:40 +00001316<
1317
Bram Moolenaard473c8c2018-08-11 18:00:22 +02001318 vim:tw=78:ts=8:noet:ft=help:norl: