blob: c5021cd48c0b79385122d09d392238212af7631e [file] [log] [blame]
Bram Moolenaar0751f512018-03-29 16:37:16 +02001*windows.txt* For Vim version 8.0. Last change: 2018 Mar 29
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()|.
84
85Each buffer has a unique number and the number will not change within a Vim
86session. The |bufnr()| and |bufname()| functions can be used to convert
87between a buffer name and the buffer number.
88
Bram Moolenaar071d4272004-06-13 20:20:40 +000089==============================================================================
902. Starting Vim *windows-starting*
91
92By default, Vim starts with one window, just like Vi.
93
94The "-o" and "-O" arguments to Vim can be used to open a window for each file
95in the argument list. The "-o" argument will split the windows horizontally;
96the "-O" argument will split the windows vertically. If both "-o" and "-O"
97are given, the last one encountered will be used to determine the split
98orientation. For example, this will open three windows, split horizontally: >
99 vim -o file1 file2 file3
100
101"-oN", where N is a decimal number, opens N windows split horizontally. If
102there are more file names than windows, only N windows are opened and some
103files do not get a window. If there are more windows than file names, the
104last few windows will be editing empty buffers. Similarly, "-ON" opens N
105windows split vertically, with the same restrictions.
106
107If there are many file names, the windows will become very small. You might
108want to set the 'winheight' and/or 'winwidth' options to create a workable
109situation.
110
111Buf/Win Enter/Leave |autocommand|s are not executed when opening the new
112windows and reading the files, that's only done when they are really entered.
113
114 *status-line*
115A status line will be used to separate windows. The 'laststatus' option tells
116when the last window also has a status line:
117 'laststatus' = 0 never a status line
118 'laststatus' = 1 status line if there is more than one window
119 'laststatus' = 2 always a status line
120
121You can change the contents of the status line with the 'statusline' option.
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000122This option can be local to the window, so that you can have a different
123status line in each window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000124
125Normally, inversion is used to display the status line. This can be changed
126with the 's' character in the 'highlight' option. For example, "sb" sets it to
127bold characters. If no highlighting is used for the status line ("sn"), the
128'^' character is used for the current window, and '=' for other windows. If
129the mouse is supported and enabled with the 'mouse' option, a status line can
130be dragged to resize windows.
131
132Note: If you expect your status line to be in reverse video and it isn't,
133check if the 'highlight' option contains "si". In version 3.0, this meant to
134invert the status line. Now it should be "sr", reverse the status line, as
135"si" now stands for italic! If italic is not available on your terminal, the
136status line is inverted anyway; you will only see this problem on terminals
137that have termcap codes for italics.
138
139==============================================================================
1403. Opening and closing a window *opening-window* *E36*
141
142CTRL-W s *CTRL-W_s*
143CTRL-W S *CTRL-W_S*
144CTRL-W CTRL-S *CTRL-W_CTRL-S*
Bram Moolenaar7b449342014-03-25 13:03:48 +0100145:[N]sp[lit] [++opt] [+cmd] [file] *:sp* *:split*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000146 Split current window in two. The result is two viewports on
Bram Moolenaar7b449342014-03-25 13:03:48 +0100147 the same file.
148
149 Make the new window N high (default is to use half the height
150 of the current window). Reduces the current window height to
151 create room (and others, if the 'equalalways' option is set,
152 'eadirection' isn't "hor", and one of them is higher than the
153 current or the new window).
154
155 If [file] is given it will be edited in the new window. If it
156 is not loaded in any buffer, it will be read. Else the new
157 window will use the already loaded buffer.
158
Bram Moolenaar071d4272004-06-13 20:20:40 +0000159 Note: CTRL-S does not work on all terminals and might block
160 further input, use CTRL-Q to get going again.
161 Also see |++opt| and |+cmd|.
162
163CTRL-W CTRL-V *CTRL-W_CTRL-V*
164CTRL-W v *CTRL-W_v*
165:[N]vs[plit] [++opt] [+cmd] [file] *:vs* *:vsplit*
Bram Moolenaar67f71312007-08-12 14:55:56 +0000166 Like |:split|, but split vertically. The windows will be
167 spread out horizontally if
168 1. a width was not specified,
169 2. 'equalalways' is set,
170 3. 'eadirection' isn't "ver", and
Bram Moolenaarc1a11ed2008-06-24 22:09:24 +0000171 4. one of the other windows is wider than the current or new
Bram Moolenaar67f71312007-08-12 14:55:56 +0000172 window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000173 Note: In other places CTRL-Q does the same as CTRL-V, but here
174 it doesn't!
175
176CTRL-W n *CTRL-W_n*
177CTRL-W CTRL_N *CTRL-W_CTRL-N*
178:[N]new [++opt] [+cmd] *:new*
179 Create a new window and start editing an empty file in it.
180 Make new window N high (default is to use half the existing
181 height). Reduces the current window height to create room (and
182 others, if the 'equalalways' option is set and 'eadirection'
183 isn't "hor").
184 Also see |++opt| and |+cmd|.
185 If 'fileformats' is not empty, the first format given will be
186 used for the new buffer. If 'fileformats' is empty, the
187 'fileformat' of the current buffer is used. This can be
188 overridden with the |++opt| argument.
189 Autocommands are executed in this order:
190 1. WinLeave for the current window
191 2. WinEnter for the new window
192 3. BufLeave for the current buffer
193 4. BufEnter for the new buffer
Bram Moolenaar53bfca22012-04-13 23:04:47 +0200194 This behaves like a ":split" first, and then an ":enew"
195 command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000196
197:[N]vne[w] [++opt] [+cmd] [file] *:vne* *:vnew*
198 Like |:new|, but split vertically. If 'equalalways' is set
199 and 'eadirection' isn't "ver" the windows will be spread out
200 horizontally, unless a width was specified.
201
202:[N]new [++opt] [+cmd] {file}
203:[N]sp[lit] [++opt] [+cmd] {file} *:split_f*
Bram Moolenaar53bfca22012-04-13 23:04:47 +0200204 Create a new window and start editing file {file} in it. This
205 behaves like a ":split" first, and then an ":e" command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000206 If [+cmd] is given, execute the command when the file has been
207 loaded |+cmd|.
208 Also see |++opt|.
209 Make new window N high (default is to use half the existing
210 height). Reduces the current window height to create room
211 (and others, if the 'equalalways' option is set).
212
213:[N]sv[iew] [++opt] [+cmd] {file} *:sv* *:sview* *splitview*
214 Same as ":split", but set 'readonly' option for this buffer.
215
216:[N]sf[ind] [++opt] [+cmd] {file} *:sf* *:sfind* *splitfind*
Bram Moolenaarc236c162008-07-13 17:41:49 +0000217 Same as ":split", but search for {file} in 'path' like in
218 |:find|. Doesn't split if {file} is not found.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000219
220CTRL-W CTRL-^ *CTRL-W_CTRL-^* *CTRL-W_^*
221CTRL-W ^ Does ":split #", split window in two and edit alternate file.
222 When a count is given, it becomes ":split #N", split window
223 and edit buffer N.
224
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200225 *CTRL-W_:*
226CTRL-W : Does the same as typing |:| : edit a command line. Useful in a
227 terminal window, where all Vim commands must be preceded with
228 CTRL-W or 'termkey'.
229
Bram Moolenaar071d4272004-06-13 20:20:40 +0000230Note that the 'splitbelow' and 'splitright' options influence where a new
231window will appear.
232
233 *:vert* *:vertical*
234:vert[ical] {cmd}
235 Execute {cmd}. If it contains a command that splits a window,
236 it will be split vertically.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000237 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000238
239:lefta[bove] {cmd} *:lefta* *:leftabove*
240:abo[veleft] {cmd} *:abo* *:aboveleft*
241 Execute {cmd}. If it contains a command that splits a window,
242 it will be opened left (vertical split) or above (horizontal
243 split) the current window. Overrules 'splitbelow' and
244 'splitright'.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000245 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000246
247:rightb[elow] {cmd} *:rightb* *:rightbelow*
248:bel[owright] {cmd} *:bel* *:belowright*
249 Execute {cmd}. If it contains a command that splits a window,
250 it will be opened right (vertical split) or below (horizontal
251 split) the current window. Overrules 'splitbelow' and
252 'splitright'.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000253 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000254
255 *:topleft* *E442*
256:to[pleft] {cmd}
257 Execute {cmd}. If it contains a command that splits a window,
258 it will appear at the top and occupy the full width of the Vim
259 window. When the split is vertical the window appears at the
260 far left and occupies the full height of the Vim window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000261 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000262
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200263 *:bo* *:botright*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000264:bo[tright] {cmd}
265 Execute {cmd}. If it contains a command that splits a window,
266 it will appear at the bottom and occupy the full width of the
267 Vim window. When the split is vertical the window appears at
268 the far right and occupies the full height of the Vim window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000269 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000270
271These command modifiers can be combined to make a vertically split window
272occupy the full height. Example: >
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200273 :vertical topleft split tags
Bram Moolenaar071d4272004-06-13 20:20:40 +0000274Opens a vertically split, full-height window on the "tags" file at the far
275left of the Vim window.
276
277
278Closing a window
279----------------
280
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100281:q[uit]
282:{count}q[uit]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000283CTRL-W q *CTRL-W_q*
284CTRL-W CTRL-Q *CTRL-W_CTRL-Q*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100285 Without {count}: Quit the current window. If {count} is
286 given quit the {count} window.
287
288 When quitting the last window (not counting a help window),
289 exit Vim.
290
Bram Moolenaar071d4272004-06-13 20:20:40 +0000291 When 'hidden' is set, and there is only one window for the
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100292 current buffer, it becomes hidden. When 'hidden' is not set,
293 and there is only one window for the current buffer, and the
294 buffer was changed, the command fails.
295
Bram Moolenaared32d942014-12-06 23:33:00 +0100296 (Note: CTRL-Q does not work on all terminals).
297
298 If [count] is greater than the last window number the last
299 window will be closed: >
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100300 :1quit " quit the first window
301 :$quit " quit the last window
302 :9quit " quit the last window
Bram Moolenaar46fceaa2016-10-23 21:21:08 +0200303 " if there are fewer than 9 windows opened
304 :-quit " quit the previous window
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100305 :+quit " quit the next window
Bram Moolenaared32d942014-12-06 23:33:00 +0100306 :+2quit " quit the second next window
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100307<
308:q[uit]!
309:{count}q[uit]!
310 Without {count}: Quit the current window. If {count} is
311 given quit the {count} window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000312
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100313 If this was the last window for a buffer, any changes to that
314 buffer are lost. When quitting the last window (not counting
315 help windows), exit Vim. The contents of the buffer are lost,
316 even when 'hidden' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000317
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100318:clo[se][!]
319:{count}clo[se][!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000320CTRL-W c *CTRL-W_c* *:clo* *:close*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100321 Without {count}: Close the current window. If {count} is
322 given close the {count} window.
323
324 When the 'hidden' option is set, or when the buffer was
325 changed and the [!] is used, the buffer becomes hidden (unless
326 there is another window editing it).
327
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000328 When there is only one window in the current tab page and
329 there is another tab page, this closes the current tab page.
330 |tab-page|.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100331
Bram Moolenaar071d4272004-06-13 20:20:40 +0000332 This command fails when: *E444*
333 - There is only one window on the screen.
334 - When 'hidden' is not set, [!] is not used, the buffer has
335 changes, and there is no other window on this buffer.
336 Changes to the buffer are not written and won't get lost, so
337 this is a "safe" command.
338
339CTRL-W CTRL-C *CTRL-W_CTRL-C*
340 You might have expected that CTRL-W CTRL-C closes the current
341 window, but that does not work, because the CTRL-C cancels the
342 command.
343
344 *:hide*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100345:hid[e]
346:{count}hid[e]
Bram Moolenaarc572da52017-08-27 16:52:01 +0200347 Without {count}: Quit the current window, unless it is the
348 last window on the screen.
349 If {count} is given quit the {count} window.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100350
351 The buffer becomes hidden (unless there is another window
Bram Moolenaared32d942014-12-06 23:33:00 +0100352 editing it or 'bufhidden' is "unload", "delete" or "wipe").
353 If the window is the last one in the current tab page the tab
354 page is closed. |tab-page|
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100355
356 The value of 'hidden' is irrelevant for this command. Changes
357 to the buffer are not written and won't get lost, so this is a
358 "safe" command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000359
360:hid[e] {cmd} Execute {cmd} with 'hidden' is set. The previous value of
361 'hidden' is restored after {cmd} has been executed.
362 Example: >
363 :hide edit Makefile
364< This will edit "Makefile", and hide the current buffer if it
365 has any changes.
366
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100367:on[ly][!]
368:{count}on[ly][!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000369CTRL-W o *CTRL-W_o* *E445*
370CTRL-W CTRL-O *CTRL-W_CTRL-O* *:on* *:only*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100371 Make the current window the only one on the screen. All other
372 windows are closed. For {count} see |:quit| command.
373
Bram Moolenaar071d4272004-06-13 20:20:40 +0000374 When the 'hidden' option is set, all buffers in closed windows
375 become hidden.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100376
Bram Moolenaar071d4272004-06-13 20:20:40 +0000377 When 'hidden' is not set, and the 'autowrite' option is set,
378 modified buffers are written. Otherwise, windows that have
379 buffers that are modified are not removed, unless the [!] is
380 given, then they become hidden. But modified buffers are
381 never abandoned, so changes cannot get lost.
382
383==============================================================================
3844. Moving cursor to other windows *window-move-cursor*
385
386CTRL-W <Down> *CTRL-W_<Down>*
387CTRL-W CTRL-J *CTRL-W_CTRL-J* *CTRL-W_j*
388CTRL-W j Move cursor to Nth window below current one. Uses the cursor
389 position to select between alternatives.
390
391CTRL-W <Up> *CTRL-W_<Up>*
392CTRL-W CTRL-K *CTRL-W_CTRL-K* *CTRL-W_k*
393CTRL-W k Move cursor to Nth window above current one. Uses the cursor
394 position to select between alternatives.
395
396CTRL-W <Left> *CTRL-W_<Left>*
397CTRL-W CTRL-H *CTRL-W_CTRL-H*
398CTRL-W <BS> *CTRL-W_<BS>* *CTRL-W_h*
399CTRL-W h Move cursor to Nth window left of current one. Uses the
400 cursor position to select between alternatives.
401
402CTRL-W <Right> *CTRL-W_<Right>*
403CTRL-W CTRL-L *CTRL-W_CTRL-L* *CTRL-W_l*
404CTRL-W l Move cursor to Nth window right of current one. Uses the
405 cursor position to select between alternatives.
406
407CTRL-W w *CTRL-W_w* *CTRL-W_CTRL-W*
408CTRL-W CTRL-W Without count: move cursor to window below/right of the
409 current one. If there is no window below or right, go to
410 top-left window.
411 With count: go to Nth window (windows are numbered from
412 top-left to bottom-right). To obtain the window number see
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100413 |bufwinnr()| and |winnr()|. When N is larger than the number
414 of windows go to the last window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000415
416 *CTRL-W_W*
417CTRL-W W Without count: move cursor to window above/left of current
418 one. If there is no window above or left, go to bottom-right
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100419 window. With count: go to Nth window, like with CTRL-W w.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000420
421CTRL-W t *CTRL-W_t* *CTRL-W_CTRL-T*
422CTRL-W CTRL-T Move cursor to top-left window.
423
424CTRL-W b *CTRL-W_b* *CTRL-W_CTRL-B*
425CTRL-W CTRL-B Move cursor to bottom-right window.
426
427CTRL-W p *CTRL-W_p* *CTRL-W_CTRL-P*
428CTRL-W CTRL-P Go to previous (last accessed) window.
429
430 *CTRL-W_P* *E441*
431CTRL-W P Go to preview window. When there is no preview window this is
432 an error.
433 {not available when compiled without the |+quickfix| feature}
434
435If Visual mode is active and the new window is not for the same buffer, the
436Visual mode is ended. If the window is on the same buffer, the cursor
437position is set to keep the same Visual area selected.
438
439 *:winc* *:wincmd*
440These commands can also be executed with ":wincmd":
441
442:[count]winc[md] {arg}
443 Like executing CTRL-W [count] {arg}. Example: >
444 :wincmd j
445< Moves to the window below the current one.
446 This command is useful when a Normal mode cannot be used (for
447 the |CursorHold| autocommand event). Or when a Normal mode
448 command is inconvenient.
449 The count can also be a window number. Example: >
450 :exe nr . "wincmd w"
451< This goes to window "nr".
452
453==============================================================================
4545. Moving windows around *window-moving*
455
456CTRL-W r *CTRL-W_r* *CTRL-W_CTRL-R* *E443*
457CTRL-W CTRL-R Rotate windows downwards/rightwards. The first window becomes
458 the second one, the second one becomes the third one, etc.
459 The last window becomes the first window. The cursor remains
460 in the same window.
461 This only works within the row or column of windows that the
462 current window is in.
463
464 *CTRL-W_R*
465CTRL-W R Rotate windows upwards/leftwards. The second window becomes
466 the first one, the third one becomes the second one, etc. The
467 first window becomes the last window. The cursor remains in
468 the same window.
469 This only works within the row or column of windows that the
470 current window is in.
471
472CTRL-W x *CTRL-W_x* *CTRL-W_CTRL-X*
473CTRL-W CTRL-X Without count: Exchange current window with next one. If there
474 is no next window, exchange with previous window.
475 With count: Exchange current window with Nth window (first
476 window is 1). The cursor is put in the other window.
477 When vertical and horizontal window splits are mixed, the
478 exchange is only done in the row or column of windows that the
479 current window is in.
480
481The following commands can be used to change the window layout. For example,
482when there are two vertically split windows, CTRL-W K will change that in
483horizontally split windows. CTRL-W H does it the other way around.
484
485 *CTRL-W_K*
486CTRL-W K Move the current window to be at the very top, using the full
487 width of the screen. This works like closing the current
488 window and then creating another one with ":topleft split",
489 except that the current window contents is used for the new
490 window.
491
492 *CTRL-W_J*
493CTRL-W J Move the current window to be at the very bottom, using the
494 full width of the screen. This works like closing the current
495 window and then creating another one with ":botright split",
496 except that the current window contents is used for the new
497 window.
498
499 *CTRL-W_H*
500CTRL-W H Move the current window to be at the far left, using the
501 full height of the screen. This works like closing the
502 current window and then creating another one with
503 ":vert topleft split", except that the current window contents
504 is used for the new window.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200505 {not available when compiled without the |+vertsplit| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000506
507 *CTRL-W_L*
508CTRL-W L Move the current window to be at the far right, using the full
509 height of the screen. This works like closing the
510 current window and then creating another one with
511 ":vert botright split", except that the current window
512 contents is used for the new window.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200513 {not available when compiled without the |+vertsplit| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000514
Bram Moolenaar4c3f5362006-04-11 21:38:50 +0000515 *CTRL-W_T*
516CTRL-W T Move the current window to a new tab page. This fails if
517 there is only one window in the current tab page.
518 When a count is specified the new tab page will be opened
519 before the tab page with this index. Otherwise it comes after
520 the current tab page.
521
Bram Moolenaar071d4272004-06-13 20:20:40 +0000522==============================================================================
5236. Window resizing *window-resize*
524
525 *CTRL-W_=*
526CTRL-W = Make all windows (almost) equally high and wide, but use
527 'winheight' and 'winwidth' for the current window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000528 Windows with 'winfixheight' set keep their height and windows
529 with 'winfixwidth' set keep their width.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000530
531:res[ize] -N *:res* *:resize* *CTRL-W_-*
532CTRL-W - Decrease current window height by N (default 1).
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200533 If used after |:vertical|: decrease width by N.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000534
535:res[ize] +N *CTRL-W_+*
536CTRL-W + Increase current window height by N (default 1).
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200537 If used after |:vertical|: increase width by N.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000538
539:res[ize] [N]
540CTRL-W CTRL-_ *CTRL-W_CTRL-_* *CTRL-W__*
541CTRL-W _ Set current window height to N (default: highest possible).
542
543z{nr}<CR> Set current window height to {nr}.
544
545 *CTRL-W_<*
546CTRL-W < Decrease current window width by N (default 1).
547
548 *CTRL-W_>*
549CTRL-W > Increase current window width by N (default 1).
550
551:vertical res[ize] [N] *:vertical-resize* *CTRL-W_bar*
552CTRL-W | Set current window width to N (default: widest possible).
553
554You can also resize a window by dragging a status line up or down with the
555mouse. Or by dragging a vertical separator line left or right. This only
556works if the version of Vim that is being used supports the mouse and the
557'mouse' option has been set to enable it.
558
559The option 'winheight' ('wh') is used to set the minimal window height of the
560current window. This option is used each time another window becomes the
561current window. If the option is '0', it is disabled. Set 'winheight' to a
562very large value, e.g., '9999', to make the current window always fill all
563available space. Set it to a reasonable value, e.g., '10', to make editing in
564the current window comfortable.
565
566The equivalent 'winwidth' ('wiw') option is used to set the minimal width of
567the current window.
568
569When the option 'equalalways' ('ea') is set, all the windows are automatically
570made the same size after splitting or closing a window. If you don't set this
571option, splitting a window will reduce the size of the current window and
572leave the other windows the same. When closing a window, the extra lines are
573given to the window above it.
574
575The 'eadirection' option limits the direction in which the 'equalalways'
576option is applied. The default "both" resizes in both directions. When the
577value is "ver" only the heights of windows are equalized. Use this when you
578have manually resized a vertically split window and want to keep this width.
579Likewise, "hor" causes only the widths of windows to be equalized.
580
581The option 'cmdheight' ('ch') is used to set the height of the command-line.
582If you are annoyed by the |hit-enter| prompt for long messages, set this
583option to 2 or 3.
584
585If there is only one window, resizing that window will also change the command
586line height. If there are several windows, resizing the current window will
587also change the height of the window below it (and sometimes the window above
588it).
589
590The minimal height and width of a window is set with 'winminheight' and
591'winminwidth'. These are hard values, a window will never become smaller.
592
593==============================================================================
5947. Argument and buffer list commands *buffer-list*
595
596 args list buffer list meaning ~
5971. :[N]argument [N] 11. :[N]buffer [N] to arg/buf N
5982. :[N]next [file ..] 12. :[N]bnext [N] to Nth next arg/buf
5993. :[N]Next [N] 13. :[N]bNext [N] to Nth previous arg/buf
6004. :[N]previous [N] 14. :[N]bprevious [N] to Nth previous arg/buf
6015. :rewind / :first 15. :brewind / :bfirst to first arg/buf
6026. :last 16. :blast to last arg/buf
6037. :all 17. :ball edit all args/buffers
604 18. :unhide edit all loaded buffers
605 19. :[N]bmod [N] to Nth modified buf
606
607 split & args list split & buffer list meaning ~
60821. :[N]sargument [N] 31. :[N]sbuffer [N] split + to arg/buf N
60922. :[N]snext [file ..] 32. :[N]sbnext [N] split + to Nth next arg/buf
61023. :[N]sNext [N] 33. :[N]sbNext [N] split + to Nth previous arg/buf
61124. :[N]sprevious [N] 34. :[N]sbprevious [N] split + to Nth previous arg/buf
61225. :srewind / :sfirst 35. :sbrewind / :sbfirst split + to first arg/buf
61326. :slast 36. :sblast split + to last arg/buf
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000061427. :sall 37. :sball edit all args/buffers
Bram Moolenaar071d4272004-06-13 20:20:40 +0000615 38. :sunhide edit all loaded buffers
616 39. :[N]sbmod [N] split + to Nth modified buf
617
61840. :args list of arguments
61941. :buffers list of buffers
620
621The meaning of [N] depends on the command:
Bram Moolenaar24a98a02017-09-27 22:23:55 +0200622 [N] is the number of buffers to go forward/backward on 2/12/22/32,
623 3/13/23/33, and 4/14/24/34
Bram Moolenaar071d4272004-06-13 20:20:40 +0000624 [N] is an argument number, defaulting to current argument, for 1 and 21
625 [N] is a buffer number, defaulting to current buffer, for 11 and 31
626 [N] is a count for 19 and 39
627
628Note: ":next" is an exception, because it must accept a list of file names
629for compatibility with Vi.
630
631
632The argument list and multiple windows
633--------------------------------------
634
635The current position in the argument list can be different for each window.
636Remember that when doing ":e file", the position in the argument list stays
637the same, but you are not editing the file at that position. To indicate
638this, the file message (and the title, if you have one) shows
639"(file (N) of M)", where "(N)" is the current position in the file list, and
640"M" the number of files in the file list.
641
642All the entries in the argument list are added to the buffer list. Thus, you
643can also get to them with the buffer list commands, like ":bnext".
644
645:[N]al[l][!] [N] *:al* *:all* *:sal* *:sall*
646:[N]sal[l][!] [N]
647 Rearrange the screen to open one window for each argument.
648 All other windows are closed. When a count is given, this is
649 the maximum number of windows to open.
Bram Moolenaarfd2ac762006-03-01 22:09:21 +0000650 With the |:tab| modifier open a tab page for each argument.
651 When there are more arguments than 'tabpagemax' further ones
652 become split windows in the last tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000653 When the 'hidden' option is set, all buffers in closed windows
654 become hidden.
655 When 'hidden' is not set, and the 'autowrite' option is set,
656 modified buffers are written. Otherwise, windows that have
657 buffers that are modified are not removed, unless the [!] is
658 given, then they become hidden. But modified buffers are
659 never abandoned, so changes cannot get lost.
660 [N] is the maximum number of windows to open. 'winheight'
661 also limits the number of windows opened ('winwidth' if
662 |:vertical| was prepended).
663 Buf/Win Enter/Leave autocommands are not executed for the new
664 windows here, that's only done when they are really entered.
665
666:[N]sa[rgument][!] [++opt] [+cmd] [N] *:sa* *:sargument*
667 Short for ":split | argument [N]": split window and go to Nth
668 argument. But when there is no such argument, the window is
669 not split. Also see |++opt| and |+cmd|.
670
671:[N]sn[ext][!] [++opt] [+cmd] [file ..] *:sn* *:snext*
672 Short for ":split | [N]next": split window and go to Nth next
673 argument. But when there is no next file, the window is not
674 split. Also see |++opt| and |+cmd|.
675
676:[N]spr[evious][!] [++opt] [+cmd] [N] *:spr* *:sprevious*
677:[N]sN[ext][!] [++opt] [+cmd] [N] *:sN* *:sNext*
678 Short for ":split | [N]Next": split window and go to Nth
679 previous argument. But when there is no previous file, the
680 window is not split. Also see |++opt| and |+cmd|.
681
682 *:sre* *:srewind*
683:sre[wind][!] [++opt] [+cmd]
684 Short for ":split | rewind": split window and go to first
685 argument. But when there is no argument list, the window is
686 not split. Also see |++opt| and |+cmd|.
687
688 *:sfir* *:sfirst*
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000689:sfir[st] [++opt] [+cmd]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000690 Same as ":srewind".
691
692 *:sla* *:slast*
693:sla[st][!] [++opt] [+cmd]
694 Short for ":split | last": split window and go to last
695 argument. But when there is no argument list, the window is
696 not split. Also see |++opt| and |+cmd|.
697
698 *:dr* *:drop*
Bram Moolenaared39e1d2008-08-09 17:55:22 +0000699:dr[op] [++opt] [+cmd] {file} ..
Bram Moolenaar071d4272004-06-13 20:20:40 +0000700 Edit the first {file} in a window.
701 - If the file is already open in a window change to that
702 window.
703 - If the file is not open in a window edit the file in the
704 current window. If the current buffer can't be |abandon|ed,
705 the window is split first.
Bram Moolenaar51628222016-12-01 23:03:28 +0100706 - Windows that are not in the argument list or are not full
707 width will be closed if possible.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000708 The |argument-list| is set, like with the |:next| command.
709 The purpose of this command is that it can be used from a
710 program that wants Vim to edit another file, e.g., a debugger.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000711 When using the |:tab| modifier each argument is opened in a
712 tab page. The last window is used if it's empty.
Bram Moolenaared39e1d2008-08-09 17:55:22 +0000713 Also see |++opt| and |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000714
715==============================================================================
7168. Do a command in all buffers or windows *list-repeat*
717
718 *:windo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100719:[range]windo {cmd} Execute {cmd} in each window or if [range] is given
720 only in windows for which the window number lies in
721 the [range]. It works like doing this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000722 CTRL-W t
723 :{cmd}
724 CTRL-W w
725 :{cmd}
726 etc.
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000727< This only operates in the current tab page.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000728 When an error is detected on one window, further
Bram Moolenaar071d4272004-06-13 20:20:40 +0000729 windows will not be visited.
730 The last window (or where an error occurred) becomes
731 the current window.
732 {cmd} can contain '|' to concatenate several commands.
733 {cmd} must not open or close windows or reorder them.
Bram Moolenaar0751f512018-03-29 16:37:16 +0200734 {not in Vi}
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200735 Also see |:tabdo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|,
736 |:cfdo| and |:lfdo|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000737
738 *:bufdo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100739:[range]bufdo[!] {cmd} Execute {cmd} in each buffer in the buffer list or if
740 [range] is given only for buffers for which their
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100741 buffer number is in the [range]. It works like doing
Bram Moolenaara162bc52015-01-07 16:54:21 +0100742 this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000743 :bfirst
744 :{cmd}
745 :bnext
746 :{cmd}
747 etc.
748< When the current file can't be |abandon|ed and the [!]
749 is not present, the command fails.
750 When an error is detected on one buffer, further
751 buffers will not be visited.
752 Unlisted buffers are skipped.
753 The last buffer (or where an error occurred) becomes
754 the current buffer.
755 {cmd} can contain '|' to concatenate several commands.
756 {cmd} must not delete buffers or add buffers to the
757 buffer list.
758 Note: While this command is executing, the Syntax
759 autocommand event is disabled by adding it to
760 'eventignore'. This considerably speeds up editing
761 each buffer.
Bram Moolenaar0751f512018-03-29 16:37:16 +0200762 {not in Vi}
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200763 Also see |:tabdo|, |:argdo|, |:windo|, |:cdo|, |:ldo|,
764 |:cfdo| and |:lfdo|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000765
766Examples: >
767
768 :windo set nolist nofoldcolumn | normal zn
769
770This resets the 'list' option and disables folding in all windows. >
771
772 :bufdo set fileencoding= | update
773
774This resets the 'fileencoding' in each buffer and writes it if this changed
775the buffer. The result is that all buffers will use the 'encoding' encoding
776(if conversion works properly).
777
778==============================================================================
7799. Tag or file name under the cursor *window-tag*
780
781 *:sta* *:stag*
782:sta[g][!] [tagname]
783 Does ":tag[!] [tagname]" and splits the window for the found
784 tag. See also |:tag|.
785
786CTRL-W ] *CTRL-W_]* *CTRL-W_CTRL-]*
787CTRL-W CTRL-] Split current window in two. Use identifier under cursor as a
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200788 tag and jump to it in the new upper window.
789 In Visual mode uses the Visually selected text as a tag.
790 Make new window N high.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000791
792 *CTRL-W_g]*
793CTRL-W g ] Split current window in two. Use identifier under cursor as a
794 tag and perform ":tselect" on it in the new upper window.
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200795 In Visual mode uses the Visually selected text as a tag.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000796 Make new window N high.
797
798 *CTRL-W_g_CTRL-]*
799CTRL-W g CTRL-] Split current window in two. Use identifier under cursor as a
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200800 tag and perform ":tjump" on it in the new upper window.
801 In Visual mode uses the Visually selected text as a tag.
802 Make new window N high.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000803
804CTRL-W f *CTRL-W_f* *CTRL-W_CTRL-F*
805CTRL-W CTRL-F Split current window in two. Edit file name under cursor.
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000806 Like ":split gf", but window isn't split if the file does not
Bram Moolenaar071d4272004-06-13 20:20:40 +0000807 exist.
808 Uses the 'path' variable as a list of directory names where to
809 look for the file. Also the path for current file is
810 used to search for the file name.
811 If the name is a hypertext link that looks like
812 "type://machine/path", only "/path" is used.
813 If a count is given, the count'th matching file is edited.
814 {not available when the |+file_in_path| feature was disabled
815 at compile time}
816
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000817CTRL-W F *CTRL-W_F*
818 Split current window in two. Edit file name under cursor and
819 jump to the line number following the file name. See |gF| for
820 details on how the line number is obtained.
Bram Moolenaar57657d82006-04-21 22:12:41 +0000821 {not available when the |+file_in_path| feature was disabled
822 at compile time}
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000823
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000824CTRL-W gf *CTRL-W_gf*
825 Open a new tab page and edit the file name under the cursor.
826 Like "tab split" and "gf", but the new tab page isn't created
827 if the file does not exist.
828 {not available when the |+file_in_path| feature was disabled
829 at compile time}
830
Bram Moolenaar57657d82006-04-21 22:12:41 +0000831CTRL-W gF *CTRL-W_gF*
832 Open a new tab page and edit the file name under the cursor
833 and jump to the line number following the file name. Like
834 "tab split" and "gF", but the new tab page isn't created if
835 the file does not exist.
836 {not available when the |+file_in_path| feature was disabled
837 at compile time}
838
Bram Moolenaar071d4272004-06-13 20:20:40 +0000839Also see |CTRL-W_CTRL-I|: open window for an included file that includes
840the keyword under the cursor.
841
842==============================================================================
84310. The preview window *preview-window*
844
845The preview window is a special window to show (preview) another file. It is
846normally a small window used to show an include file or definition of a
847function.
848{not available when compiled without the |+quickfix| feature}
849
Bram Moolenaarc270d802006-03-11 21:29:41 +0000850There can be only one preview window (per tab page). It is created with one
851of the commands below. The 'previewheight' option can be set to specify the
852height of the preview window when it's opened. The 'previewwindow' option is
853set in the preview window to be able to recognize it. The 'winfixheight'
854option is set to have it keep the same height when opening/closing other
855windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000856
857 *:pta* *:ptag*
858:pta[g][!] [tagname]
859 Does ":tag[!] [tagname]" and shows the found tag in a
860 "Preview" window without changing the current buffer or cursor
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000861 position. If a "Preview" window already exists, it is re-used
Bram Moolenaar071d4272004-06-13 20:20:40 +0000862 (like a help window is). If a new one is opened,
863 'previewheight' is used for the height of the window. See
864 also |:tag|.
865 See below for an example. |CursorHold-example|
866 Small difference from |:tag|: When [tagname] is equal to the
867 already displayed tag, the position in the matching tag list
868 is not reset. This makes the CursorHold example work after a
869 |:ptnext|.
870
871CTRL-W z *CTRL-W_z*
872CTRL-W CTRL-Z *CTRL-W_CTRL-Z* *:pc* *:pclose*
873:pc[lose][!] Close any "Preview" window currently open. When the 'hidden'
874 option is set, or when the buffer was changed and the [!] is
875 used, the buffer becomes hidden (unless there is another
876 window editing it). The command fails if any "Preview" buffer
877 cannot be closed. See also |:close|.
878
879 *:pp* *:ppop*
880:[count]pp[op][!]
881 Does ":[count]pop[!]" in the preview window. See |:pop| and
882 |:ptag|. {not in Vi}
883
884CTRL-W } *CTRL-W_}*
885 Use identifier under cursor as a tag and perform a :ptag on
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000886 it. Make the new Preview window (if required) N high. If N is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000887 not given, 'previewheight' is used.
888
889CTRL-W g } *CTRL-W_g}*
890 Use identifier under cursor as a tag and perform a :ptjump on
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000891 it. Make the new Preview window (if required) N high. If N is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000892 not given, 'previewheight' is used.
893
894 *:ped* *:pedit*
895:ped[it][!] [++opt] [+cmd] {file}
896 Edit {file} in the preview window. The preview window is
897 opened like with |:ptag|. The current window and cursor
898 position isn't changed. Useful example: >
899 :pedit +/fputc /usr/include/stdio.h
900<
901 *:ps* *:psearch*
902:[range]ps[earch][!] [count] [/]pattern[/]
903 Works like |:ijump| but shows the found match in the preview
904 window. The preview window is opened like with |:ptag|. The
905 current window and cursor position isn't changed. Useful
906 example: >
907 :psearch popen
908< Like with the |:ptag| command, you can use this to
909 automatically show information about the word under the
910 cursor. This is less clever than using |:ptag|, but you don't
911 need a tags file and it will also find matches in system
912 include files. Example: >
913 :au! CursorHold *.[ch] nested exe "silent! psearch " . expand("<cword>")
914< Warning: This can be slow.
915
916Example *CursorHold-example* >
917
918 :au! CursorHold *.[ch] nested exe "silent! ptag " . expand("<cword>")
919
920This will cause a ":ptag" to be executed for the keyword under the cursor,
921when the cursor hasn't moved for the time set with 'updatetime'. The "nested"
922makes other autocommands be executed, so that syntax highlighting works in the
923preview window. The "silent!" avoids an error message when the tag could not
924be found. Also see |CursorHold|. To disable this again: >
925
926 :au! CursorHold
927
928A nice addition is to highlight the found tag, avoid the ":ptag" when there
929is no word under the cursor, and a few other things: >
930
931 :au! CursorHold *.[ch] nested call PreviewWord()
932 :func PreviewWord()
933 : if &previewwindow " don't do this in the preview window
934 : return
935 : endif
936 : let w = expand("<cword>") " get the word under cursor
937 : if w =~ '\a' " if the word contains a letter
938 :
939 : " Delete any existing highlight before showing another tag
940 : silent! wincmd P " jump to preview window
941 : if &previewwindow " if we really get there...
942 : match none " delete existing highlight
943 : wincmd p " back to old window
944 : endif
945 :
946 : " Try displaying a matching tag for the word under the cursor
947 : try
948 : exe "ptag " . w
949 : catch
950 : return
951 : endtry
952 :
953 : silent! wincmd P " jump to preview window
954 : if &previewwindow " if we really get there...
955 : if has("folding")
956 : silent! .foldopen " don't want a closed fold
957 : endif
958 : call search("$", "b") " to end of previous line
959 : let w = substitute(w, '\\', '\\\\', "")
960 : call search('\<\V' . w . '\>') " position cursor on match
961 : " Add a match highlight to the word at this position
962 : hi previewWord term=bold ctermbg=green guibg=green
963 : exe 'match previewWord "\%' . line(".") . 'l\%' . col(".") . 'c\k*"'
964 : wincmd p " back to old window
965 : endif
966 : endif
967 :endfun
968
969==============================================================================
97011. Using hidden buffers *buffer-hidden*
971
972A hidden buffer is not displayed in a window, but is still loaded into memory.
973This makes it possible to jump from file to file, without the need to read or
974write the file every time you get another buffer in a window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000975
976 *:buffer-!*
977If the option 'hidden' ('hid') is set, abandoned buffers are kept for all
978commands that start editing another file: ":edit", ":next", ":tag", etc. The
979commands that move through the buffer list sometimes make the current buffer
980hidden although the 'hidden' option is not set. This happens when a buffer is
981modified, but is forced (with '!') to be removed from a window, and
982'autowrite' is off or the buffer can't be written.
983
984You can make a hidden buffer not hidden by starting to edit it with any
985command. Or by deleting it with the ":bdelete" command.
986
987The 'hidden' is global, it is used for all buffers. The 'bufhidden' option
988can be used to make an exception for a specific buffer. It can take these
989values:
990 <empty> Use the value of 'hidden'.
991 hide Hide this buffer, also when 'hidden' is not set.
992 unload Don't hide but unload this buffer, also when 'hidden'
993 is set.
994 delete Delete the buffer.
995
996 *hidden-quit*
997When you try to quit Vim while there is a hidden, modified buffer, you will
998get an error message and Vim will make that buffer the current buffer. You
999can then decide to write this buffer (":wq") or quit without writing (":q!").
1000Be careful: there may be more hidden, modified buffers!
1001
1002A buffer can also be unlisted. This means it exists, but it is not in the
1003list of buffers. |unlisted-buffer|
1004
1005
Bram Moolenaard51cb702015-07-21 15:03:06 +02001006:files[!] [flags] *:files*
1007:buffers[!] [flags] *:buffers* *:ls*
1008:ls[!] [flags]
1009 Show all buffers. Example:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001010
Bram Moolenaar97d62492012-11-15 21:28:22 +01001011 1 #h "/test/text" line 1 ~
1012 2u "asdf" line 0 ~
1013 3 %a + "version.c" line 1 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00001014
1015 When the [!] is included the list will show unlisted buffers
1016 (the term "unlisted" is a bit confusing then...).
1017
1018 Each buffer has a unique number. That number will not change,
Bram Moolenaar0122c402015-02-03 19:13:34 +01001019 thus you can always go to a specific buffer with ":buffer N"
1020 or "N CTRL-^", where N is the buffer number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001021
1022 Indicators (chars in the same column are mutually exclusive):
1023 u an unlisted buffer (only displayed when [!] is used)
1024 |unlisted-buffer|
1025 % the buffer in the current window
1026 # the alternate buffer for ":e #" and CTRL-^
1027 a an active buffer: it is loaded and visible
1028 h a hidden buffer: It is loaded, but currently not
1029 displayed in a window |hidden-buffer|
1030 - a buffer with 'modifiable' off
1031 = a readonly buffer
Bram Moolenaarc572da52017-08-27 16:52:01 +02001032 R a terminal buffer with a running job
1033 F a terminal buffer with a finished job
Bram Moolenaar37c64c72017-09-19 22:06:03 +02001034 ? a terminal buffer without a job: `:terminal NONE`
Bram Moolenaar071d4272004-06-13 20:20:40 +00001035 + a modified buffer
1036 x a buffer with read errors
1037
Bram Moolenaard51cb702015-07-21 15:03:06 +02001038 [flags] can be a combination of the following characters,
1039 which restrict the buffers to be listed:
1040 + modified buffers
1041 - buffers with 'modifiable' off
1042 = readonly buffers
1043 a active buffers
Bram Moolenaare392eb42015-11-19 20:38:09 +01001044 u unlisted buffers (overrides the "!")
Bram Moolenaard51cb702015-07-21 15:03:06 +02001045 h hidden buffers
1046 x buffers with a read error
1047 % current buffer
1048 # alternate buffer
Bram Moolenaar0751f512018-03-29 16:37:16 +02001049 R terminal buffers with a running job
1050 F terminal buffers with a finished job
1051 ? terminal buffers without a job: `:terminal NONE`
Bram Moolenaard51cb702015-07-21 15:03:06 +02001052 Combining flags means they are "and"ed together, e.g.:
1053 h+ hidden buffers which are modified
1054 a+ active buffers which are modified
1055
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02001056 When using |:filter| the pattern is matched against the
1057 displayed buffer name, e.g.: >
1058 filter /\.vim/ ls
1059<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001060 *:bad* *:badd*
1061:bad[d] [+lnum] {fname}
1062 Add file name {fname} to the buffer list, without loading it.
1063 If "lnum" is specified, the cursor will be positioned at that
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001064 line when the buffer is first entered. Note that other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001065 commands after the + will be ignored.
1066
1067:[N]bd[elete][!] *:bd* *:bdel* *:bdelete* *E516*
1068:bd[elete][!] [N]
1069 Unload buffer [N] (default: current buffer) and delete it from
1070 the buffer list. If the buffer was changed, this fails,
1071 unless when [!] is specified, in which case changes are lost.
1072 The file remains unaffected. Any windows for this buffer are
1073 closed. If buffer [N] is the current buffer, another buffer
1074 will be displayed instead. This is the most recent entry in
1075 the jump list that points into a loaded buffer.
1076 Actually, the buffer isn't completely deleted, it is removed
1077 from the buffer list |unlisted-buffer| and option values,
1078 variables and mappings/abbreviations for the buffer are
Bram Moolenaar4d84d932014-11-30 14:50:16 +01001079 cleared. Examples: >
1080 :.,$-bdelete " delete buffers from the current one to
1081 " last but one
1082 :%bdelete " delete all buffers
1083<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001084
1085:bdelete[!] {bufname} *E93* *E94*
1086 Like ":bdelete[!] [N]", but buffer given by name. Note that a
1087 buffer whose name is a number cannot be referenced by that
1088 name; use the buffer number instead. Insert a backslash
1089 before a space in a buffer name.
1090
1091:bdelete[!] N1 N2 ...
1092 Do ":bdelete[!]" for buffer N1, N2, etc. The arguments can be
1093 buffer numbers or buffer names (but not buffer names that are
1094 a number). Insert a backslash before a space in a buffer
1095 name.
1096
1097:N,Mbdelete[!] Do ":bdelete[!]" for all buffers in the range N to M
1098 |inclusive|.
1099
1100:[N]bw[ipeout][!] *:bw* *:bwipe* *:bwipeout* *E517*
1101:bw[ipeout][!] {bufname}
1102:N,Mbw[ipeout][!]
1103:bw[ipeout][!] N1 N2 ...
Bram Moolenaardf1bdc92006-02-23 21:32:16 +00001104 Like |:bdelete|, but really delete the buffer. Everything
1105 related to the buffer is lost. All marks in this buffer
1106 become invalid, option settings are lost, etc. Don't use this
Bram Moolenaar4d84d932014-11-30 14:50:16 +01001107 unless you know what you are doing. Examples: >
1108 :.+,$bwipeout " wipe out all buffers after the current
1109 " one
1110 :%bwipeout " wipe out all buffers
1111<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001112
1113:[N]bun[load][!] *:bun* *:bunload* *E515*
1114:bun[load][!] [N]
1115 Unload buffer [N] (default: current buffer). The memory
1116 allocated for this buffer will be freed. The buffer remains
1117 in the buffer list.
1118 If the buffer was changed, this fails, unless when [!] is
1119 specified, in which case the changes are lost.
1120 Any windows for this buffer are closed. If buffer [N] is the
1121 current buffer, another buffer will be displayed instead.
1122 This is the most recent entry in the jump list that points
1123 into a loaded buffer.
1124
1125:bunload[!] {bufname}
1126 Like ":bunload[!] [N]", but buffer given by name. Note that a
1127 buffer whose name is a number cannot be referenced by that
1128 name; use the buffer number instead. Insert a backslash
1129 before a space in a buffer name.
1130
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 Moolenaar9c8d9e12014-09-19 20:07:26 +02001147:[N]b[uffer][!] [+cmd] {bufname}
Bram Moolenaarc1a11ed2008-06-24 22:09:24 +00001148 Edit buffer for {bufname} from the buffer list. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001149 |:buffer-!| for [!]. This will also edit a buffer that is not
1150 in the buffer list, without setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001151 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001152
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001153:[N]sb[uffer] [+cmd] [N] *:sb* *:sbuffer*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001154 Split window and edit buffer [N] from the buffer list. If [N]
1155 is not given, the current buffer is edited. Respects the
1156 "useopen" setting of 'switchbuf' when splitting. This will
1157 also edit a buffer that is not in the buffer list, without
1158 setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001159 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001160
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001161:[N]sb[uffer] [+cmd] {bufname}
Bram Moolenaarc1a11ed2008-06-24 22:09:24 +00001162 Split window and edit buffer for {bufname} from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001163 list. This will also edit a buffer that is not in the buffer
1164 list, without setting the 'buflisted' flag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001165 Note: If what you want to do is split the buffer, make a copy
1166 under another name, you can do it this way: >
1167 :w foobar | sp #
Bram Moolenaar12969c02015-09-08 23:36:10 +02001168< Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001169
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001170:[N]bn[ext][!] [+cmd] [N] *:bn* *:bnext* *E87*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001171 Go to [N]th next buffer in buffer list. [N] defaults to one.
1172 Wraps around the end of the buffer list.
1173 See |:buffer-!| for [!].
Bram Moolenaar12969c02015-09-08 23:36:10 +02001174 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001175 If you are in a help buffer, this takes you to the next help
1176 buffer (if there is one). Similarly, if you are in a normal
1177 (non-help) buffer, this takes you to the next normal buffer.
1178 This is so that if you have invoked help, it doesn't get in
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001179 the way when you're browsing code/text buffers. The next three
Bram Moolenaar071d4272004-06-13 20:20:40 +00001180 commands also work like this.
1181
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001182
Bram Moolenaar071d4272004-06-13 20:20:40 +00001183 *:sbn* *:sbnext*
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001184:[N]sbn[ext] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001185 Split window and go to [N]th next buffer in buffer list.
1186 Wraps around the end of the buffer list. Uses 'switchbuf'
Bram Moolenaar12969c02015-09-08 23:36:10 +02001187 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001188
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001189:[N]bN[ext][!] [+cmd] [N] *:bN* *:bNext* *:bp* *:bprevious* *E88*
1190:[N]bp[revious][!] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001191 Go to [N]th previous buffer in buffer list. [N] defaults to
1192 one. Wraps around the start of the buffer list.
1193 See |:buffer-!| for [!] and 'switchbuf'.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001194 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001195
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001196:[N]sbN[ext] [+cmd] [N] *:sbN* *:sbNext* *:sbp* *:sbprevious*
1197:[N]sbp[revious] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001198 Split window and go to [N]th previous buffer in buffer list.
1199 Wraps around the start of the buffer list.
1200 Uses 'switchbuf'.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001201 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001202
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001203:br[ewind][!] [+cmd] *:br* *:brewind*
1204 Go to first buffer in buffer list. If the buffer list is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001205 empty, go to the first unlisted buffer.
1206 See |:buffer-!| for [!].
1207
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001208:bf[irst] [+cmd] *:bf* *:bfirst*
1209 Same as |:brewind|.
1210 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001211
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001212:sbr[ewind] [+cmd] *:sbr* *:sbrewind*
1213 Split window and go to first buffer in buffer list. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001214 buffer list is empty, go to the first unlisted buffer.
1215 Respects the 'switchbuf' option.
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001216 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001217
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001218:sbf[irst] [+cmd] *:sbf* *:sbfirst*
1219 Same as ":sbrewind".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001220
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001221:bl[ast][!] [+cmd] *:bl* *:blast*
1222 Go to last buffer in buffer list. If the buffer list is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001223 empty, go to the last unlisted buffer.
1224 See |:buffer-!| for [!].
1225
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001226:sbl[ast] [+cmd] *:sbl* *:sblast*
1227 Split window and go to last buffer in buffer list. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001228 buffer list is empty, go to the last unlisted buffer.
1229 Respects 'switchbuf' option.
1230
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001231:[N]bm[odified][!] [+cmd] [N] *:bm* *:bmodified* *E84*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001232 Go to [N]th next modified buffer. Note: this command also
1233 finds unlisted buffers. If there is no modified buffer the
1234 command fails.
1235
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001236:[N]sbm[odified] [+cmd] [N] *:sbm* *:sbmodified*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001237 Split window and go to [N]th next modified buffer.
1238 Respects 'switchbuf' option.
1239 Note: this command also finds buffers not in the buffer list.
1240
1241:[N]unh[ide] [N] *:unh* *:unhide* *:sun* *:sunhide*
1242:[N]sun[hide] [N]
1243 Rearrange the screen to open one window for each loaded buffer
1244 in the buffer list. When a count is given, this is the
1245 maximum number of windows to open.
1246
1247:[N]ba[ll] [N] *:ba* *:ball* *:sba* *:sball*
1248:[N]sba[ll] [N] Rearrange the screen to open one window for each buffer in
1249 the buffer list. When a count is given, this is the maximum
1250 number of windows to open. 'winheight' also limits the number
1251 of windows opened ('winwidth' if |:vertical| was prepended).
1252 Buf/Win Enter/Leave autocommands are not executed for the new
1253 windows here, that's only done when they are really entered.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +00001254 When the |:tab| modifier is used new windows are opened in a
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00001255 new tab, up to 'tabpagemax'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001256
1257Note: All the commands above that start editing another buffer, keep the
1258'readonly' flag as it was. This differs from the ":edit" command, which sets
1259the 'readonly' flag each time the file is read.
1260
1261==============================================================================
126212. Special kinds of buffers *special-buffers*
1263
1264Instead of containing the text of a file, buffers can also be used for other
1265purposes. A few options can be set to change the behavior of a buffer:
1266 'bufhidden' what happens when the buffer is no longer displayed
1267 in a window.
1268 'buftype' what kind of a buffer this is
1269 'swapfile' whether the buffer will have a swap file
1270 'buflisted' buffer shows up in the buffer list
1271
1272A few useful kinds of a buffer:
1273
Bram Moolenaar280f1262006-01-30 00:14:18 +00001274quickfix Used to contain the error list or the location list. See
1275 |:cwindow| and |:lwindow|. This command sets the 'buftype'
1276 option to "quickfix". You are not supposed to change this!
1277 'swapfile' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001278
1279help Contains a help file. Will only be created with the |:help|
1280 command. The flag that indicates a help buffer is internal
1281 and can't be changed. The 'buflisted' option will be reset
1282 for a help buffer.
1283
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001284terminal A terminal window buffer, see |terminal|. The contents cannot
1285 be read or changed until the job ends.
1286
Bram Moolenaar677ee682005-01-27 14:41:15 +00001287directory Displays directory contents. Can be used by a file explorer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001288 plugin. The buffer is created with these settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001289 :setlocal buftype=nowrite
1290 :setlocal bufhidden=delete
1291 :setlocal noswapfile
Bram Moolenaar071d4272004-06-13 20:20:40 +00001292< The buffer name is the name of the directory and is adjusted
1293 when using the |:cd| command.
1294
1295scratch Contains text that can be discarded at any time. It is kept
1296 when closing the window, it must be deleted explicitly.
1297 Settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001298 :setlocal buftype=nofile
1299 :setlocal bufhidden=hide
1300 :setlocal noswapfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001301< The buffer name can be used to identify the buffer, if you
1302 give it a meaningful name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001303
1304 *unlisted-buffer*
1305unlisted The buffer is not in the buffer list. It is not used for
1306 normal editing, but to show a help file, remember a file name
1307 or marks. The ":bdelete" command will also set this option,
1308 thus it doesn't completely delete the buffer. Settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001309 :setlocal nobuflisted
Bram Moolenaar071d4272004-06-13 20:20:40 +00001310<
1311
1312 vim:tw=78:ts=8:ft=help:norl: