| blob | ccb980114e7e1414c9c833c336bcec51ccc617b2 |
1 *windows.txt* For Vim version 7.3. Last change: 2010 Aug 15
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Editing with multiple windows and buffers. *windows* *buffers*
9 The commands which have been added to use multiple windows and buffers are
10 explained here. Additionally, there are explanations for commands that work
11 differently when used in combination with more than one window.
13 The basics are explained in chapter 7 and 8 of the user manual |usr_07.txt|
14 |usr_08.txt|.
16 1. Introduction |windows-intro|
17 2. Starting Vim |windows-starting|
18 3. Opening and closing a window |opening-window|
19 4. Moving cursor to other windows |window-move-cursor|
20 5. Moving windows around |window-moving|
21 6. Window resizing |window-resize|
22 7. Argument and buffer list commands |buffer-list|
23 8. Do a command in all buffers or windows |list-repeat|
24 9. Tag or file name under the cursor |window-tag|
25 10. The preview window |preview-window|
26 11. Using hidden buffers |buffer-hidden|
27 12. Special kinds of buffers |special-buffers|
29 {Vi does not have any of these commands}
30 {not able to use multiple windows when the |+windows| feature was disabled at
31 compile time}
32 {not able to use vertically split windows when the |+vertsplit| feature was
33 disabled at compile time}
35 ==============================================================================
36 1. Introduction *windows-intro* *window*
38 Summary:
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.
43 A window is a viewport onto a buffer. You can use multiple windows on one
44 buffer, or several windows on different buffers.
46 A buffer is a file loaded into memory for editing. The original file remains
47 unchanged until you write the buffer to the file.
49 A buffer can be in one of three states:
51 *active-buffer*
52 active: 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*
56 hidden: 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*
60 inactive: 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.
65 In a table:
67 state displayed loaded ":buffers" ~
68 in window shows ~
69 active yes yes 'a'
70 hidden no yes 'h'
71 inactive no no ' '
73 Note: All CTRL-W commands can also be executed with |:wincmd|, for those
74 places where a Normal mode command can't be used or is inconvenient.
76 The main Vim window can hold several split windows. There are also tab pages
77 |tab-page|, each of which can hold multiple windows.
79 ==============================================================================
80 2. Starting Vim *windows-starting*
82 By default, Vim starts with one window, just like Vi.
84 The "-o" and "-O" arguments to Vim can be used to open a window for each file
85 in the argument list. The "-o" argument will split the windows horizontally;
86 the "-O" argument will split the windows vertically. If both "-o" and "-O"
87 are given, the last one encountered will be used to determine the split
88 orientation. For example, this will open three windows, split horizontally: >
89 vim -o file1 file2 file3
91 "-oN", where N is a decimal number, opens N windows split horizontally. If
92 there are more file names than windows, only N windows are opened and some
93 files do not get a window. If there are more windows than file names, the
94 last few windows will be editing empty buffers. Similarly, "-ON" opens N
95 windows split vertically, with the same restrictions.
97 If there are many file names, the windows will become very small. You might
98 want to set the 'winheight' and/or 'winwidth' options to create a workable
99 situation.
101 Buf/Win Enter/Leave |autocommand|s are not executed when opening the new
102 windows and reading the files, that's only done when they are really entered.
104 *status-line*
105 A status line will be used to separate windows. The 'laststatus' option tells
106 when the last window also has a status line:
107 'laststatus' = 0 never a status line
108 'laststatus' = 1 status line if there is more than one window
109 'laststatus' = 2 always a status line
111 You can change the contents of the status line with the 'statusline' option.
112 This option can be local to the window, so that you can have a different
113 status line in each window.
115 Normally, inversion is used to display the status line. This can be changed
116 with the 's' character in the 'highlight' option. For example, "sb" sets it to
117 bold characters. If no highlighting is used for the status line ("sn"), the
118 '^' character is used for the current window, and '=' for other windows. If
119 the mouse is supported and enabled with the 'mouse' option, a status line can
120 be dragged to resize windows.
122 Note: If you expect your status line to be in reverse video and it isn't,
123 check if the 'highlight' option contains "si". In version 3.0, this meant to
124 invert the status line. Now it should be "sr", reverse the status line, as
125 "si" now stands for italic! If italic is not available on your terminal, the
126 status line is inverted anyway; you will only see this problem on terminals
127 that have termcap codes for italics.
129 ==============================================================================
130 3. Opening and closing a window *opening-window* *E36*
132 CTRL-W s *CTRL-W_s*
133 CTRL-W S *CTRL-W_S*
134 CTRL-W CTRL-S *CTRL-W_CTRL-S*
135 :[N]sp[lit] [++opt] [+cmd] *:sp* *:split*
136 Split current window in two. The result is two viewports on
137 the same file. Make new window N high (default is to use half
138 the height of the current window). Reduces the current window
139 height to create room (and others, if the 'equalalways' option
140 is set, 'eadirection' isn't "hor", and one of them is higher
141 than the current or the new window).
142 Note: CTRL-S does not work on all terminals and might block
143 further input, use CTRL-Q to get going again.
144 Also see |++opt| and |+cmd|.
146 CTRL-W CTRL-V *CTRL-W_CTRL-V*
147 CTRL-W v *CTRL-W_v*
148 :[N]vs[plit] [++opt] [+cmd] [file] *:vs* *:vsplit*
149 Like |:split|, but split vertically. The windows will be
150 spread out horizontally if
151 1. a width was not specified,
152 2. 'equalalways' is set,
153 3. 'eadirection' isn't "ver", and
154 4. one of the other windows is wider than the current or new
155 window.
156 Note: In other places CTRL-Q does the same as CTRL-V, but here
157 it doesn't!
159 CTRL-W n *CTRL-W_n*
160 CTRL-W CTRL_N *CTRL-W_CTRL-N*
161 :[N]new [++opt] [+cmd] *:new*
162 Create a new window and start editing an empty file in it.
163 Make new window N high (default is to use half the existing
164 height). Reduces the current window height to create room (and
165 others, if the 'equalalways' option is set and 'eadirection'
166 isn't "hor").
167 Also see |++opt| and |+cmd|.
168 If 'fileformats' is not empty, the first format given will be
169 used for the new buffer. If 'fileformats' is empty, the
170 'fileformat' of the current buffer is used. This can be
171 overridden with the |++opt| argument.
172 Autocommands are executed in this order:
173 1. WinLeave for the current window
174 2. WinEnter for the new window
175 3. BufLeave for the current buffer
176 4. BufEnter for the new buffer
177 This behaves like a ":split" first, and then a ":e" command.
179 :[N]vne[w] [++opt] [+cmd] [file] *:vne* *:vnew*
180 Like |:new|, but split vertically. If 'equalalways' is set
181 and 'eadirection' isn't "ver" the windows will be spread out
182 horizontally, unless a width was specified.
184 :[N]new [++opt] [+cmd] {file}
185 :[N]sp[lit] [++opt] [+cmd] {file} *:split_f*
186 Create a new window and start editing file {file} in it.
187 If [+cmd] is given, execute the command when the file has been
188 loaded |+cmd|.
189 Also see |++opt|.
190 Make new window N high (default is to use half the existing
191 height). Reduces the current window height to create room
192 (and others, if the 'equalalways' option is set).
194 :[N]sv[iew] [++opt] [+cmd] {file} *:sv* *:sview* *splitview*
195 Same as ":split", but set 'readonly' option for this buffer.
197 :[N]sf[ind] [++opt] [+cmd] {file} *:sf* *:sfind* *splitfind*
198 Same as ":split", but search for {file} in 'path' like in
199 |:find|. Doesn't split if {file} is not found.
201 CTRL-W CTRL-^ *CTRL-W_CTRL-^* *CTRL-W_^*
202 CTRL-W ^ Does ":split #", split window in two and edit alternate file.
203 When a count is given, it becomes ":split #N", split window
204 and edit buffer N.
206 Note that the 'splitbelow' and 'splitright' options influence where a new
207 window will appear.
209 *:vert* *:vertical*
210 :vert[ical] {cmd}
211 Execute {cmd}. If it contains a command that splits a window,
212 it will be split vertically.
213 Doesn't work for |:execute| and |:normal|.
215 :lefta[bove] {cmd} *:lefta* *:leftabove*
216 :abo[veleft] {cmd} *:abo* *:aboveleft*
217 Execute {cmd}. If it contains a command that splits a window,
218 it will be opened left (vertical split) or above (horizontal
219 split) the current window. Overrules 'splitbelow' and
220 'splitright'.
221 Doesn't work for |:execute| and |:normal|.
223 :rightb[elow] {cmd} *:rightb* *:rightbelow*
224 :bel[owright] {cmd} *:bel* *:belowright*
225 Execute {cmd}. If it contains a command that splits a window,
226 it will be opened right (vertical split) or below (horizontal
227 split) the current window. Overrules 'splitbelow' and
228 'splitright'.
229 Doesn't work for |:execute| and |:normal|.
231 *:topleft* *E442*
232 :to[pleft] {cmd}
233 Execute {cmd}. If it contains a command that splits a window,
234 it will appear at the top and occupy the full width of the Vim
235 window. When the split is vertical the window appears at the
236 far left and occupies the full height of the Vim window.
237 Doesn't work for |:execute| and |:normal|.
239 *:botright*
240 :bo[tright] {cmd}
241 Execute {cmd}. If it contains a command that splits a window,
242 it will appear at the bottom and occupy the full width of the
243 Vim window. When the split is vertical the window appears at
244 the far right and occupies the full height of the Vim window.
245 Doesn't work for |:execute| and |:normal|.
247 These command modifiers can be combined to make a vertically split window
248 occupy the full height. Example: >
249 :vertical topleft edit tags
250 Opens a vertically split, full-height window on the "tags" file at the far
251 left of the Vim window.
254 Closing a window
255 ----------------
257 CTRL-W q *CTRL-W_q*
258 CTRL-W CTRL-Q *CTRL-W_CTRL-Q*
259 :q[uit] Quit current window. When quitting the last window (not
260 counting a help window), exit Vim.
261 When 'hidden' is set, and there is only one window for the
262 current buffer, it becomes hidden.
263 When 'hidden' is not set, and there is only one window for the
264 current buffer, and the buffer was changed, the command fails.
265 (Note: CTRL-Q does not work on all terminals)
267 :q[uit]! Quit current window. If this was the last window for a buffer,
268 any changes to that buffer are lost. When quitting the last
269 window (not counting help windows), exit Vim. The contents of
270 the buffer are lost, even when 'hidden' is set.
272 CTRL-W c *CTRL-W_c* *:clo* *:close*
273 :clo[se][!] Close current window. When the 'hidden' option is set, or
274 when the buffer was changed and the [!] is used, the buffer
275 becomes hidden (unless there is another window editing it).
276 When there is only one window in the current tab page and
277 there is another tab page, this closes the current tab page.
278 |tab-page|.
279 This command fails when: *E444*
280 - There is only one window on the screen.
281 - When 'hidden' is not set, [!] is not used, the buffer has
282 changes, and there is no other window on this buffer.
283 Changes to the buffer are not written and won't get lost, so
284 this is a "safe" command.
286 CTRL-W CTRL-C *CTRL-W_CTRL-C*
287 You might have expected that CTRL-W CTRL-C closes the current
288 window, but that does not work, because the CTRL-C cancels the
289 command.
291 *:hide*
292 :hid[e] Quit current window, unless it is the last window on the
293 screen. The buffer becomes hidden (unless there is another
294 window editing it or 'bufhidden' is "unload" or "delete").
295 If the window is the last one in the current tab page the tab
296 page is closed. |tab-page|
297 The value of 'hidden' is irrelevant for this command.
298 Changes to the buffer are not written and won't get lost, so
299 this is a "safe" command.
301 :hid[e] {cmd} Execute {cmd} with 'hidden' is set. The previous value of
302 'hidden' is restored after {cmd} has been executed.
303 Example: >
304 :hide edit Makefile
305 < This will edit "Makefile", and hide the current buffer if it
306 has any changes.
308 CTRL-W o *CTRL-W_o* *E445*
309 CTRL-W CTRL-O *CTRL-W_CTRL-O* *:on* *:only*
310 :on[ly][!] Make the current window the only one on the screen. All other
311 windows are closed.
312 When the 'hidden' option is set, all buffers in closed windows
313 become hidden.
314 When 'hidden' is not set, and the 'autowrite' option is set,
315 modified buffers are written. Otherwise, windows that have
316 buffers that are modified are not removed, unless the [!] is
317 given, then they become hidden. But modified buffers are
318 never abandoned, so changes cannot get lost.
320 ==============================================================================
321 4. Moving cursor to other windows *window-move-cursor*
323 CTRL-W <Down> *CTRL-W_<Down>*
324 CTRL-W CTRL-J *CTRL-W_CTRL-J* *CTRL-W_j*
325 CTRL-W j Move cursor to Nth window below current one. Uses the cursor
326 position to select between alternatives.
328 CTRL-W <Up> *CTRL-W_<Up>*
329 CTRL-W CTRL-K *CTRL-W_CTRL-K* *CTRL-W_k*
330 CTRL-W k Move cursor to Nth window above current one. Uses the cursor
331 position to select between alternatives.
333 CTRL-W <Left> *CTRL-W_<Left>*
334 CTRL-W CTRL-H *CTRL-W_CTRL-H*
335 CTRL-W <BS> *CTRL-W_<BS>* *CTRL-W_h*
336 CTRL-W h Move cursor to Nth window left of current one. Uses the
337 cursor position to select between alternatives.
339 CTRL-W <Right> *CTRL-W_<Right>*
340 CTRL-W CTRL-L *CTRL-W_CTRL-L* *CTRL-W_l*
341 CTRL-W l Move cursor to Nth window right of current one. Uses the
342 cursor position to select between alternatives.
344 CTRL-W w *CTRL-W_w* *CTRL-W_CTRL-W*
345 CTRL-W CTRL-W Without count: move cursor to window below/right of the
346 current one. If there is no window below or right, go to
347 top-left window.
348 With count: go to Nth window (windows are numbered from
349 top-left to bottom-right). To obtain the window number see
350 |bufwinnr()| and |winnr()|. When N is larger than the number
351 of windows go to the last window.
353 *CTRL-W_W*
354 CTRL-W W Without count: move cursor to window above/left of current
355 one. If there is no window above or left, go to bottom-right
356 window. With count: go to Nth window, like with CTRL-W w.
358 CTRL-W t *CTRL-W_t* *CTRL-W_CTRL-T*
359 CTRL-W CTRL-T Move cursor to top-left window.
361 CTRL-W b *CTRL-W_b* *CTRL-W_CTRL-B*
362 CTRL-W CTRL-B Move cursor to bottom-right window.
364 CTRL-W p *CTRL-W_p* *CTRL-W_CTRL-P*
365 CTRL-W CTRL-P Go to previous (last accessed) window.
367 *CTRL-W_P* *E441*
368 CTRL-W P Go to preview window. When there is no preview window this is
369 an error.
370 {not available when compiled without the |+quickfix| feature}
372 If Visual mode is active and the new window is not for the same buffer, the
373 Visual mode is ended. If the window is on the same buffer, the cursor
374 position is set to keep the same Visual area selected.
376 *:winc* *:wincmd*
377 These commands can also be executed with ":wincmd":
379 :[count]winc[md] {arg}
380 Like executing CTRL-W [count] {arg}. Example: >
381 :wincmd j
382 < Moves to the window below the current one.
383 This command is useful when a Normal mode cannot be used (for
384 the |CursorHold| autocommand event). Or when a Normal mode
385 command is inconvenient.
386 The count can also be a window number. Example: >
387 :exe nr . "wincmd w"
388 < This goes to window "nr".
390 ==============================================================================
391 5. Moving windows around *window-moving*
393 CTRL-W r *CTRL-W_r* *CTRL-W_CTRL-R* *E443*
394 CTRL-W CTRL-R Rotate windows downwards/rightwards. The first window becomes
395 the second one, the second one becomes the third one, etc.
396 The last window becomes the first window. The cursor remains
397 in the same window.
398 This only works within the row or column of windows that the
399 current window is in.
401 *CTRL-W_R*
402 CTRL-W R Rotate windows upwards/leftwards. The second window becomes
403 the first one, the third one becomes the second one, etc. The
404 first window becomes the last window. The cursor remains in
405 the same window.
406 This only works within the row or column of windows that the
407 current window is in.
409 CTRL-W x *CTRL-W_x* *CTRL-W_CTRL-X*
410 CTRL-W CTRL-X Without count: Exchange current window with next one. If there
411 is no next window, exchange with previous window.
412 With count: Exchange current window with Nth window (first
413 window is 1). The cursor is put in the other window.
414 When vertical and horizontal window splits are mixed, the
415 exchange is only done in the row or column of windows that the
416 current window is in.
418 The following commands can be used to change the window layout. For example,
419 when there are two vertically split windows, CTRL-W K will change that in
420 horizontally split windows. CTRL-W H does it the other way around.
422 *CTRL-W_K*
423 CTRL-W K Move the current window to be at the very top, using the full
424 width of the screen. This works like closing the current
425 window and then creating another one with ":topleft split",
426 except that the current window contents is used for the new
427 window.
429 *CTRL-W_J*
430 CTRL-W J Move the current window to be at the very bottom, using the
431 full width of the screen. This works like closing the current
432 window and then creating another one with ":botright split",
433 except that the current window contents is used for the new
434 window.
436 *CTRL-W_H*
437 CTRL-W H Move the current window to be at the far left, using the
438 full height of the screen. This works like closing the
439 current window and then creating another one with
440 ":vert topleft split", except that the current window contents
441 is used for the new window.
442 {not available when compiled without the |+vertsplit| feature}
444 *CTRL-W_L*
445 CTRL-W L Move the current window to be at the far right, using the full
446 height of the screen. This works like closing the
447 current window and then creating another one with
448 ":vert botright split", except that the current window
449 contents is used for the new window.
450 {not available when compiled without the |+vertsplit| feature}
452 *CTRL-W_T*
453 CTRL-W T Move the current window to a new tab page. This fails if
454 there is only one window in the current tab page.
455 When a count is specified the new tab page will be opened
456 before the tab page with this index. Otherwise it comes after
457 the current tab page.
459 ==============================================================================
460 6. Window resizing *window-resize*
462 *CTRL-W_=*
463 CTRL-W = Make all windows (almost) equally high and wide, but use
464 'winheight' and 'winwidth' for the current window.
465 Windows with 'winfixheight' set keep their height and windows
466 with 'winfixwidth' set keep their width.
468 :res[ize] -N *:res* *:resize* *CTRL-W_-*
469 CTRL-W - Decrease current window height by N (default 1).
470 If used after |:vertical|: decrease width by N.
472 :res[ize] +N *CTRL-W_+*
473 CTRL-W + Increase current window height by N (default 1).
474 If used after |:vertical|: increase width by N.
476 :res[ize] [N]
477 CTRL-W CTRL-_ *CTRL-W_CTRL-_* *CTRL-W__*
478 CTRL-W _ Set current window height to N (default: highest possible).
480 z{nr}<CR> Set current window height to {nr}.
482 *CTRL-W_<*
483 CTRL-W < Decrease current window width by N (default 1).
485 *CTRL-W_>*
486 CTRL-W > Increase current window width by N (default 1).
488 :vertical res[ize] [N] *:vertical-resize* *CTRL-W_bar*
489 CTRL-W | Set current window width to N (default: widest possible).
491 You can also resize a window by dragging a status line up or down with the
492 mouse. Or by dragging a vertical separator line left or right. This only
493 works if the version of Vim that is being used supports the mouse and the
494 'mouse' option has been set to enable it.
496 The option 'winheight' ('wh') is used to set the minimal window height of the
497 current window. This option is used each time another window becomes the
498 current window. If the option is '0', it is disabled. Set 'winheight' to a
499 very large value, e.g., '9999', to make the current window always fill all
500 available space. Set it to a reasonable value, e.g., '10', to make editing in
501 the current window comfortable.
503 The equivalent 'winwidth' ('wiw') option is used to set the minimal width of
504 the current window.
506 When the option 'equalalways' ('ea') is set, all the windows are automatically
507 made the same size after splitting or closing a window. If you don't set this
508 option, splitting a window will reduce the size of the current window and
509 leave the other windows the same. When closing a window, the extra lines are
510 given to the window above it.
512 The 'eadirection' option limits the direction in which the 'equalalways'
513 option is applied. The default "both" resizes in both directions. When the
514 value is "ver" only the heights of windows are equalized. Use this when you
515 have manually resized a vertically split window and want to keep this width.
516 Likewise, "hor" causes only the widths of windows to be equalized.
518 The option 'cmdheight' ('ch') is used to set the height of the command-line.
519 If you are annoyed by the |hit-enter| prompt for long messages, set this
520 option to 2 or 3.
522 If there is only one window, resizing that window will also change the command
523 line height. If there are several windows, resizing the current window will
524 also change the height of the window below it (and sometimes the window above
525 it).
527 The minimal height and width of a window is set with 'winminheight' and
528 'winminwidth'. These are hard values, a window will never become smaller.
530 ==============================================================================
531 7. Argument and buffer list commands *buffer-list*
533 args list buffer list meaning ~
534 1. :[N]argument [N] 11. :[N]buffer [N] to arg/buf N
535 2. :[N]next [file ..] 12. :[N]bnext [N] to Nth next arg/buf
536 3. :[N]Next [N] 13. :[N]bNext [N] to Nth previous arg/buf
537 4. :[N]previous [N] 14. :[N]bprevious [N] to Nth previous arg/buf
538 5. :rewind / :first 15. :brewind / :bfirst to first arg/buf
539 6. :last 16. :blast to last arg/buf
540 7. :all 17. :ball edit all args/buffers
541 18. :unhide edit all loaded buffers
542 19. :[N]bmod [N] to Nth modified buf
544 split & args list split & buffer list meaning ~
545 21. :[N]sargument [N] 31. :[N]sbuffer [N] split + to arg/buf N
546 22. :[N]snext [file ..] 32. :[N]sbnext [N] split + to Nth next arg/buf
547 23. :[N]sNext [N] 33. :[N]sbNext [N] split + to Nth previous arg/buf
548 24. :[N]sprevious [N] 34. :[N]sbprevious [N] split + to Nth previous arg/buf
549 25. :srewind / :sfirst 35. :sbrewind / :sbfirst split + to first arg/buf
550 26. :slast 36. :sblast split + to last arg/buf
551 27. :sall 37. :sball edit all args/buffers
552 38. :sunhide edit all loaded buffers
553 39. :[N]sbmod [N] split + to Nth modified buf
555 40. :args list of arguments
556 41. :buffers list of buffers
558 The meaning of [N] depends on the command:
559 [N] is number of buffers to go forward/backward on ?2, ?3, and ?4
560 [N] is an argument number, defaulting to current argument, for 1 and 21
561 [N] is a buffer number, defaulting to current buffer, for 11 and 31
562 [N] is a count for 19 and 39
564 Note: ":next" is an exception, because it must accept a list of file names
565 for compatibility with Vi.
568 The argument list and multiple windows
569 --------------------------------------
571 The current position in the argument list can be different for each window.
572 Remember that when doing ":e file", the position in the argument list stays
573 the same, but you are not editing the file at that position. To indicate
574 this, the file message (and the title, if you have one) shows
575 "(file (N) of M)", where "(N)" is the current position in the file list, and
576 "M" the number of files in the file list.
578 All the entries in the argument list are added to the buffer list. Thus, you
579 can also get to them with the buffer list commands, like ":bnext".
581 :[N]al[l][!] [N] *:al* *:all* *:sal* *:sall*
582 :[N]sal[l][!] [N]
583 Rearrange the screen to open one window for each argument.
584 All other windows are closed. When a count is given, this is
585 the maximum number of windows to open.
586 With the |:tab| modifier open a tab page for each argument.
587 When there are more arguments than 'tabpagemax' further ones
588 become split windows in the last tab page.
589 When the 'hidden' option is set, all buffers in closed windows
590 become hidden.
591 When 'hidden' is not set, and the 'autowrite' option is set,
592 modified buffers are written. Otherwise, windows that have
593 buffers that are modified are not removed, unless the [!] is
594 given, then they become hidden. But modified buffers are
595 never abandoned, so changes cannot get lost.
596 [N] is the maximum number of windows to open. 'winheight'
597 also limits the number of windows opened ('winwidth' if
598 |:vertical| was prepended).
599 Buf/Win Enter/Leave autocommands are not executed for the new
600 windows here, that's only done when they are really entered.
602 :[N]sa[rgument][!] [++opt] [+cmd] [N] *:sa* *:sargument*
603 Short for ":split | argument [N]": split window and go to Nth
604 argument. But when there is no such argument, the window is
605 not split. Also see |++opt| and |+cmd|.
607 :[N]sn[ext][!] [++opt] [+cmd] [file ..] *:sn* *:snext*
608 Short for ":split | [N]next": split window and go to Nth next
609 argument. But when there is no next file, the window is not
610 split. Also see |++opt| and |+cmd|.
612 :[N]spr[evious][!] [++opt] [+cmd] [N] *:spr* *:sprevious*
613 :[N]sN[ext][!] [++opt] [+cmd] [N] *:sN* *:sNext*
614 Short for ":split | [N]Next": split window and go to Nth
615 previous argument. But when there is no previous file, the
616 window is not split. Also see |++opt| and |+cmd|.
618 *:sre* *:srewind*
619 :sre[wind][!] [++opt] [+cmd]
620 Short for ":split | rewind": split window and go to first
621 argument. But when there is no argument list, the window is
622 not split. Also see |++opt| and |+cmd|.
624 *:sfir* *:sfirst*
625 :sfir[st] [++opt] [+cmd]
626 Same as ":srewind".
628 *:sla* *:slast*
629 :sla[st][!] [++opt] [+cmd]
630 Short for ":split | last": split window and go to last
631 argument. But when there is no argument list, the window is
632 not split. Also see |++opt| and |+cmd|.
634 *:dr* *:drop*
635 :dr[op] [++opt] [+cmd] {file} ..
636 Edit the first {file} in a window.
637 - If the file is already open in a window change to that
638 window.
639 - If the file is not open in a window edit the file in the
640 current window. If the current buffer can't be |abandon|ed,
641 the window is split first.
642 The |argument-list| is set, like with the |:next| command.
643 The purpose of this command is that it can be used from a
644 program that wants Vim to edit another file, e.g., a debugger.
645 When using the |:tab| modifier each argument is opened in a
646 tab page. The last window is used if it's empty.
647 Also see |++opt| and |+cmd|.
648 {only available when compiled with a GUI}
650 ==============================================================================
651 8. Do a command in all buffers or windows *list-repeat*
653 *:windo*
654 :windo {cmd} Execute {cmd} in each window.
655 It works like doing this: >
656 CTRL-W t
657 :{cmd}
658 CTRL-W w
659 :{cmd}
660 etc.
661 < This only operates in the current tab page.
662 When an error is detected on one window, further
663 windows will not be visited.
664 The last window (or where an error occurred) becomes
665 the current window.
666 {cmd} can contain '|' to concatenate several commands.
667 {cmd} must not open or close windows or reorder them.
668 {not in Vi} {not available when compiled without the
669 |+listcmds| feature}
670 Also see |:tabdo|, |:argdo| and |:bufdo|.
672 *:bufdo*
673 :bufdo[!] {cmd} Execute {cmd} in each buffer in the buffer list.
674 It works like doing this: >
675 :bfirst
676 :{cmd}
677 :bnext
678 :{cmd}
679 etc.
680 < When the current file can't be |abandon|ed and the [!]
681 is not present, the command fails.
682 When an error is detected on one buffer, further
683 buffers will not be visited.
684 Unlisted buffers are skipped.
685 The last buffer (or where an error occurred) becomes
686 the current buffer.
687 {cmd} can contain '|' to concatenate several commands.
688 {cmd} must not delete buffers or add buffers to the
689 buffer list.
690 Note: While this command is executing, the Syntax
691 autocommand event is disabled by adding it to
692 'eventignore'. This considerably speeds up editing
693 each buffer.
694 {not in Vi} {not available when compiled without the
695 |+listcmds| feature}
696 Also see |:tabdo|, |:argdo| and |:windo|.
698 Examples: >
700 :windo set nolist nofoldcolumn | normal zn
702 This resets the 'list' option and disables folding in all windows. >
704 :bufdo set fileencoding= | update
706 This resets the 'fileencoding' in each buffer and writes it if this changed
707 the buffer. The result is that all buffers will use the 'encoding' encoding
708 (if conversion works properly).
710 ==============================================================================
711 9. Tag or file name under the cursor *window-tag*
713 *:sta* *:stag*
714 :sta[g][!] [tagname]
715 Does ":tag[!] [tagname]" and splits the window for the found
716 tag. See also |:tag|.
718 CTRL-W ] *CTRL-W_]* *CTRL-W_CTRL-]*
719 CTRL-W CTRL-] Split current window in two. Use identifier under cursor as a
720 tag and jump to it in the new upper window. Make new window N
721 high.
723 *CTRL-W_g]*
724 CTRL-W g ] Split current window in two. Use identifier under cursor as a
725 tag and perform ":tselect" on it in the new upper window.
726 Make new window N high.
728 *CTRL-W_g_CTRL-]*
729 CTRL-W g CTRL-] Split current window in two. Use identifier under cursor as a
730 tag and perform ":tjump" on it in the new upper window. Make
731 new window N high.
733 CTRL-W f *CTRL-W_f* *CTRL-W_CTRL-F*
734 CTRL-W CTRL-F Split current window in two. Edit file name under cursor.
735 Like ":split gf", but window isn't split if the file does not
736 exist.
737 Uses the 'path' variable as a list of directory names where to
738 look for the file. Also the path for current file is
739 used to search for the file name.
740 If the name is a hypertext link that looks like
741 "type://machine/path", only "/path" is used.
742 If a count is given, the count'th matching file is edited.
743 {not available when the |+file_in_path| feature was disabled
744 at compile time}
746 CTRL-W F *CTRL-W_F*
747 Split current window in two. Edit file name under cursor and
748 jump to the line number following the file name. See |gF| for
749 details on how the line number is obtained.
750 {not available when the |+file_in_path| feature was disabled
751 at compile time}
753 CTRL-W gf *CTRL-W_gf*
754 Open a new tab page and edit the file name under the cursor.
755 Like "tab split" and "gf", but the new tab page isn't created
756 if the file does not exist.
757 {not available when the |+file_in_path| feature was disabled
758 at compile time}
760 CTRL-W gF *CTRL-W_gF*
761 Open a new tab page and edit the file name under the cursor
762 and jump to the line number following the file name. Like
763 "tab split" and "gF", but the new tab page isn't created if
764 the file does not exist.
765 {not available when the |+file_in_path| feature was disabled
766 at compile time}
768 Also see |CTRL-W_CTRL-I|: open window for an included file that includes
769 the keyword under the cursor.
771 ==============================================================================
772 10. The preview window *preview-window*
774 The preview window is a special window to show (preview) another file. It is
775 normally a small window used to show an include file or definition of a
776 function.
777 {not available when compiled without the |+quickfix| feature}
779 There can be only one preview window (per tab page). It is created with one
780 of the commands below. The 'previewheight' option can be set to specify the
781 height of the preview window when it's opened. The 'previewwindow' option is
782 set in the preview window to be able to recognize it. The 'winfixheight'
783 option is set to have it keep the same height when opening/closing other
784 windows.
786 *:pta* *:ptag*
787 :pta[g][!] [tagname]
788 Does ":tag[!] [tagname]" and shows the found tag in a
789 "Preview" window without changing the current buffer or cursor
790 position. If a "Preview" window already exists, it is re-used
791 (like a help window is). If a new one is opened,
792 'previewheight' is used for the height of the window. See
793 also |:tag|.
794 See below for an example. |CursorHold-example|
795 Small difference from |:tag|: When [tagname] is equal to the
796 already displayed tag, the position in the matching tag list
797 is not reset. This makes the CursorHold example work after a
798 |:ptnext|.
800 CTRL-W z *CTRL-W_z*
801 CTRL-W CTRL-Z *CTRL-W_CTRL-Z* *:pc* *:pclose*
802 :pc[lose][!] Close any "Preview" window currently open. When the 'hidden'
803 option is set, or when the buffer was changed and the [!] is
804 used, the buffer becomes hidden (unless there is another
805 window editing it). The command fails if any "Preview" buffer
806 cannot be closed. See also |:close|.
808 *:pp* *:ppop*
809 :[count]pp[op][!]
810 Does ":[count]pop[!]" in the preview window. See |:pop| and
811 |:ptag|. {not in Vi}
813 CTRL-W } *CTRL-W_}*
814 Use identifier under cursor as a tag and perform a :ptag on
815 it. Make the new Preview window (if required) N high. If N is
816 not given, 'previewheight' is used.
818 CTRL-W g } *CTRL-W_g}*
819 Use identifier under cursor as a tag and perform a :ptjump on
820 it. Make the new Preview window (if required) N high. If N is
821 not given, 'previewheight' is used.
823 *:ped* *:pedit*
824 :ped[it][!] [++opt] [+cmd] {file}
825 Edit {file} in the preview window. The preview window is
826 opened like with |:ptag|. The current window and cursor
827 position isn't changed. Useful example: >
828 :pedit +/fputc /usr/include/stdio.h
829 <
830 *:ps* *:psearch*
831 :[range]ps[earch][!] [count] [/]pattern[/]
832 Works like |:ijump| but shows the found match in the preview
833 window. The preview window is opened like with |:ptag|. The
834 current window and cursor position isn't changed. Useful
835 example: >
836 :psearch popen
837 < Like with the |:ptag| command, you can use this to
838 automatically show information about the word under the
839 cursor. This is less clever than using |:ptag|, but you don't
840 need a tags file and it will also find matches in system
841 include files. Example: >
842 :au! CursorHold *.[ch] nested exe "silent! psearch " . expand("<cword>")
843 < Warning: This can be slow.
845 Example *CursorHold-example* >
847 :au! CursorHold *.[ch] nested exe "silent! ptag " . expand("<cword>")
849 This will cause a ":ptag" to be executed for the keyword under the cursor,
850 when the cursor hasn't moved for the time set with 'updatetime'. The "nested"
851 makes other autocommands be executed, so that syntax highlighting works in the
852 preview window. The "silent!" avoids an error message when the tag could not
853 be found. Also see |CursorHold|. To disable this again: >
855 :au! CursorHold
857 A nice addition is to highlight the found tag, avoid the ":ptag" when there
858 is no word under the cursor, and a few other things: >
860 :au! CursorHold *.[ch] nested call PreviewWord()
861 :func PreviewWord()
862 : if &previewwindow " don't do this in the preview window
863 : return
864 : endif
865 : let w = expand("<cword>") " get the word under cursor
866 : if w =~ '\a' " if the word contains a letter
867 :
868 : " Delete any existing highlight before showing another tag
869 : silent! wincmd P " jump to preview window
870 : if &previewwindow " if we really get there...
871 : match none " delete existing highlight
872 : wincmd p " back to old window
873 : endif
874 :
875 : " Try displaying a matching tag for the word under the cursor
876 : try
877 : exe "ptag " . w
878 : catch
879 : return
880 : endtry
881 :
882 : silent! wincmd P " jump to preview window
883 : if &previewwindow " if we really get there...
884 : if has("folding")
885 : silent! .foldopen " don't want a closed fold
886 : endif
887 : call search("$", "b") " to end of previous line
888 : let w = substitute(w, '\\', '\\\\', "")
889 : call search('\<\V' . w . '\>') " position cursor on match
890 : " Add a match highlight to the word at this position
891 : hi previewWord term=bold ctermbg=green guibg=green
892 : exe 'match previewWord "\%' . line(".") . 'l\%' . col(".") . 'c\k*"'
893 : wincmd p " back to old window
894 : endif
895 : endif
896 :endfun
898 ==============================================================================
899 11. Using hidden buffers *buffer-hidden*
901 A hidden buffer is not displayed in a window, but is still loaded into memory.
902 This makes it possible to jump from file to file, without the need to read or
903 write the file every time you get another buffer in a window.
904 {not available when compiled without the |+listcmds| feature}
906 *:buffer-!*
907 If the option 'hidden' ('hid') is set, abandoned buffers are kept for all
908 commands that start editing another file: ":edit", ":next", ":tag", etc. The
909 commands that move through the buffer list sometimes make the current buffer
910 hidden although the 'hidden' option is not set. This happens when a buffer is
911 modified, but is forced (with '!') to be removed from a window, and
912 'autowrite' is off or the buffer can't be written.
914 You can make a hidden buffer not hidden by starting to edit it with any
915 command. Or by deleting it with the ":bdelete" command.
917 The 'hidden' is global, it is used for all buffers. The 'bufhidden' option
918 can be used to make an exception for a specific buffer. It can take these
919 values:
920 <empty> Use the value of 'hidden'.
921 hide Hide this buffer, also when 'hidden' is not set.
922 unload Don't hide but unload this buffer, also when 'hidden'
923 is set.
924 delete Delete the buffer.
926 *hidden-quit*
927 When you try to quit Vim while there is a hidden, modified buffer, you will
928 get an error message and Vim will make that buffer the current buffer. You
929 can then decide to write this buffer (":wq") or quit without writing (":q!").
930 Be careful: there may be more hidden, modified buffers!
932 A buffer can also be unlisted. This means it exists, but it is not in the
933 list of buffers. |unlisted-buffer|
936 :files[!] *:files*
937 :buffers[!] *:buffers* *:ls*
938 :ls[!] Show all buffers. Example:
940 1 #h "/test/text" line 1 ~
941 2u "asdf" line 0 ~
942 3 %a+ "version.c" line 1 ~
944 When the [!] is included the list will show unlisted buffers
945 (the term "unlisted" is a bit confusing then...).
947 Each buffer has a unique number. That number will not change,
948 so you can always go to a specific buffer with ":buffer N" or
949 "N CTRL-^", where N is the buffer number.
951 Indicators (chars in the same column are mutually exclusive):
952 u an unlisted buffer (only displayed when [!] is used)
953 |unlisted-buffer|
954 % the buffer in the current window
955 # the alternate buffer for ":e #" and CTRL-^
956 a an active buffer: it is loaded and visible
957 h a hidden buffer: It is loaded, but currently not
958 displayed in a window |hidden-buffer|
959 - a buffer with 'modifiable' off
960 = a readonly buffer
961 + a modified buffer
962 x a buffer with read errors
964 *:bad* *:badd*
965 :bad[d] [+lnum] {fname}
966 Add file name {fname} to the buffer list, without loading it.
967 If "lnum" is specified, the cursor will be positioned at that
968 line when the buffer is first entered. Note that other
969 commands after the + will be ignored.
971 :[N]bd[elete][!] *:bd* *:bdel* *:bdelete* *E516*
972 :bd[elete][!] [N]
973 Unload buffer [N] (default: current buffer) and delete it from
974 the buffer list. If the buffer was changed, this fails,
975 unless when [!] is specified, in which case changes are lost.
976 The file remains unaffected. Any windows for this buffer are
977 closed. If buffer [N] is the current buffer, another buffer
978 will be displayed instead. This is the most recent entry in
979 the jump list that points into a loaded buffer.
980 Actually, the buffer isn't completely deleted, it is removed
981 from the buffer list |unlisted-buffer| and option values,
982 variables and mappings/abbreviations for the buffer are
983 cleared.
985 :bdelete[!] {bufname} *E93* *E94*
986 Like ":bdelete[!] [N]", but buffer given by name. Note that a
987 buffer whose name is a number cannot be referenced by that
988 name; use the buffer number instead. Insert a backslash
989 before a space in a buffer name.
991 :bdelete[!] N1 N2 ...
992 Do ":bdelete[!]" for buffer N1, N2, etc. The arguments can be
993 buffer numbers or buffer names (but not buffer names that are
994 a number). Insert a backslash before a space in a buffer
995 name.
997 :N,Mbdelete[!] Do ":bdelete[!]" for all buffers in the range N to M
998 |inclusive|.
1000 :[N]bw[ipeout][!] *:bw* *:bwipe* *:bwipeout* *E517*
1001 :bw[ipeout][!] {bufname}
1002 :N,Mbw[ipeout][!]
1003 :bw[ipeout][!] N1 N2 ...
1004 Like |:bdelete|, but really delete the buffer. Everything
1005 related to the buffer is lost. All marks in this buffer
1006 become invalid, option settings are lost, etc. Don't use this
1007 unless you know what you are doing.
1009 :[N]bun[load][!] *:bun* *:bunload* *E515*
1010 :bun[load][!] [N]
1011 Unload buffer [N] (default: current buffer). The memory
1012 allocated for this buffer will be freed. The buffer remains
1013 in the buffer list.
1014 If the buffer was changed, this fails, unless when [!] is
1015 specified, in which case the changes are lost.
1016 Any windows for this buffer are closed. If buffer [N] is the
1017 current buffer, another buffer will be displayed instead.
1018 This is the most recent entry in the jump list that points
1019 into a loaded buffer.
1021 :bunload[!] {bufname}
1022 Like ":bunload[!] [N]", but buffer given by name. Note that a
1023 buffer whose name is a number cannot be referenced by that
1024 name; use the buffer number instead. Insert a backslash
1025 before a space in a buffer name.
1027 :N,Mbunload[!] Do ":bunload[!]" for all buffers in the range N to M
1028 |inclusive|.
1030 :bunload[!] N1 N2 ...
1031 Do ":bunload[!]" for buffer N1, N2, etc. The arguments can be
1032 buffer numbers or buffer names (but not buffer names that are
1033 a number). Insert a backslash before a space in a buffer
1034 name.
1036 :[N]b[uffer][!] [N] *:b* *:bu* *:buf* *:buffer* *E86*
1037 Edit buffer [N] from the buffer list. If [N] is not given,
1038 the current buffer remains being edited. See |:buffer-!| for
1039 [!]. This will also edit a buffer that is not in the buffer
1040 list, without setting the 'buflisted' flag.
1042 :[N]b[uffer][!] {bufname}
1043 Edit buffer for {bufname} from the buffer list. See
1044 |:buffer-!| for [!]. This will also edit a buffer that is not
1045 in the buffer list, without setting the 'buflisted' flag.
1047 :[N]sb[uffer] [N] *:sb* *:sbuffer*
1048 Split window and edit buffer [N] from the buffer list. If [N]
1049 is not given, the current buffer is edited. Respects the
1050 "useopen" setting of 'switchbuf' when splitting. This will
1051 also edit a buffer that is not in the buffer list, without
1052 setting the 'buflisted' flag.
1054 :[N]sb[uffer] {bufname}
1055 Split window and edit buffer for {bufname} from the buffer
1056 list. This will also edit a buffer that is not in the buffer
1057 list, without setting the 'buflisted' flag.
1058 Note: If what you want to do is split the buffer, make a copy
1059 under another name, you can do it this way: >
1060 :w foobar | sp #
1062 :[N]bn[ext][!] [N] *:bn* *:bnext* *E87*
1063 Go to [N]th next buffer in buffer list. [N] defaults to one.
1064 Wraps around the end of the buffer list.
1065 See |:buffer-!| for [!].
1066 If you are in a help buffer, this takes you to the next help
1067 buffer (if there is one). Similarly, if you are in a normal
1068 (non-help) buffer, this takes you to the next normal buffer.
1069 This is so that if you have invoked help, it doesn't get in
1070 the way when you're browsing code/text buffers. The next three
1071 commands also work like this.
1073 *:sbn* *:sbnext*
1074 :[N]sbn[ext] [N]
1075 Split window and go to [N]th next buffer in buffer list.
1076 Wraps around the end of the buffer list. Uses 'switchbuf'
1078 :[N]bN[ext][!] [N] *:bN* *:bNext* *:bp* *:bprevious* *E88*
1079 :[N]bp[revious][!] [N]
1080 Go to [N]th previous buffer in buffer list. [N] defaults to
1081 one. Wraps around the start of the buffer list.
1082 See |:buffer-!| for [!] and 'switchbuf'.
1084 :[N]sbN[ext] [N] *:sbN* *:sbNext* *:sbp* *:sbprevious*
1085 :[N]sbp[revious] [N]
1086 Split window and go to [N]th previous buffer in buffer list.
1087 Wraps around the start of the buffer list.
1088 Uses 'switchbuf'.
1090 *:br* *:brewind*
1091 :br[ewind][!] Go to first buffer in buffer list. If the buffer list is
1092 empty, go to the first unlisted buffer.
1093 See |:buffer-!| for [!].
1095 *:bf* *:bfirst*
1096 :bf[irst] Same as ":brewind".
1098 *:sbr* *:sbrewind*
1099 :sbr[ewind] Split window and go to first buffer in buffer list. If the
1100 buffer list is empty, go to the first unlisted buffer.
1101 Respects the 'switchbuf' option.
1103 *:sbf* *:sbfirst*
1104 :sbf[irst] Same as ":sbrewind".
1106 *:bl* *:blast*
1107 :bl[ast][!] Go to last buffer in buffer list. If the buffer list is
1108 empty, go to the last unlisted buffer.
1109 See |:buffer-!| for [!].
1111 *:sbl* *:sblast*
1112 :sbl[ast] Split window and go to last buffer in buffer list. If the
1113 buffer list is empty, go to the last unlisted buffer.
1114 Respects 'switchbuf' option.
1116 :[N]bm[odified][!] [N] *:bm* *:bmodified* *E84*
1117 Go to [N]th next modified buffer. Note: this command also
1118 finds unlisted buffers. If there is no modified buffer the
1119 command fails.
1121 :[N]sbm[odified] [N] *:sbm* *:sbmodified*
1122 Split window and go to [N]th next modified buffer.
1123 Respects 'switchbuf' option.
1124 Note: this command also finds buffers not in the buffer list.
1126 :[N]unh[ide] [N] *:unh* *:unhide* *:sun* *:sunhide*
1127 :[N]sun[hide] [N]
1128 Rearrange the screen to open one window for each loaded buffer
1129 in the buffer list. When a count is given, this is the
1130 maximum number of windows to open.
1132 :[N]ba[ll] [N] *:ba* *:ball* *:sba* *:sball*
1133 :[N]sba[ll] [N] Rearrange the screen to open one window for each buffer in
1134 the buffer list. When a count is given, this is the maximum
1135 number of windows to open. 'winheight' also limits the number
1136 of windows opened ('winwidth' if |:vertical| was prepended).
1137 Buf/Win Enter/Leave autocommands are not executed for the new
1138 windows here, that's only done when they are really entered.
1139 When the |:tab| modifier is used new windows are opened in a
1140 new tab, up to 'tabpagemax'.
1142 Note: All the commands above that start editing another buffer, keep the
1143 'readonly' flag as it was. This differs from the ":edit" command, which sets
1144 the 'readonly' flag each time the file is read.
1146 ==============================================================================
1147 12. Special kinds of buffers *special-buffers*
1149 Instead of containing the text of a file, buffers can also be used for other
1150 purposes. A few options can be set to change the behavior of a buffer:
1151 'bufhidden' what happens when the buffer is no longer displayed
1152 in a window.
1153 'buftype' what kind of a buffer this is
1154 'swapfile' whether the buffer will have a swap file
1155 'buflisted' buffer shows up in the buffer list
1157 A few useful kinds of a buffer:
1159 quickfix Used to contain the error list or the location list. See
1160 |:cwindow| and |:lwindow|. This command sets the 'buftype'
1161 option to "quickfix". You are not supposed to change this!
1162 'swapfile' is off.
1164 help Contains a help file. Will only be created with the |:help|
1165 command. The flag that indicates a help buffer is internal
1166 and can't be changed. The 'buflisted' option will be reset
1167 for a help buffer.
1169 directory Displays directory contents. Can be used by a file explorer
1170 plugin. The buffer is created with these settings: >
1171 :setlocal buftype=nowrite
1172 :setlocal bufhidden=delete
1173 :setlocal noswapfile
1174 < The buffer name is the name of the directory and is adjusted
1175 when using the |:cd| command.
1177 scratch Contains text that can be discarded at any time. It is kept
1178 when closing the window, it must be deleted explicitly.
1179 Settings: >
1180 :setlocal buftype=nofile
1181 :setlocal bufhidden=hide
1182 :setlocal noswapfile
1183 < The buffer name can be used to identify the buffer, if you
1184 give it a meaningful name.
1186 *unlisted-buffer*
1187 unlisted The buffer is not in the buffer list. It is not used for
1188 normal editing, but to show a help file, remember a file name
1189 or marks. The ":bdelete" command will also set this option,
1190 thus it doesn't completely delete the buffer. Settings: >
1191 :setlocal nobuflisted
1192 <
1194 vim:tw=78:ts=8:ft=help:norl: