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