vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

usr_08.txt (19467B)


      1 *usr_08.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
      2 
      3 
      4 		     VIM USER MANUAL	by Bram Moolenaar
      5 
      6 
      7 			      Splitting windows
      8 
      9 
     10 Display two different files above each other.  Or view two locations in the
     11 file at the same time.  See the difference between two files by putting them
     12 side by side.  All this is possible with split windows.
     13 
     14 |08.1|	Split a window
     15 |08.2|	Split a window on another file
     16 |08.3|	Window size
     17 |08.4|	Vertical splits
     18 |08.5|	Moving windows
     19 |08.6|	Commands for all windows
     20 |08.7|	Viewing differences with vimdiff
     21 |08.8|	Various
     22 |08.9|	Tab pages
     23 
     24      Next chapter: |usr_09.txt|  Using the GUI
     25  Previous chapter: |usr_07.txt|  Editing more than one file
     26 Table of contents: |usr_toc.txt|
     27 
     28 ==============================================================================
     29 *08.1*	Split a window
     30 
     31 The easiest way to open a new window is to use the following command: >
     32 
     33 	:split
     34 
     35 This command splits the screen into two windows and leaves the cursor in the
     36 top one:
     37 
     38 	+----------------------------------+
     39 	|/* file one.c */		   |
     40 	|~				   |
     41 	|~				   |
     42 	|one.c=============================|
     43 	|/* file one.c */		   |
     44 	|~				   |
     45 	|one.c=============================|
     46 	|				   |
     47 	+----------------------------------+
     48 
     49 What you see here is two windows on the same file.  The line with "====" is
     50 the status line.  It displays information about the window above it.  (In
     51 practice the status line will be in reverse video.)
     52    The two windows allow you to view two parts of the same file.  For example,
     53 you could make the top window show the variable declarations of a program, and
     54 the bottom one the code that uses these variables.
     55 
     56 The CTRL-W w command can be used to jump between the windows.  If you are in
     57 the top window, CTRL-W w jumps to the window below it.  If you are in the
     58 bottom window it will jump to the first window.  (CTRL-W CTRL-W does the same
     59 thing, in case you let go of the CTRL key a bit later.)
     60 
     61 
     62 CLOSE THE WINDOW
     63 
     64 To close a window, use the command: >
     65 
     66 	:close
     67 
     68 Actually, any command that quits editing a file works, like ":quit" and "ZZ".
     69 But ":close" prevents you from accidentally exiting Vim when you close the
     70 last window.
     71 
     72 
     73 CLOSING ALL OTHER WINDOWS
     74 
     75 If you have opened a whole bunch of windows, but now want to concentrate on
     76 one of them, this command will be useful: >
     77 
     78 	:only
     79 
     80 This closes all windows, except for the current one.  If any of the other
     81 windows has changes, you will get an error message and that window won't be
     82 closed.
     83 
     84 ==============================================================================
     85 *08.2*	Split a window on another file
     86 
     87 The following command opens a second window and starts editing the given file:
     88 >
     89 	:split two.c
     90 
     91 If you were editing one.c, then the result looks like this:
     92 
     93 	+----------------------------------+
     94 	|/* file two.c */		   |
     95 	|~				   |
     96 	|~				   |
     97 	|two.c=============================|
     98 	|/* file one.c */		   |
     99 	|~				   |
    100 	|one.c=============================|
    101 	|				   |
    102 	+----------------------------------+
    103 
    104 To open a window on a new, empty file, use this: >
    105 
    106 	:new
    107 
    108 You can repeat the ":split" and ":new" commands to create as many windows as
    109 you like.
    110 
    111 ==============================================================================
    112 *08.3*	Window size
    113 
    114 The ":split" command can take a number argument.  If specified, this will be
    115 the height of the new window.  For example, the following opens a new window
    116 three lines high and starts editing the file alpha.c: >
    117 
    118 	:3split alpha.c
    119 
    120 For existing windows you can change the size in several ways.  When you have a
    121 working mouse, it is easy: Move the mouse pointer to the status line that
    122 separates two windows, and drag it up or down.
    123 
    124 To increase the size of a window: >
    125 
    126 	CTRL-W +
    127 
    128 To decrease it: >
    129 
    130 	CTRL-W -
    131 
    132 Both of these commands take a count and increase or decrease the window size
    133 by that many lines.  Thus "4 CTRL-W +" make the window four lines higher.
    134 
    135 To set the window height to a specified number of lines: >
    136 
    137 	{height}CTRL-W _
    138 
    139 That's: a number {height}, CTRL-W and then an underscore (the - key with Shift
    140 on English-US keyboards).
    141    To make a window as high as it can be, use the CTRL-W _ command without a
    142 count.
    143 
    144 
    145 USING THE MOUSE
    146 
    147 In Vim you can do many things very quickly from the keyboard.  Unfortunately,
    148 the window resizing commands require quite a bit of typing.  In this case,
    149 using the mouse is faster.  Position the mouse pointer on a status line.  Now
    150 press the left mouse button and drag.  The status line will move, thus making
    151 the window on one side higher and the other smaller.
    152 
    153 
    154 OPTIONS
    155 
    156 The 'winheight' option can be set to a minimal desired height of a window and
    157 'winminheight' to a hard minimum height.
    158    Likewise, there is 'winwidth' for the minimal desired width and
    159 'winminwidth' for the hard minimum width.
    160    The 'equalalways' option, when set, makes Vim equalize the windows sizes
    161 when a window is closed or opened.
    162 
    163 ==============================================================================
    164 *08.4*	Vertical splits
    165 
    166 The ":split" command creates the new window above the current one.  To make
    167 the window appear at the left side, use: >
    168 
    169 	:vsplit
    170 
    171 or: >
    172 	:vsplit two.c
    173 
    174 The result looks something like this:
    175 
    176 	+--------------------------------------+
    177 	|/* file two.c */   |/* file one.c */  |
    178 	|~		    |~		       |
    179 	|~		    |~		       |
    180 	|~		    |~		       |
    181 	|two.c===============one.c=============|
    182 	|				       |
    183 	+--------------------------------------+
    184 
    185 Actually, the | lines in the middle will be in reverse video.  This is called
    186 the vertical separator.  It separates the two windows left and right of it.
    187 
    188 There is also the ":vnew" command, to open a vertically split window on a new,
    189 empty file.  Another way to do this: >
    190 
    191 	:vertical new
    192 
    193 The ":vertical" command can be inserted before another command that splits a
    194 window.  This will cause that command to split the window vertically instead
    195 of horizontally.  (If the command doesn't split a window, it works
    196 unmodified.)
    197 
    198 
    199 MOVING BETWEEN WINDOWS
    200 
    201 Since you can split windows horizontally and vertically as much as you like,
    202 you can create almost any layout of windows.  Then you can use these commands
    203 to move between them:
    204 
    205 	CTRL-W h	move to the window on the left
    206 	CTRL-W j	move to the window below
    207 	CTRL-W k	move to the window above
    208 	CTRL-W l	move to the window on the right
    209 
    210 	CTRL-W t	move to the TOP window
    211 	CTRL-W b	move to the BOTTOM window
    212 
    213 You will notice the same letters as used for moving the cursor.  And the
    214 cursor keys can also be used, if you like.
    215    More commands to move to other windows: |Q_wi|.
    216 
    217 ==============================================================================
    218 *08.5*	Moving windows
    219 
    220 You have split a few windows, but now they are in the wrong place.  Then you
    221 need a command to move the window somewhere else.  For example, you have three
    222 windows like this:
    223 
    224 	+----------------------------------+
    225 	|/* file two.c */		   |
    226 	|~				   |
    227 	|~				   |
    228 	|two.c=============================|
    229 	|/* file three.c */		   |
    230 	|~				   |
    231 	|~				   |
    232 	|three.c===========================|
    233 	|/* file one.c */		   |
    234 	|~				   |
    235 	|one.c=============================|
    236 	|				   |
    237 	+----------------------------------+
    238 
    239 Clearly the last one should be at the top.  Go to that window (using CTRL-W w)
    240 and then type this command: >
    241 
    242 	CTRL-W K
    243 
    244 This uses the uppercase letter K.  What happens is that the window is moved to
    245 the very top.  You will notice that K is again used for moving upwards.
    246    When you have vertical splits, CTRL-W K will move the current window to the
    247 top and make it occupy the full width of the Vim window.  If this is your
    248 layout:
    249 
    250 	+-------------------------------------------+
    251 	|/* two.c */  |/* three.c */  |/* one.c */  |
    252 	|~	      |~	      |~	    |
    253 	|~	      |~	      |~	    |
    254 	|~	      |~	      |~	    |
    255 	|~	      |~	      |~	    |
    256 	|~	      |~	      |~	    |
    257 	|two.c=========three.c=========one.c========|
    258 	|					    |
    259 	+-------------------------------------------+
    260 
    261 Then using CTRL-W K in the middle window (three.c) will result in:
    262 
    263 	+-------------------------------------------+
    264 	|/* three.c */				    |
    265 	|~					    |
    266 	|~					    |
    267 	|three.c====================================|
    268 	|/* two.c */	       |/* one.c */	    |
    269 	|~		       |~		    |
    270 	|two.c==================one.c===============|
    271 	|					    |
    272 	+-------------------------------------------+
    273 
    274 The other three similar commands (you can probably guess these now):
    275 
    276 	CTRL-W H	move window to the far left
    277 	CTRL-W J	move window to the bottom
    278 	CTRL-W L	move window to the far right
    279 
    280 ==============================================================================
    281 *08.6*	Commands for all windows
    282 
    283 When you have several windows open and you want to quit Vim, you can close
    284 each window separately.  A quicker way is using this command: >
    285 
    286 	:qall
    287 
    288 This stands for "quit all".  If any of the windows contain changes, Vim will
    289 not exit.  The cursor will automatically be positioned in a window with
    290 changes.  You can then either use ":write" to save the changes, or ":quit!" to
    291 throw them away.
    292 
    293 If you know there are windows with changes, and you want to save all these
    294 changes, use this command: >
    295 
    296 	:wall
    297 
    298 This stands for "write all".  But actually, it only writes files with
    299 changes.  Vim knows it doesn't make sense to write files that were not
    300 changed.
    301    And then there is the combination of ":qall" and ":wall": the "write and
    302 quit all" command: >
    303 
    304 	:wqall
    305 
    306 This writes all modified files and quits Vim.
    307    Finally, there is a command that quits Vim and throws away all changes: >
    308 
    309 	:qall!
    310 
    311 Be careful, there is no way to undo this command!
    312 
    313 
    314 OPENING A WINDOW FOR ALL ARGUMENTS
    315 
    316 To make Vim open a window for each file, start it with the "-o" argument: >
    317 
    318 	vim -o one.txt two.txt three.txt
    319 
    320 This results in:
    321 
    322 	+-------------------------------+
    323 	|file one.txt			|
    324 	|~				|
    325 	|one.txt========================|
    326 	|file two.txt			|
    327 	|~				|
    328 	|two.txt========================|
    329 	|file three.txt			|
    330 	|~				|
    331 	|three.txt======================|
    332 	|				|
    333 	+-------------------------------+
    334 
    335 The "-O" argument is used to get vertically split windows.
    336    When Vim is already running, the ":all" command opens a window for each
    337 file in the argument list.  ":vertical all" does it with vertical splits.
    338 
    339 ==============================================================================
    340 *08.7*	Viewing differences with vimdiff
    341 
    342 There is a special way to start Vim, which shows the differences between two
    343 files.  Let's take a file "main.c" and insert a few characters in one line.
    344 Write this file with the 'backup' option set, so that the backup file
    345 "main.c~" will contain the previous version of the file.
    346    Type this command in a shell (not in Vim): >
    347 
    348 	vimdiff main.c~ main.c
    349 
    350 Vim will start, with two windows side by side.  You will only see the line
    351 in which you added characters, and a few lines above and below it.
    352 
    353 	 VV		      VV
    354 	+-----------------------------------------+
    355 	|+ +--123 lines: /* a|+ +--123 lines: /* a|  <- fold
    356 	|  text		     |	text		  |
    357 	|  text		     |	text		  |
    358 	|  text		     |	text		  |
    359 	|  text		     |	changed text	  |  <- changed line
    360 	|  text		     |	text		  |
    361 	|  text		     |	------------------|  <- deleted line
    362 	|  text		     |	text		  |
    363 	|  text		     |	text		  |
    364 	|  text		     |	text		  |
    365 	|+ +--432 lines: text|+ +--432 lines: text|  <- fold
    366 	|  ~		     |	~		  |
    367 	|  ~		     |	~		  |
    368 	|main.c~==============main.c==============|
    369 	|					  |
    370 	+-----------------------------------------+
    371 
    372 (This picture doesn't show the highlighting, use the vimdiff command for a
    373 better look.)
    374 
    375 The lines that were not modified have been collapsed into one line.  This is
    376 called a closed fold.  They are indicated in the picture with "<- fold".  Thus
    377 the single fold line at the top stands for 123 text lines.  These lines are
    378 equal in both files.
    379    The line marked with "<- changed line" is highlighted, and the inserted
    380 text is displayed with another color.  This clearly shows what the difference
    381 is between the two files.
    382    The line that was deleted is displayed with "---" in the main.c window.
    383 See the "<- deleted line" marker in the picture.  These characters are not
    384 really there.  They just fill up main.c, so that it displays the same number
    385 of lines as the other window.
    386 
    387 
    388 THE FOLD COLUMN
    389 
    390 Each window has a column on the left with a slightly different background.  In
    391 the picture above these are indicated with "VV".  You notice there is a plus
    392 character there, in front of each closed fold.  Move the mouse pointer to that
    393 plus and click the left button.  The fold will open, and you can see the text
    394 that it contains.
    395    The fold column contains a minus sign for an open fold.  If you click on
    396 this -, the fold will close.
    397    Obviously, this only works when you have a working mouse.  You can also use
    398 "zo" to open a fold and "zc" to close it.
    399 
    400 
    401 DIFFING IN VIM
    402 
    403 Another way to start in diff mode can be done from inside Vim.  Edit the
    404 "main.c" file, then make a split and show the differences: >
    405 
    406 	:edit main.c
    407 	:vertical diffsplit main.c~
    408 
    409 The ":vertical" command is used to make the window split vertically.  If you
    410 omit this, you will get a horizontal split.
    411 
    412 If you have a patch or diff file, you can use the third way to start diff
    413 mode.  First edit the file to which the patch applies.  Then tell Vim the name
    414 of the patch file: >
    415 
    416 	:edit main.c
    417 	:vertical diffpatch main.c.diff
    418 
    419 WARNING: The patch file must contain only one patch, for the file you are
    420 editing.  Otherwise you will get a lot of error messages, and some files might
    421 be patched unexpectedly.
    422    The patching will only be done to the copy of the file in Vim.  The file on
    423 your harddisk will remain unmodified (until you decide to write the file).
    424 
    425 
    426 SCROLL BINDING
    427 
    428 When the files have more changes, you can scroll in the usual way.  Vim will
    429 try to keep both the windows start at the same position, so you can easily see
    430 the differences side by side.
    431    When you don't want this for a moment, use this command: >
    432 
    433 	:set noscrollbind
    434 
    435 
    436 JUMPING TO CHANGES
    437 
    438 When you have disabled folding in some way, it may be difficult to find the
    439 changes.  Use this command to jump forward to the next change: >
    440 
    441 	]c
    442 
    443 To go the other way use: >
    444 
    445 	[c
    446 
    447 Prepend a count to jump further away. Thus "4]c" jumps to the fourth next
    448 change, and "3[c" jumps to the third previous change.
    449 
    450 
    451 REMOVING CHANGES
    452 
    453 You can move text from one window to the other.  This either removes
    454 differences or adds new ones.  Vim doesn't keep the highlighting updated in
    455 all situations.  To update it use this command: >
    456 
    457 	:diffupdate
    458 
    459 To remove a difference, you can move the text in a highlighted block from one
    460 window to another.  Take the "main.c" and "main.c~" example above.  Move the
    461 cursor to the left window, on the line that was deleted in the other window.
    462 Now type this command: >
    463 
    464 	dp
    465 
    466 The change will be removed by putting the text of the current window in the
    467 other window.  "dp" stands for "diff put".
    468    You can also do it the other way around.  Move the cursor to the right
    469 window, to the line where "changed" was inserted.  Now type this command: >
    470 
    471 	do
    472 
    473 The change will now be removed by getting the text from the other window.
    474 Since there are no changes left now, Vim puts all text in a closed fold.
    475 "do" stands for "diff obtain".  "dg" would have been better, but that already
    476 has a different meaning ("dgg" deletes from the cursor until the first line).
    477 
    478 For details about diff mode, see |vimdiff|.
    479 
    480 ==============================================================================
    481 *08.8*	Various
    482 
    483 The 'laststatus' option can be used to specify when the last window has a
    484 statusline:
    485 
    486 	0	never
    487 	1	only when there are split windows (the default)
    488 	2	always
    489 
    490 Many commands that edit another file have a variant that splits the window.
    491 For Command-line commands this is done by prepending an "s".  For example:
    492 ":tag" jumps to a tag, ":stag" splits the window and jumps to a
    493 tag.
    494    For Normal mode commands a CTRL-W is prepended.  CTRL-^ jumps to the
    495 alternate file, CTRL-W CTRL-^ splits the window and edits the alternate file.
    496 
    497 The 'splitbelow' option can be set to make a new window appear below the
    498 current window.  The 'splitright' option can be set to make a vertically split
    499 window appear right of the current window.
    500 
    501 When splitting a window you can prepend a modifier command to tell where the
    502 window is to appear:
    503 
    504 	:leftabove {cmd}	left or above the current window
    505 	:aboveleft {cmd}	idem
    506 	:rightbelow {cmd}	right or below the current window
    507 	:belowright {cmd}	idem
    508 	:topleft {cmd}		at the top or left of the Vim window
    509 	:botright {cmd}		at the bottom or right of the Vim window
    510 
    511 
    512 ==============================================================================
    513 *08.9*	Tab pages
    514 
    515 You will have noticed that windows never overlap.  That means you quickly run
    516 out of screen space.  The solution for this is called Tab pages.
    517 
    518 Assume you are editing "thisfile".  To create a new tab page use this command: >
    519 
    520 	:tabedit thatfile
    521 
    522 This will edit the file "thatfile" in a window that occupies the whole Vim
    523 window.  And you will notice a bar at the top with the two file names:
    524 
    525 	+----------------------------------+
    526 	| thisfile | /thatfile/ __________X|    (thatfile is bold)
    527 	|/* thatfile */			   |
    528 	|that				   |
    529 	|that				   |
    530 	|~				   |
    531 	|~				   |
    532 	|~				   |
    533 	|				   |
    534 	+----------------------------------+
    535 
    536 You now have two tab pages.  The first one has a window for "thisfile" and the
    537 second one a window for "thatfile".  It's like two pages that are on top of
    538 each other, with a tab sticking out of each page showing the file name.
    539 
    540 Now use the mouse to click on "thisfile" in the top line.  The result is
    541 
    542 	+----------------------------------+
    543 	| /thisfile/ | thatfile __________X|    (thisfile is bold)
    544 	|/* thisfile */			   |
    545 	|this				   |
    546 	|this				   |
    547 	|~				   |
    548 	|~				   |
    549 	|~				   |
    550 	|				   |
    551 	+----------------------------------+
    552 
    553 Thus you can switch between tab pages by clicking on the label in the top
    554 line.  If you don't have a mouse or don't want to use it, you can use the "gt"
    555 command.  Mnemonic: Goto Tab.
    556 
    557 Now let's create another tab page with the command: >
    558 
    559 	:tab split
    560 
    561 This makes a new tab page with one window that is editing the same buffer as
    562 the window we were in:
    563 
    564 	+-------------------------------------+
    565 	| thisfile | /thisfile/ | thatfile __X|   (thisfile is bold)
    566 	|/* thisfile */			      |
    567 	|this				      |
    568 	|this				      |
    569 	|~				      |
    570 	|~				      |
    571 	|~				      |
    572 	|				      |
    573 	+-------------------------------------+
    574 
    575 You can put ":tab" before any Ex command that opens a window.  The window will
    576 be opened in a new tab page.  Another example: >
    577 
    578 	:tab help gt
    579 
    580 Will show the help text for "gt" in a new tab page.
    581 
    582 A few more things you can do with tab pages:
    583 
    584 - click with the mouse in the space after the last label
    585 	The next tab page will be selected, like with "gt".
    586 
    587 - click with the mouse on the "X" in the top right corner
    588 	The current tab page will be closed.  Unless there are unsaved
    589 	changes in the current tab page.
    590 
    591 - double click with the mouse in the top line
    592 	A new tab page will be created.
    593 
    594 - the "tabonly" command
    595 	Closes all tab pages except the current one.  Unless there are unsaved
    596 	changes in other tab pages.
    597 
    598 For more information about tab pages see |tab-page|.
    599 
    600 ==============================================================================
    601 
    602 Next chapter: |usr_09.txt|  Using the GUI
    603 
    604 Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: