blob: 81042dbcdf8da97f9c5f50494c85b5c374dc6949 [file] [log] [blame]
Bram Moolenaar7571d552016-08-18 22:54:46 +02001*windows.txt* For Vim version 7.4. Last change: 2016 Aug 18
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 Moolenaar7571d552016-08-18 22:54:46 +020078 *window-ID*
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
225Note that the 'splitbelow' and 'splitright' options influence where a new
226window will appear.
227
228 *:vert* *:vertical*
229:vert[ical] {cmd}
230 Execute {cmd}. If it contains a command that splits a window,
231 it will be split vertically.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000232 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000233
234:lefta[bove] {cmd} *:lefta* *:leftabove*
235:abo[veleft] {cmd} *:abo* *:aboveleft*
236 Execute {cmd}. If it contains a command that splits a window,
237 it will be opened left (vertical split) or above (horizontal
238 split) the current window. Overrules 'splitbelow' and
239 'splitright'.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000240 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000241
242:rightb[elow] {cmd} *:rightb* *:rightbelow*
243:bel[owright] {cmd} *:bel* *:belowright*
244 Execute {cmd}. If it contains a command that splits a window,
245 it will be opened right (vertical split) or below (horizontal
246 split) the current window. Overrules 'splitbelow' and
247 'splitright'.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000248 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000249
250 *:topleft* *E442*
251:to[pleft] {cmd}
252 Execute {cmd}. If it contains a command that splits a window,
253 it will appear at the top and occupy the full width of the Vim
254 window. When the split is vertical the window appears at the
255 far left and occupies the full height of the Vim window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000256 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000257
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200258 *:bo* *:botright*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000259:bo[tright] {cmd}
260 Execute {cmd}. If it contains a command that splits a window,
261 it will appear at the bottom and occupy the full width of the
262 Vim window. When the split is vertical the window appears at
263 the far right and occupies the full height of the Vim window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000264 Doesn't work for |:execute| and |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000265
266These command modifiers can be combined to make a vertically split window
267occupy the full height. Example: >
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200268 :vertical topleft split tags
Bram Moolenaar071d4272004-06-13 20:20:40 +0000269Opens a vertically split, full-height window on the "tags" file at the far
270left of the Vim window.
271
272
273Closing a window
274----------------
275
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100276:q[uit]
277:{count}q[uit]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000278CTRL-W q *CTRL-W_q*
279CTRL-W CTRL-Q *CTRL-W_CTRL-Q*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100280 Without {count}: Quit the current window. If {count} is
281 given quit the {count} window.
282
283 When quitting the last window (not counting a help window),
284 exit Vim.
285
Bram Moolenaar071d4272004-06-13 20:20:40 +0000286 When 'hidden' is set, and there is only one window for the
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100287 current buffer, it becomes hidden. When 'hidden' is not set,
288 and there is only one window for the current buffer, and the
289 buffer was changed, the command fails.
290
Bram Moolenaared32d942014-12-06 23:33:00 +0100291 (Note: CTRL-Q does not work on all terminals).
292
293 If [count] is greater than the last window number the last
294 window will be closed: >
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100295 :1quit " quit the first window
296 :$quit " quit the last window
297 :9quit " quit the last window
298 " if there are less than 9 windows opened
299 :-quit " quit the previews window
300 :+quit " quit the next window
Bram Moolenaared32d942014-12-06 23:33:00 +0100301 :+2quit " quit the second next window
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100302<
303:q[uit]!
304:{count}q[uit]!
305 Without {count}: Quit the current window. If {count} is
306 given quit the {count} window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000307
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100308 If this was the last window for a buffer, any changes to that
309 buffer are lost. When quitting the last window (not counting
310 help windows), exit Vim. The contents of the buffer are lost,
311 even when 'hidden' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000312
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100313:clo[se][!]
314:{count}clo[se][!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000315CTRL-W c *CTRL-W_c* *:clo* *:close*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100316 Without {count}: Close the current window. If {count} is
317 given close the {count} window.
318
319 When the 'hidden' option is set, or when the buffer was
320 changed and the [!] is used, the buffer becomes hidden (unless
321 there is another window editing it).
322
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000323 When there is only one window in the current tab page and
324 there is another tab page, this closes the current tab page.
325 |tab-page|.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100326
Bram Moolenaar071d4272004-06-13 20:20:40 +0000327 This command fails when: *E444*
328 - There is only one window on the screen.
329 - When 'hidden' is not set, [!] is not used, the buffer has
330 changes, and there is no other window on this buffer.
331 Changes to the buffer are not written and won't get lost, so
332 this is a "safe" command.
333
334CTRL-W CTRL-C *CTRL-W_CTRL-C*
335 You might have expected that CTRL-W CTRL-C closes the current
336 window, but that does not work, because the CTRL-C cancels the
337 command.
338
339 *:hide*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100340:hid[e]
341:{count}hid[e]
342 Quit the current window, unless it is the last window on the
343 screen. For {count} see |:quit| command.
344
345 The buffer becomes hidden (unless there is another window
Bram Moolenaared32d942014-12-06 23:33:00 +0100346 editing it or 'bufhidden' is "unload", "delete" or "wipe").
347 If the window is the last one in the current tab page the tab
348 page is closed. |tab-page|
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100349
350 The value of 'hidden' is irrelevant for this command. Changes
351 to the buffer are not written and won't get lost, so this is a
352 "safe" command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000353
354:hid[e] {cmd} Execute {cmd} with 'hidden' is set. The previous value of
355 'hidden' is restored after {cmd} has been executed.
356 Example: >
357 :hide edit Makefile
358< This will edit "Makefile", and hide the current buffer if it
359 has any changes.
360
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100361:on[ly][!]
362:{count}on[ly][!]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000363CTRL-W o *CTRL-W_o* *E445*
364CTRL-W CTRL-O *CTRL-W_CTRL-O* *:on* *:only*
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100365 Make the current window the only one on the screen. All other
366 windows are closed. For {count} see |:quit| command.
367
Bram Moolenaar071d4272004-06-13 20:20:40 +0000368 When the 'hidden' option is set, all buffers in closed windows
369 become hidden.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100370
Bram Moolenaar071d4272004-06-13 20:20:40 +0000371 When 'hidden' is not set, and the 'autowrite' option is set,
372 modified buffers are written. Otherwise, windows that have
373 buffers that are modified are not removed, unless the [!] is
374 given, then they become hidden. But modified buffers are
375 never abandoned, so changes cannot get lost.
376
377==============================================================================
3784. Moving cursor to other windows *window-move-cursor*
379
380CTRL-W <Down> *CTRL-W_<Down>*
381CTRL-W CTRL-J *CTRL-W_CTRL-J* *CTRL-W_j*
382CTRL-W j Move cursor to Nth window below current one. Uses the cursor
383 position to select between alternatives.
384
385CTRL-W <Up> *CTRL-W_<Up>*
386CTRL-W CTRL-K *CTRL-W_CTRL-K* *CTRL-W_k*
387CTRL-W k Move cursor to Nth window above current one. Uses the cursor
388 position to select between alternatives.
389
390CTRL-W <Left> *CTRL-W_<Left>*
391CTRL-W CTRL-H *CTRL-W_CTRL-H*
392CTRL-W <BS> *CTRL-W_<BS>* *CTRL-W_h*
393CTRL-W h Move cursor to Nth window left of current one. Uses the
394 cursor position to select between alternatives.
395
396CTRL-W <Right> *CTRL-W_<Right>*
397CTRL-W CTRL-L *CTRL-W_CTRL-L* *CTRL-W_l*
398CTRL-W l Move cursor to Nth window right of current one. Uses the
399 cursor position to select between alternatives.
400
401CTRL-W w *CTRL-W_w* *CTRL-W_CTRL-W*
402CTRL-W CTRL-W Without count: move cursor to window below/right of the
403 current one. If there is no window below or right, go to
404 top-left window.
405 With count: go to Nth window (windows are numbered from
406 top-left to bottom-right). To obtain the window number see
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100407 |bufwinnr()| and |winnr()|. When N is larger than the number
408 of windows go to the last window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000409
410 *CTRL-W_W*
411CTRL-W W Without count: move cursor to window above/left of current
412 one. If there is no window above or left, go to bottom-right
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100413 window. With count: go to Nth window, like with CTRL-W w.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000414
415CTRL-W t *CTRL-W_t* *CTRL-W_CTRL-T*
416CTRL-W CTRL-T Move cursor to top-left window.
417
418CTRL-W b *CTRL-W_b* *CTRL-W_CTRL-B*
419CTRL-W CTRL-B Move cursor to bottom-right window.
420
421CTRL-W p *CTRL-W_p* *CTRL-W_CTRL-P*
422CTRL-W CTRL-P Go to previous (last accessed) window.
423
424 *CTRL-W_P* *E441*
425CTRL-W P Go to preview window. When there is no preview window this is
426 an error.
427 {not available when compiled without the |+quickfix| feature}
428
429If Visual mode is active and the new window is not for the same buffer, the
430Visual mode is ended. If the window is on the same buffer, the cursor
431position is set to keep the same Visual area selected.
432
433 *:winc* *:wincmd*
434These commands can also be executed with ":wincmd":
435
436:[count]winc[md] {arg}
437 Like executing CTRL-W [count] {arg}. Example: >
438 :wincmd j
439< Moves to the window below the current one.
440 This command is useful when a Normal mode cannot be used (for
441 the |CursorHold| autocommand event). Or when a Normal mode
442 command is inconvenient.
443 The count can also be a window number. Example: >
444 :exe nr . "wincmd w"
445< This goes to window "nr".
446
447==============================================================================
4485. Moving windows around *window-moving*
449
450CTRL-W r *CTRL-W_r* *CTRL-W_CTRL-R* *E443*
451CTRL-W CTRL-R Rotate windows downwards/rightwards. The first window becomes
452 the second one, the second one becomes the third one, etc.
453 The last window becomes the first window. The cursor remains
454 in the same window.
455 This only works within the row or column of windows that the
456 current window is in.
457
458 *CTRL-W_R*
459CTRL-W R Rotate windows upwards/leftwards. The second window becomes
460 the first one, the third one becomes the second one, etc. The
461 first window becomes the last window. The cursor remains in
462 the same window.
463 This only works within the row or column of windows that the
464 current window is in.
465
466CTRL-W x *CTRL-W_x* *CTRL-W_CTRL-X*
467CTRL-W CTRL-X Without count: Exchange current window with next one. If there
468 is no next window, exchange with previous window.
469 With count: Exchange current window with Nth window (first
470 window is 1). The cursor is put in the other window.
471 When vertical and horizontal window splits are mixed, the
472 exchange is only done in the row or column of windows that the
473 current window is in.
474
475The following commands can be used to change the window layout. For example,
476when there are two vertically split windows, CTRL-W K will change that in
477horizontally split windows. CTRL-W H does it the other way around.
478
479 *CTRL-W_K*
480CTRL-W K Move the current window to be at the very top, using the full
481 width of the screen. This works like closing the current
482 window and then creating another one with ":topleft split",
483 except that the current window contents is used for the new
484 window.
485
486 *CTRL-W_J*
487CTRL-W J Move the current window to be at the very bottom, using the
488 full width of the screen. This works like closing the current
489 window and then creating another one with ":botright split",
490 except that the current window contents is used for the new
491 window.
492
493 *CTRL-W_H*
494CTRL-W H Move the current window to be at the far left, using the
495 full height of the screen. This works like closing the
496 current window and then creating another one with
497 ":vert topleft split", except that the current window contents
498 is used for the new window.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200499 {not available when compiled without the |+vertsplit| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000500
501 *CTRL-W_L*
502CTRL-W L Move the current window to be at the far right, using the full
503 height of the screen. This works like closing the
504 current window and then creating another one with
505 ":vert botright split", except that the current window
506 contents is used for the new window.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200507 {not available when compiled without the |+vertsplit| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000508
Bram Moolenaar4c3f5362006-04-11 21:38:50 +0000509 *CTRL-W_T*
510CTRL-W T Move the current window to a new tab page. This fails if
511 there is only one window in the current tab page.
512 When a count is specified the new tab page will be opened
513 before the tab page with this index. Otherwise it comes after
514 the current tab page.
515
Bram Moolenaar071d4272004-06-13 20:20:40 +0000516==============================================================================
5176. Window resizing *window-resize*
518
519 *CTRL-W_=*
520CTRL-W = Make all windows (almost) equally high and wide, but use
521 'winheight' and 'winwidth' for the current window.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +0000522 Windows with 'winfixheight' set keep their height and windows
523 with 'winfixwidth' set keep their width.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000524
525:res[ize] -N *:res* *:resize* *CTRL-W_-*
526CTRL-W - Decrease current window height by N (default 1).
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200527 If used after |:vertical|: decrease width by N.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000528
529:res[ize] +N *CTRL-W_+*
530CTRL-W + Increase current window height by N (default 1).
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200531 If used after |:vertical|: increase width by N.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000532
533:res[ize] [N]
534CTRL-W CTRL-_ *CTRL-W_CTRL-_* *CTRL-W__*
535CTRL-W _ Set current window height to N (default: highest possible).
536
537z{nr}<CR> Set current window height to {nr}.
538
539 *CTRL-W_<*
540CTRL-W < Decrease current window width by N (default 1).
541
542 *CTRL-W_>*
543CTRL-W > Increase current window width by N (default 1).
544
545:vertical res[ize] [N] *:vertical-resize* *CTRL-W_bar*
546CTRL-W | Set current window width to N (default: widest possible).
547
548You can also resize a window by dragging a status line up or down with the
549mouse. Or by dragging a vertical separator line left or right. This only
550works if the version of Vim that is being used supports the mouse and the
551'mouse' option has been set to enable it.
552
553The option 'winheight' ('wh') is used to set the minimal window height of the
554current window. This option is used each time another window becomes the
555current window. If the option is '0', it is disabled. Set 'winheight' to a
556very large value, e.g., '9999', to make the current window always fill all
557available space. Set it to a reasonable value, e.g., '10', to make editing in
558the current window comfortable.
559
560The equivalent 'winwidth' ('wiw') option is used to set the minimal width of
561the current window.
562
563When the option 'equalalways' ('ea') is set, all the windows are automatically
564made the same size after splitting or closing a window. If you don't set this
565option, splitting a window will reduce the size of the current window and
566leave the other windows the same. When closing a window, the extra lines are
567given to the window above it.
568
569The 'eadirection' option limits the direction in which the 'equalalways'
570option is applied. The default "both" resizes in both directions. When the
571value is "ver" only the heights of windows are equalized. Use this when you
572have manually resized a vertically split window and want to keep this width.
573Likewise, "hor" causes only the widths of windows to be equalized.
574
575The option 'cmdheight' ('ch') is used to set the height of the command-line.
576If you are annoyed by the |hit-enter| prompt for long messages, set this
577option to 2 or 3.
578
579If there is only one window, resizing that window will also change the command
580line height. If there are several windows, resizing the current window will
581also change the height of the window below it (and sometimes the window above
582it).
583
584The minimal height and width of a window is set with 'winminheight' and
585'winminwidth'. These are hard values, a window will never become smaller.
586
587==============================================================================
5887. Argument and buffer list commands *buffer-list*
589
590 args list buffer list meaning ~
5911. :[N]argument [N] 11. :[N]buffer [N] to arg/buf N
5922. :[N]next [file ..] 12. :[N]bnext [N] to Nth next arg/buf
5933. :[N]Next [N] 13. :[N]bNext [N] to Nth previous arg/buf
5944. :[N]previous [N] 14. :[N]bprevious [N] to Nth previous arg/buf
5955. :rewind / :first 15. :brewind / :bfirst to first arg/buf
5966. :last 16. :blast to last arg/buf
5977. :all 17. :ball edit all args/buffers
598 18. :unhide edit all loaded buffers
599 19. :[N]bmod [N] to Nth modified buf
600
601 split & args list split & buffer list meaning ~
60221. :[N]sargument [N] 31. :[N]sbuffer [N] split + to arg/buf N
60322. :[N]snext [file ..] 32. :[N]sbnext [N] split + to Nth next arg/buf
60423. :[N]sNext [N] 33. :[N]sbNext [N] split + to Nth previous arg/buf
60524. :[N]sprevious [N] 34. :[N]sbprevious [N] split + to Nth previous arg/buf
60625. :srewind / :sfirst 35. :sbrewind / :sbfirst split + to first arg/buf
60726. :slast 36. :sblast split + to last arg/buf
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000060827. :sall 37. :sball edit all args/buffers
Bram Moolenaar071d4272004-06-13 20:20:40 +0000609 38. :sunhide edit all loaded buffers
610 39. :[N]sbmod [N] split + to Nth modified buf
611
61240. :args list of arguments
61341. :buffers list of buffers
614
615The meaning of [N] depends on the command:
616 [N] is number of buffers to go forward/backward on ?2, ?3, and ?4
617 [N] is an argument number, defaulting to current argument, for 1 and 21
618 [N] is a buffer number, defaulting to current buffer, for 11 and 31
619 [N] is a count for 19 and 39
620
621Note: ":next" is an exception, because it must accept a list of file names
622for compatibility with Vi.
623
624
625The argument list and multiple windows
626--------------------------------------
627
628The current position in the argument list can be different for each window.
629Remember that when doing ":e file", the position in the argument list stays
630the same, but you are not editing the file at that position. To indicate
631this, the file message (and the title, if you have one) shows
632"(file (N) of M)", where "(N)" is the current position in the file list, and
633"M" the number of files in the file list.
634
635All the entries in the argument list are added to the buffer list. Thus, you
636can also get to them with the buffer list commands, like ":bnext".
637
638:[N]al[l][!] [N] *:al* *:all* *:sal* *:sall*
639:[N]sal[l][!] [N]
640 Rearrange the screen to open one window for each argument.
641 All other windows are closed. When a count is given, this is
642 the maximum number of windows to open.
Bram Moolenaarfd2ac762006-03-01 22:09:21 +0000643 With the |:tab| modifier open a tab page for each argument.
644 When there are more arguments than 'tabpagemax' further ones
645 become split windows in the last tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000646 When the 'hidden' option is set, all buffers in closed windows
647 become hidden.
648 When 'hidden' is not set, and the 'autowrite' option is set,
649 modified buffers are written. Otherwise, windows that have
650 buffers that are modified are not removed, unless the [!] is
651 given, then they become hidden. But modified buffers are
652 never abandoned, so changes cannot get lost.
653 [N] is the maximum number of windows to open. 'winheight'
654 also limits the number of windows opened ('winwidth' if
655 |:vertical| was prepended).
656 Buf/Win Enter/Leave autocommands are not executed for the new
657 windows here, that's only done when they are really entered.
658
659:[N]sa[rgument][!] [++opt] [+cmd] [N] *:sa* *:sargument*
660 Short for ":split | argument [N]": split window and go to Nth
661 argument. But when there is no such argument, the window is
662 not split. Also see |++opt| and |+cmd|.
663
664:[N]sn[ext][!] [++opt] [+cmd] [file ..] *:sn* *:snext*
665 Short for ":split | [N]next": split window and go to Nth next
666 argument. But when there is no next file, the window is not
667 split. Also see |++opt| and |+cmd|.
668
669:[N]spr[evious][!] [++opt] [+cmd] [N] *:spr* *:sprevious*
670:[N]sN[ext][!] [++opt] [+cmd] [N] *:sN* *:sNext*
671 Short for ":split | [N]Next": split window and go to Nth
672 previous argument. But when there is no previous file, the
673 window is not split. Also see |++opt| and |+cmd|.
674
675 *:sre* *:srewind*
676:sre[wind][!] [++opt] [+cmd]
677 Short for ":split | rewind": split window and go to first
678 argument. But when there is no argument list, the window is
679 not split. Also see |++opt| and |+cmd|.
680
681 *:sfir* *:sfirst*
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000682:sfir[st] [++opt] [+cmd]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000683 Same as ":srewind".
684
685 *:sla* *:slast*
686:sla[st][!] [++opt] [+cmd]
687 Short for ":split | last": split window and go to last
688 argument. But when there is no argument list, the window is
689 not split. Also see |++opt| and |+cmd|.
690
691 *:dr* *:drop*
Bram Moolenaared39e1d2008-08-09 17:55:22 +0000692:dr[op] [++opt] [+cmd] {file} ..
Bram Moolenaar071d4272004-06-13 20:20:40 +0000693 Edit the first {file} in a window.
694 - If the file is already open in a window change to that
695 window.
696 - If the file is not open in a window edit the file in the
697 current window. If the current buffer can't be |abandon|ed,
698 the window is split first.
699 The |argument-list| is set, like with the |:next| command.
700 The purpose of this command is that it can be used from a
701 program that wants Vim to edit another file, e.g., a debugger.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000702 When using the |:tab| modifier each argument is opened in a
703 tab page. The last window is used if it's empty.
Bram Moolenaared39e1d2008-08-09 17:55:22 +0000704 Also see |++opt| and |+cmd|.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200705 {only available when compiled with a GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000706
707==============================================================================
7088. Do a command in all buffers or windows *list-repeat*
709
710 *:windo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100711:[range]windo {cmd} Execute {cmd} in each window or if [range] is given
712 only in windows for which the window number lies in
713 the [range]. It works like doing this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000714 CTRL-W t
715 :{cmd}
716 CTRL-W w
717 :{cmd}
718 etc.
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000719< This only operates in the current tab page.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000720 When an error is detected on one window, further
Bram Moolenaar071d4272004-06-13 20:20:40 +0000721 windows will not be visited.
722 The last window (or where an error occurred) becomes
723 the current window.
724 {cmd} can contain '|' to concatenate several commands.
725 {cmd} must not open or close windows or reorder them.
726 {not in Vi} {not available when compiled without the
727 |+listcmds| feature}
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200728 Also see |:tabdo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|,
729 |:cfdo| and |:lfdo|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000730
731 *:bufdo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100732:[range]bufdo[!] {cmd} Execute {cmd} in each buffer in the buffer list or if
733 [range] is given only for buffers for which their
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100734 buffer number is in the [range]. It works like doing
Bram Moolenaara162bc52015-01-07 16:54:21 +0100735 this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000736 :bfirst
737 :{cmd}
738 :bnext
739 :{cmd}
740 etc.
741< When the current file can't be |abandon|ed and the [!]
742 is not present, the command fails.
743 When an error is detected on one buffer, further
744 buffers will not be visited.
745 Unlisted buffers are skipped.
746 The last buffer (or where an error occurred) becomes
747 the current buffer.
748 {cmd} can contain '|' to concatenate several commands.
749 {cmd} must not delete buffers or add buffers to the
750 buffer list.
751 Note: While this command is executing, the Syntax
752 autocommand event is disabled by adding it to
753 'eventignore'. This considerably speeds up editing
754 each buffer.
755 {not in Vi} {not available when compiled without the
756 |+listcmds| feature}
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200757 Also see |:tabdo|, |:argdo|, |:windo|, |:cdo|, |:ldo|,
758 |:cfdo| and |:lfdo|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000759
760Examples: >
761
762 :windo set nolist nofoldcolumn | normal zn
763
764This resets the 'list' option and disables folding in all windows. >
765
766 :bufdo set fileencoding= | update
767
768This resets the 'fileencoding' in each buffer and writes it if this changed
769the buffer. The result is that all buffers will use the 'encoding' encoding
770(if conversion works properly).
771
772==============================================================================
7739. Tag or file name under the cursor *window-tag*
774
775 *:sta* *:stag*
776:sta[g][!] [tagname]
777 Does ":tag[!] [tagname]" and splits the window for the found
778 tag. See also |:tag|.
779
780CTRL-W ] *CTRL-W_]* *CTRL-W_CTRL-]*
781CTRL-W CTRL-] Split current window in two. Use identifier under cursor as a
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200782 tag and jump to it in the new upper window.
783 In Visual mode uses the Visually selected text as a tag.
784 Make new window N high.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000785
786 *CTRL-W_g]*
787CTRL-W g ] Split current window in two. Use identifier under cursor as a
788 tag and perform ":tselect" on it in the new upper window.
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200789 In Visual mode uses the Visually selected text as a tag.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000790 Make new window N high.
791
792 *CTRL-W_g_CTRL-]*
793CTRL-W g CTRL-] Split current window in two. Use identifier under cursor as a
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200794 tag and perform ":tjump" on it in the new upper window.
795 In Visual mode uses the Visually selected text as a tag.
796 Make new window N high.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000797
798CTRL-W f *CTRL-W_f* *CTRL-W_CTRL-F*
799CTRL-W CTRL-F Split current window in two. Edit file name under cursor.
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000800 Like ":split gf", but window isn't split if the file does not
Bram Moolenaar071d4272004-06-13 20:20:40 +0000801 exist.
802 Uses the 'path' variable as a list of directory names where to
803 look for the file. Also the path for current file is
804 used to search for the file name.
805 If the name is a hypertext link that looks like
806 "type://machine/path", only "/path" is used.
807 If a count is given, the count'th matching file is edited.
808 {not available when the |+file_in_path| feature was disabled
809 at compile time}
810
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000811CTRL-W F *CTRL-W_F*
812 Split current window in two. Edit file name under cursor and
813 jump to the line number following the file name. See |gF| for
814 details on how the line number is obtained.
Bram Moolenaar57657d82006-04-21 22:12:41 +0000815 {not available when the |+file_in_path| feature was disabled
816 at compile time}
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000817
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000818CTRL-W gf *CTRL-W_gf*
819 Open a new tab page and edit the file name under the cursor.
820 Like "tab split" and "gf", but the new tab page isn't created
821 if the file does not exist.
822 {not available when the |+file_in_path| feature was disabled
823 at compile time}
824
Bram Moolenaar57657d82006-04-21 22:12:41 +0000825CTRL-W gF *CTRL-W_gF*
826 Open a new tab page and edit the file name under the cursor
827 and jump to the line number following the file name. Like
828 "tab split" and "gF", but the new tab page isn't created if
829 the file does not exist.
830 {not available when the |+file_in_path| feature was disabled
831 at compile time}
832
Bram Moolenaar071d4272004-06-13 20:20:40 +0000833Also see |CTRL-W_CTRL-I|: open window for an included file that includes
834the keyword under the cursor.
835
836==============================================================================
83710. The preview window *preview-window*
838
839The preview window is a special window to show (preview) another file. It is
840normally a small window used to show an include file or definition of a
841function.
842{not available when compiled without the |+quickfix| feature}
843
Bram Moolenaarc270d802006-03-11 21:29:41 +0000844There can be only one preview window (per tab page). It is created with one
845of the commands below. The 'previewheight' option can be set to specify the
846height of the preview window when it's opened. The 'previewwindow' option is
847set in the preview window to be able to recognize it. The 'winfixheight'
848option is set to have it keep the same height when opening/closing other
849windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000850
851 *:pta* *:ptag*
852:pta[g][!] [tagname]
853 Does ":tag[!] [tagname]" and shows the found tag in a
854 "Preview" window without changing the current buffer or cursor
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000855 position. If a "Preview" window already exists, it is re-used
Bram Moolenaar071d4272004-06-13 20:20:40 +0000856 (like a help window is). If a new one is opened,
857 'previewheight' is used for the height of the window. See
858 also |:tag|.
859 See below for an example. |CursorHold-example|
860 Small difference from |:tag|: When [tagname] is equal to the
861 already displayed tag, the position in the matching tag list
862 is not reset. This makes the CursorHold example work after a
863 |:ptnext|.
864
865CTRL-W z *CTRL-W_z*
866CTRL-W CTRL-Z *CTRL-W_CTRL-Z* *:pc* *:pclose*
867:pc[lose][!] Close any "Preview" window currently open. When the 'hidden'
868 option is set, or when the buffer was changed and the [!] is
869 used, the buffer becomes hidden (unless there is another
870 window editing it). The command fails if any "Preview" buffer
871 cannot be closed. See also |:close|.
872
873 *:pp* *:ppop*
874:[count]pp[op][!]
875 Does ":[count]pop[!]" in the preview window. See |:pop| and
876 |:ptag|. {not in Vi}
877
878CTRL-W } *CTRL-W_}*
879 Use identifier under cursor as a tag and perform a :ptag on
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000880 it. Make the new Preview window (if required) N high. If N is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000881 not given, 'previewheight' is used.
882
883CTRL-W g } *CTRL-W_g}*
884 Use identifier under cursor as a tag and perform a :ptjump on
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000885 it. Make the new Preview window (if required) N high. If N is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000886 not given, 'previewheight' is used.
887
888 *:ped* *:pedit*
889:ped[it][!] [++opt] [+cmd] {file}
890 Edit {file} in the preview window. The preview window is
891 opened like with |:ptag|. The current window and cursor
892 position isn't changed. Useful example: >
893 :pedit +/fputc /usr/include/stdio.h
894<
895 *:ps* *:psearch*
896:[range]ps[earch][!] [count] [/]pattern[/]
897 Works like |:ijump| but shows the found match in the preview
898 window. The preview window is opened like with |:ptag|. The
899 current window and cursor position isn't changed. Useful
900 example: >
901 :psearch popen
902< Like with the |:ptag| command, you can use this to
903 automatically show information about the word under the
904 cursor. This is less clever than using |:ptag|, but you don't
905 need a tags file and it will also find matches in system
906 include files. Example: >
907 :au! CursorHold *.[ch] nested exe "silent! psearch " . expand("<cword>")
908< Warning: This can be slow.
909
910Example *CursorHold-example* >
911
912 :au! CursorHold *.[ch] nested exe "silent! ptag " . expand("<cword>")
913
914This will cause a ":ptag" to be executed for the keyword under the cursor,
915when the cursor hasn't moved for the time set with 'updatetime'. The "nested"
916makes other autocommands be executed, so that syntax highlighting works in the
917preview window. The "silent!" avoids an error message when the tag could not
918be found. Also see |CursorHold|. To disable this again: >
919
920 :au! CursorHold
921
922A nice addition is to highlight the found tag, avoid the ":ptag" when there
923is no word under the cursor, and a few other things: >
924
925 :au! CursorHold *.[ch] nested call PreviewWord()
926 :func PreviewWord()
927 : if &previewwindow " don't do this in the preview window
928 : return
929 : endif
930 : let w = expand("<cword>") " get the word under cursor
931 : if w =~ '\a' " if the word contains a letter
932 :
933 : " Delete any existing highlight before showing another tag
934 : silent! wincmd P " jump to preview window
935 : if &previewwindow " if we really get there...
936 : match none " delete existing highlight
937 : wincmd p " back to old window
938 : endif
939 :
940 : " Try displaying a matching tag for the word under the cursor
941 : try
942 : exe "ptag " . w
943 : catch
944 : return
945 : endtry
946 :
947 : silent! wincmd P " jump to preview window
948 : if &previewwindow " if we really get there...
949 : if has("folding")
950 : silent! .foldopen " don't want a closed fold
951 : endif
952 : call search("$", "b") " to end of previous line
953 : let w = substitute(w, '\\', '\\\\', "")
954 : call search('\<\V' . w . '\>') " position cursor on match
955 : " Add a match highlight to the word at this position
956 : hi previewWord term=bold ctermbg=green guibg=green
957 : exe 'match previewWord "\%' . line(".") . 'l\%' . col(".") . 'c\k*"'
958 : wincmd p " back to old window
959 : endif
960 : endif
961 :endfun
962
963==============================================================================
96411. Using hidden buffers *buffer-hidden*
965
966A hidden buffer is not displayed in a window, but is still loaded into memory.
967This makes it possible to jump from file to file, without the need to read or
968write the file every time you get another buffer in a window.
969{not available when compiled without the |+listcmds| feature}
970
971 *:buffer-!*
972If the option 'hidden' ('hid') is set, abandoned buffers are kept for all
973commands that start editing another file: ":edit", ":next", ":tag", etc. The
974commands that move through the buffer list sometimes make the current buffer
975hidden although the 'hidden' option is not set. This happens when a buffer is
976modified, but is forced (with '!') to be removed from a window, and
977'autowrite' is off or the buffer can't be written.
978
979You can make a hidden buffer not hidden by starting to edit it with any
980command. Or by deleting it with the ":bdelete" command.
981
982The 'hidden' is global, it is used for all buffers. The 'bufhidden' option
983can be used to make an exception for a specific buffer. It can take these
984values:
985 <empty> Use the value of 'hidden'.
986 hide Hide this buffer, also when 'hidden' is not set.
987 unload Don't hide but unload this buffer, also when 'hidden'
988 is set.
989 delete Delete the buffer.
990
991 *hidden-quit*
992When you try to quit Vim while there is a hidden, modified buffer, you will
993get an error message and Vim will make that buffer the current buffer. You
994can then decide to write this buffer (":wq") or quit without writing (":q!").
995Be careful: there may be more hidden, modified buffers!
996
997A buffer can also be unlisted. This means it exists, but it is not in the
998list of buffers. |unlisted-buffer|
999
1000
Bram Moolenaard51cb702015-07-21 15:03:06 +02001001:files[!] [flags] *:files*
1002:buffers[!] [flags] *:buffers* *:ls*
1003:ls[!] [flags]
1004 Show all buffers. Example:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001005
Bram Moolenaar97d62492012-11-15 21:28:22 +01001006 1 #h "/test/text" line 1 ~
1007 2u "asdf" line 0 ~
1008 3 %a + "version.c" line 1 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00001009
1010 When the [!] is included the list will show unlisted buffers
1011 (the term "unlisted" is a bit confusing then...).
1012
1013 Each buffer has a unique number. That number will not change,
Bram Moolenaar0122c402015-02-03 19:13:34 +01001014 thus you can always go to a specific buffer with ":buffer N"
1015 or "N CTRL-^", where N is the buffer number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001016
1017 Indicators (chars in the same column are mutually exclusive):
1018 u an unlisted buffer (only displayed when [!] is used)
1019 |unlisted-buffer|
1020 % the buffer in the current window
1021 # the alternate buffer for ":e #" and CTRL-^
1022 a an active buffer: it is loaded and visible
1023 h a hidden buffer: It is loaded, but currently not
1024 displayed in a window |hidden-buffer|
1025 - a buffer with 'modifiable' off
1026 = a readonly buffer
1027 + a modified buffer
1028 x a buffer with read errors
1029
Bram Moolenaard51cb702015-07-21 15:03:06 +02001030 [flags] can be a combination of the following characters,
1031 which restrict the buffers to be listed:
1032 + modified buffers
1033 - buffers with 'modifiable' off
1034 = readonly buffers
1035 a active buffers
Bram Moolenaare392eb42015-11-19 20:38:09 +01001036 u unlisted buffers (overrides the "!")
Bram Moolenaard51cb702015-07-21 15:03:06 +02001037 h hidden buffers
1038 x buffers with a read error
1039 % current buffer
1040 # alternate buffer
1041 Combining flags means they are "and"ed together, e.g.:
1042 h+ hidden buffers which are modified
1043 a+ active buffers which are modified
1044
Bram Moolenaar071d4272004-06-13 20:20:40 +00001045 *:bad* *:badd*
1046:bad[d] [+lnum] {fname}
1047 Add file name {fname} to the buffer list, without loading it.
1048 If "lnum" is specified, the cursor will be positioned at that
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001049 line when the buffer is first entered. Note that other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001050 commands after the + will be ignored.
1051
1052:[N]bd[elete][!] *:bd* *:bdel* *:bdelete* *E516*
1053:bd[elete][!] [N]
1054 Unload buffer [N] (default: current buffer) and delete it from
1055 the buffer list. If the buffer was changed, this fails,
1056 unless when [!] is specified, in which case changes are lost.
1057 The file remains unaffected. Any windows for this buffer are
1058 closed. If buffer [N] is the current buffer, another buffer
1059 will be displayed instead. This is the most recent entry in
1060 the jump list that points into a loaded buffer.
1061 Actually, the buffer isn't completely deleted, it is removed
1062 from the buffer list |unlisted-buffer| and option values,
1063 variables and mappings/abbreviations for the buffer are
Bram Moolenaar4d84d932014-11-30 14:50:16 +01001064 cleared. Examples: >
1065 :.,$-bdelete " delete buffers from the current one to
1066 " last but one
1067 :%bdelete " delete all buffers
1068<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001069
1070:bdelete[!] {bufname} *E93* *E94*
1071 Like ":bdelete[!] [N]", but buffer given by name. Note that a
1072 buffer whose name is a number cannot be referenced by that
1073 name; use the buffer number instead. Insert a backslash
1074 before a space in a buffer name.
1075
1076:bdelete[!] N1 N2 ...
1077 Do ":bdelete[!]" for buffer N1, N2, etc. The arguments can be
1078 buffer numbers or buffer names (but not buffer names that are
1079 a number). Insert a backslash before a space in a buffer
1080 name.
1081
1082:N,Mbdelete[!] Do ":bdelete[!]" for all buffers in the range N to M
1083 |inclusive|.
1084
1085:[N]bw[ipeout][!] *:bw* *:bwipe* *:bwipeout* *E517*
1086:bw[ipeout][!] {bufname}
1087:N,Mbw[ipeout][!]
1088:bw[ipeout][!] N1 N2 ...
Bram Moolenaardf1bdc92006-02-23 21:32:16 +00001089 Like |:bdelete|, but really delete the buffer. Everything
1090 related to the buffer is lost. All marks in this buffer
1091 become invalid, option settings are lost, etc. Don't use this
Bram Moolenaar4d84d932014-11-30 14:50:16 +01001092 unless you know what you are doing. Examples: >
1093 :.+,$bwipeout " wipe out all buffers after the current
1094 " one
1095 :%bwipeout " wipe out all buffers
1096<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001097
1098:[N]bun[load][!] *:bun* *:bunload* *E515*
1099:bun[load][!] [N]
1100 Unload buffer [N] (default: current buffer). The memory
1101 allocated for this buffer will be freed. The buffer remains
1102 in the buffer list.
1103 If the buffer was changed, this fails, unless when [!] is
1104 specified, in which case the changes are lost.
1105 Any windows for this buffer are closed. If buffer [N] is the
1106 current buffer, another buffer will be displayed instead.
1107 This is the most recent entry in the jump list that points
1108 into a loaded buffer.
1109
1110:bunload[!] {bufname}
1111 Like ":bunload[!] [N]", but buffer given by name. Note that a
1112 buffer whose name is a number cannot be referenced by that
1113 name; use the buffer number instead. Insert a backslash
1114 before a space in a buffer name.
1115
1116:N,Mbunload[!] Do ":bunload[!]" for all buffers in the range N to M
1117 |inclusive|.
1118
1119:bunload[!] N1 N2 ...
1120 Do ":bunload[!]" for buffer N1, N2, etc. The arguments can be
1121 buffer numbers or buffer names (but not buffer names that are
1122 a number). Insert a backslash before a space in a buffer
1123 name.
1124
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001125:[N]b[uffer][!] [+cmd] [N] *:b* *:bu* *:buf* *:buffer* *E86*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001126 Edit buffer [N] from the buffer list. If [N] is not given,
1127 the current buffer remains being edited. See |:buffer-!| for
1128 [!]. This will also edit a buffer that is not in the buffer
1129 list, without setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001130 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001131
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001132:[N]b[uffer][!] [+cmd] {bufname}
Bram Moolenaarc1a11ed2008-06-24 22:09:24 +00001133 Edit buffer for {bufname} from the buffer list. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001134 |:buffer-!| for [!]. This will also edit a buffer that is not
1135 in the buffer list, without setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001136 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001137
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001138:[N]sb[uffer] [+cmd] [N] *:sb* *:sbuffer*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001139 Split window and edit buffer [N] from the buffer list. If [N]
1140 is not given, the current buffer is edited. Respects the
1141 "useopen" setting of 'switchbuf' when splitting. This will
1142 also edit a buffer that is not in the buffer list, without
1143 setting the 'buflisted' flag.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001144 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001145
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001146:[N]sb[uffer] [+cmd] {bufname}
Bram Moolenaarc1a11ed2008-06-24 22:09:24 +00001147 Split window and edit buffer for {bufname} from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001148 list. This will also edit a buffer that is not in the buffer
1149 list, without setting the 'buflisted' flag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001150 Note: If what you want to do is split the buffer, make a copy
1151 under another name, you can do it this way: >
1152 :w foobar | sp #
Bram Moolenaar12969c02015-09-08 23:36:10 +02001153< Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001154
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001155:[N]bn[ext][!] [+cmd] [N] *:bn* *:bnext* *E87*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001156 Go to [N]th next buffer in buffer list. [N] defaults to one.
1157 Wraps around the end of the buffer list.
1158 See |:buffer-!| for [!].
Bram Moolenaar12969c02015-09-08 23:36:10 +02001159 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001160 If you are in a help buffer, this takes you to the next help
1161 buffer (if there is one). Similarly, if you are in a normal
1162 (non-help) buffer, this takes you to the next normal buffer.
1163 This is so that if you have invoked help, it doesn't get in
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001164 the way when you're browsing code/text buffers. The next three
Bram Moolenaar071d4272004-06-13 20:20:40 +00001165 commands also work like this.
1166
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001167
Bram Moolenaar071d4272004-06-13 20:20:40 +00001168 *:sbn* *:sbnext*
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001169:[N]sbn[ext] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001170 Split window and go to [N]th next buffer in buffer list.
1171 Wraps around the end of the buffer list. Uses 'switchbuf'
Bram Moolenaar12969c02015-09-08 23:36:10 +02001172 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001173
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001174:[N]bN[ext][!] [+cmd] [N] *:bN* *:bNext* *:bp* *:bprevious* *E88*
1175:[N]bp[revious][!] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001176 Go to [N]th previous buffer in buffer list. [N] defaults to
1177 one. Wraps around the start of the buffer list.
1178 See |:buffer-!| for [!] and 'switchbuf'.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001179 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001180
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001181:[N]sbN[ext] [+cmd] [N] *:sbN* *:sbNext* *:sbp* *:sbprevious*
1182:[N]sbp[revious] [+cmd] [N]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001183 Split window and go to [N]th previous buffer in buffer list.
1184 Wraps around the start of the buffer list.
1185 Uses 'switchbuf'.
Bram Moolenaar12969c02015-09-08 23:36:10 +02001186 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001187
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001188:br[ewind][!] [+cmd] *:br* *:brewind*
1189 Go to first buffer in buffer list. If the buffer list is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001190 empty, go to the first unlisted buffer.
1191 See |:buffer-!| for [!].
1192
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001193:bf[irst] [+cmd] *:bf* *:bfirst*
1194 Same as |:brewind|.
1195 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001196
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001197:sbr[ewind] [+cmd] *:sbr* *:sbrewind*
1198 Split window and go to first buffer in buffer list. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001199 buffer list is empty, go to the first unlisted buffer.
1200 Respects the 'switchbuf' option.
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001201 Also see |+cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001202
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001203:sbf[irst] [+cmd] *:sbf* *:sbfirst*
1204 Same as ":sbrewind".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001205
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001206:bl[ast][!] [+cmd] *:bl* *:blast*
1207 Go to last buffer in buffer list. If the buffer list is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001208 empty, go to the last unlisted buffer.
1209 See |:buffer-!| for [!].
1210
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001211:sbl[ast] [+cmd] *:sbl* *:sblast*
1212 Split window and go to last buffer in buffer list. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001213 buffer list is empty, go to the last unlisted buffer.
1214 Respects 'switchbuf' option.
1215
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001216:[N]bm[odified][!] [+cmd] [N] *:bm* *:bmodified* *E84*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001217 Go to [N]th next modified buffer. Note: this command also
1218 finds unlisted buffers. If there is no modified buffer the
1219 command fails.
1220
Bram Moolenaar9c8d9e12014-09-19 20:07:26 +02001221:[N]sbm[odified] [+cmd] [N] *:sbm* *:sbmodified*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001222 Split window and go to [N]th next modified buffer.
1223 Respects 'switchbuf' option.
1224 Note: this command also finds buffers not in the buffer list.
1225
1226:[N]unh[ide] [N] *:unh* *:unhide* *:sun* *:sunhide*
1227:[N]sun[hide] [N]
1228 Rearrange the screen to open one window for each loaded buffer
1229 in the buffer list. When a count is given, this is the
1230 maximum number of windows to open.
1231
1232:[N]ba[ll] [N] *:ba* *:ball* *:sba* *:sball*
1233:[N]sba[ll] [N] Rearrange the screen to open one window for each buffer in
1234 the buffer list. When a count is given, this is the maximum
1235 number of windows to open. 'winheight' also limits the number
1236 of windows opened ('winwidth' if |:vertical| was prepended).
1237 Buf/Win Enter/Leave autocommands are not executed for the new
1238 windows here, that's only done when they are really entered.
Bram Moolenaar756ec0f2007-05-05 17:59:48 +00001239 When the |:tab| modifier is used new windows are opened in a
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00001240 new tab, up to 'tabpagemax'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001241
1242Note: All the commands above that start editing another buffer, keep the
1243'readonly' flag as it was. This differs from the ":edit" command, which sets
1244the 'readonly' flag each time the file is read.
1245
1246==============================================================================
124712. Special kinds of buffers *special-buffers*
1248
1249Instead of containing the text of a file, buffers can also be used for other
1250purposes. A few options can be set to change the behavior of a buffer:
1251 'bufhidden' what happens when the buffer is no longer displayed
1252 in a window.
1253 'buftype' what kind of a buffer this is
1254 'swapfile' whether the buffer will have a swap file
1255 'buflisted' buffer shows up in the buffer list
1256
1257A few useful kinds of a buffer:
1258
Bram Moolenaar280f1262006-01-30 00:14:18 +00001259quickfix Used to contain the error list or the location list. See
1260 |:cwindow| and |:lwindow|. This command sets the 'buftype'
1261 option to "quickfix". You are not supposed to change this!
1262 'swapfile' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001263
1264help Contains a help file. Will only be created with the |:help|
1265 command. The flag that indicates a help buffer is internal
1266 and can't be changed. The 'buflisted' option will be reset
1267 for a help buffer.
1268
Bram Moolenaar677ee682005-01-27 14:41:15 +00001269directory Displays directory contents. Can be used by a file explorer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001270 plugin. The buffer is created with these settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001271 :setlocal buftype=nowrite
1272 :setlocal bufhidden=delete
1273 :setlocal noswapfile
Bram Moolenaar071d4272004-06-13 20:20:40 +00001274< The buffer name is the name of the directory and is adjusted
1275 when using the |:cd| command.
1276
1277scratch Contains text that can be discarded at any time. It is kept
1278 when closing the window, it must be deleted explicitly.
1279 Settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001280 :setlocal buftype=nofile
1281 :setlocal bufhidden=hide
1282 :setlocal noswapfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001283< The buffer name can be used to identify the buffer, if you
1284 give it a meaningful name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001285
1286 *unlisted-buffer*
1287unlisted The buffer is not in the buffer list. It is not used for
1288 normal editing, but to show a help file, remember a file name
1289 or marks. The ":bdelete" command will also set this option,
1290 thus it doesn't completely delete the buffer. Settings: >
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00001291 :setlocal nobuflisted
Bram Moolenaar071d4272004-06-13 20:20:40 +00001292<
1293
1294 vim:tw=78:ts=8:ft=help:norl: