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