vim

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

usr_22.txt (14254B)


      1 *usr_22.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
      2 
      3 
      4 		     VIM USER MANUAL	by Bram Moolenaar
      5 
      6 
      7 			   Finding the file to edit
      8 
      9 
     10 Files can be found everywhere.  So how do you find them?  Vim offers various
     11 ways to browse the directory tree.  There are commands to jump to a file that
     12 is mentioned in another.  And Vim remembers which files have been edited
     13 before.
     14 
     15 |22.1|	The file browser
     16 |22.2|	The current directory
     17 |22.3|	Finding a file
     18 |22.4|	The buffer list
     19 
     20      Next chapter: |usr_23.txt|  Editing other files
     21  Previous chapter: |usr_21.txt|  Go away and come back
     22 Table of contents: |usr_toc.txt|
     23 
     24 ==============================================================================
     25 *22.1*	The file browser
     26 
     27 Vim has a plugin that makes it possible to edit a directory.  Try this: >
     28 
     29 	:edit .
     30 
     31 Through the magic of autocommands and Vim scripts, the window will be filled
     32 with the contents of the directory.  It looks like this (slightly cleaned up
     33 so that it fits within 78 chars): >
     34 
     35   " ==========================================================================
     36   " Netrw Directory Listing                                       (netrw v184)
     37   "   /path/to/vim/runtime/doc
     38   "   Sorted by      name
     39   "   Sort sequence: [\/]$,*,\(\.bak\|\~\|\.o\|\.h\|\.info\|\.swp\)[*@]\=$
     40   "   Quick Help: <F1>:help -:go up dir D:delete R:rename s:sort-by x:special
     41   " ==========================================================================
     42   ../
     43   ./
     44   check/
     45   Makefile
     46   autocmd.txt
     47   change.txt
     48   eval.txt
     49   filetype.txt
     50   help.txt.info
     51 
     52 You can see these items:
     53 
     54 1. The name of the browsing tool and its version number
     55 2. The name of the browsing directory
     56 3. The method of sorting (may be by name, time, or size)
     57 4. How names are to be sorted (directories first, then by extension, etc.)
     58 5. How to get help (the <F1> key), and an abridged list of available commands
     59 6. A listing of files, including "../" (it will list the parent directory).
     60 
     61 If you have syntax highlighting enabled, the different parts are highlighted
     62 so as to make it easier to spot them.
     63 
     64 You can use Normal mode Vim commands to move around in the text.  For example,
     65 move the cursor atop a file and press <Enter>; you will then be editing that
     66 file.  To go back to the browser use ":edit ." again, or use ":Explore".
     67 CTRL-O also works.
     68 
     69 Try using <Enter> while the cursor is atop a directory name.  The result is
     70 that the file browser moves into that directory and displays the items found
     71 there.  Pressing <Enter> on the first directory "../" moves you one level
     72 higher.  Pressing "-" does the same thing, without the need to move to the
     73 "../" item first.
     74 
     75 You can press <F1> to get help on the things you can do in the netrw file
     76 browser.  This is what you get:
     77 >
     78  QUICK HELP						netrw-quickhelp
     79                        (Use ctrl-] to select a topic)
     80 	Intro to Browsing...............................netrw-intro-browse
     81 	  Quick Reference: Maps.........................netrw-quickmap
     82 	  Quick Reference: Commands.....................netrw-browse-cmds
     83 <
     84 The <F1> key thus brings you to a netrw directory browsing contents help page.
     85 It's a regular help page; use the usual |CTRL-]| to jump to tagged help items
     86 and |CTRL-O| to jump back.  So, if you CTRL-] on |netrw-quickmap| you will
     87 jump to this:
     88 >
     89 				netrw-quickmap  netrw-quickmaps
     90  QUICK REFERENCE: MAPS				netrw-browse-maps
     91 
     92 	  ---			-----------------			----
     93 	  Map			Quick Explanation			Link
     94 	  ---			-----------------			----
     95 	 <F1>	Causes Netrw to issue help
     96 	 <cr>	Netrw will enter the directory or read the file      netrw-cr
     97 	 <del>	Netrw will attempt to remove the file/directory      netrw-del
     98 <	 (etc.)
     99 
    100 To select files for display and editing (with the cursor atop a filename):
    101 >
    102 	   o	Enter the file/directory under the cursor in a new   netrw-o
    103 		browser window.  A horizontal split is used.
    104 	   O	Obtain a file specified by cursor                    netrw-O
    105 	   p	Preview the file                                     netrw-p
    106 	   P	Browse in the previously used window                 netrw-P
    107 	   v	Enter the file/directory under the cursor in a new   netrw-v
    108 		browser window.  A vertical split is used.
    109 <
    110 The following normal-mode commands may be used to control the browser display:
    111 >
    112 	   i	Cycle between thin, long, wide, and tree listings    netrw-i
    113 	   r	Reverse sorting order                                netrw-r
    114 	   s	Select sorting style: by name, time, or file size    netrw-s
    115 <
    116 As a sampling of extra normal-mode commands:
    117 >
    118 	   cd	Make browsing directory the current directory        netrw-cd
    119 	   D	Attempt to remove the file(s)/directory(ies)         netrw-D
    120 	   gb	Go to previous bookmarked directory                  netrw-gb
    121 	   mb	Bookmark current directory                           netrw-mb
    122 	   R	Rename the designated file(s)/directory(ies)         netrw-R
    123 <
    124 One may also use command mode; again, just a sampling:
    125 >
    126      :Explore[!]  [dir] Explore directory of current file......netrw-explore
    127      :Hexplore[!] [dir] Horizontal Split & Explore.............netrw-explore
    128 <
    129 The netrw browser is not limited to just your local machine; one may use URLs
    130 such as: >
    131 
    132 	:Explore ftp://somehost/path/to/dir/
    133 	:e scp://somehost/path/to/dir/
    134 <
    135 	Note: The trailing "/" is important.
    136 
    137 See |netrw-browse| for more.
    138 
    139 ==============================================================================
    140 *22.2*	The current directory
    141 
    142 Just like the shell, Vim has the concept of a current directory.  Suppose you
    143 are in your home directory and want to edit several files in a directory
    144 "VeryLongFileName".  You could do: >
    145 
    146 	:edit VeryLongFileName/file1.txt
    147 	:edit VeryLongFileName/file2.txt
    148 	:edit VeryLongFileName/file3.txt
    149 
    150 To avoid much of the typing, do this: >
    151 
    152 	:cd VeryLongFileName
    153 	:edit file1.txt
    154 	:edit file2.txt
    155 	:edit file3.txt
    156 
    157 The ":cd" command changes the current directory.  You can see what the current
    158 directory is with the ":pwd" command: >
    159 
    160 	:pwd
    161 	/home/Bram/VeryLongFileName
    162 
    163 Vim remembers the last directory that you used.  Use "cd -" to go back to it.
    164 Example: >
    165 
    166 	:pwd
    167 	/home/Bram/VeryLongFileName
    168 	:cd /etc
    169 	:pwd
    170 	/etc
    171 	:cd -
    172 	:pwd
    173 	/home/Bram/VeryLongFileName
    174 	:cd -
    175 	:pwd
    176 	/etc
    177 
    178 
    179 WINDOW LOCAL DIRECTORY
    180 
    181 When you split a window, both windows use the same current directory.  When
    182 you want to edit a number of files somewhere else in the new window, you can
    183 make it use a different directory, without changing the current directory in
    184 the other window.  This is called a local directory. >
    185 
    186 	:pwd
    187 	/home/Bram/VeryLongFileName
    188 	:split
    189 	:lcd /etc
    190 	:pwd
    191 	/etc
    192 	CTRL-W w
    193 	:pwd
    194 	/home/Bram/VeryLongFileName
    195 
    196 So long as no `:lcd` command has been used, all windows share the same current
    197 directory.  Doing a `:cd` command in one window will also change the current
    198 directory of the other window.
    199    For a window where `:lcd` has been used a different current directory is
    200 remembered.  Using `:cd` or `:lcd` in other windows will not change it.
    201    When using a `:cd` command in a window that uses a different current
    202 directory, it will go back to using the shared directory.
    203 
    204 
    205 TAB LOCAL DIRECTORY
    206 
    207 When you open a new tab page, it uses the directory of the window in the
    208 previous tab page from which the new tab page was opened.  You can change the
    209 directory of the current tab page using the `:tcd` command.  All the windows
    210 in a tab page share this directory except for windows with a window-local
    211 directory.  Any new windows opened in this tab page will use this directory as
    212 the current working directory.  Using a `:cd` command in a tab page will not
    213 change the working directory of tab pages which have a tab local directory.
    214 When the global working directory is changed using the `:cd` command in a tab
    215 page, it will also change the current tab page working directory.
    216 
    217 
    218 ==============================================================================
    219 *22.3*	Finding a file
    220 
    221 You are editing a C program that contains this line:
    222 
    223 	#include "inits.h" ~
    224 
    225 You want to see what is in that "inits.h" file.  Move the cursor on the name
    226 of the file and type: >
    227 
    228 	gf
    229 
    230 Vim will find the file and edit it.
    231    What if the file is not in the current directory?  Vim will use the 'path'
    232 option to find the file.  This option is a list of directory names where to
    233 look for your file.
    234    Suppose you have your include files located in "c:/prog/include".  This
    235 command will add it to the 'path' option: >
    236 
    237 	:set path+=c:/prog/include
    238 
    239 This directory is an absolute path.  No matter where you are, it will be the
    240 same place.  What if you have located files in a subdirectory, below where the
    241 file is?  Then you can specify a relative path name.  This starts with a dot:
    242 >
    243 	:set path+=./proto
    244 
    245 This tells Vim to look in the directory "proto", below the directory where the
    246 file in which you use "gf" is.  Thus using "gf" on "inits.h" will make Vim
    247 look for "proto/inits.h", starting in the directory of the file.
    248    Without the "./", thus "proto", Vim would look in the "proto" directory
    249 below the current directory.  And the current directory might not be where the
    250 file that you are editing is located.
    251 
    252 The 'path' option allows specifying the directories where to search for files
    253 in many more ways.  See the help on the 'path' option.
    254    The 'isfname' option is used to decide which characters are included in the
    255 file name, and which ones are not (e.g., the " character in the example
    256 above).
    257 
    258 When you know the file name, but it's not to be found in the file, you can
    259 type it: >
    260 
    261 	:find inits.h
    262 
    263 Vim will then use the 'path' option to try and locate the file.  This is the
    264 same as the ":edit" command, except for the use of 'path'.
    265 
    266 To open the found file in a new window use CTRL-W f instead of "gf", or use
    267 ":sfind" instead of ":find".
    268 
    269 
    270 A nice way to directly start Vim to edit a file somewhere in the 'path': >
    271 
    272 	vim "+find stdio.h"
    273 
    274 This finds the file "stdio.h" in your value of 'path'.  The quotes are
    275 necessary to have one argument |-+c|.
    276 
    277 ==============================================================================
    278 *22.4*	The buffer list
    279 
    280 The Vim editor uses the term buffer to describe a file being edited.
    281 Actually, a buffer is a copy of the file that you edit.  When you finish
    282 changing the buffer, you write the contents of the buffer to the file.
    283 Buffers not only contain file contents, but also all the marks, settings, and
    284 other stuff that goes with it.
    285 
    286 
    287 HIDDEN BUFFERS
    288 
    289 Suppose you are editing the file one.txt and need to edit the file two.txt.
    290 You could simply use ":edit two.txt", but since you made changes to one.txt
    291 that won't work.  You also don't want to write one.txt yet.  Vim has a
    292 solution for you: >
    293 
    294 	:hide edit two.txt
    295 
    296 The buffer "one.txt" disappears from the screen, but Vim still knows that you
    297 are editing this buffer, so it keeps the modified text.  This is called a
    298 hidden buffer: The buffer contains text, but you can't see it.
    299    The argument of ":hide" is another command.  ":hide" makes that command
    300 behave as if the 'hidden' option was set.  You could also set this option
    301 yourself.  The effect is that when any buffer is abandoned, it becomes hidden.
    302    Be careful!  When you have hidden buffers with changes, don't exit Vim
    303 without making sure you have saved all the buffers.
    304 
    305 
    306 INACTIVE BUFFERS
    307 
    308 When a buffer has been used once, Vim remembers some information about it.
    309 When it is not displayed in a window and it is not hidden, it is still in the
    310 buffer list.  This is called an inactive buffer.  Overview:
    311 
    312 	Active		Appears in a window, text loaded.
    313 	Hidden		Not in a window, text loaded.
    314 	Inactive	Not in a window, no text loaded.
    315 
    316 The inactive buffers are remembered, because Vim keeps information about them,
    317 like marks.  And remembering the file name is useful too, so that you can see
    318 which files you have edited.  And edit them again.
    319 
    320 
    321 LISTING BUFFERS
    322 
    323 View the buffer list with this command: >
    324 
    325 	:buffers
    326 
    327 A command which does the same, is not so obvious to list buffers, but is much
    328 shorter to type: >
    329 
    330 	:ls
    331 
    332 The output could look like this:
    333 
    334   1 #h   "help.txt"			line 62 ~
    335   2 %a + "usr_21.txt"			line 1 ~
    336   3      "usr_toc.txt"			line 1 ~
    337 
    338 The first column contains the buffer number.  You can use this to edit the
    339 buffer without having to type the name, see below.
    340    After the buffer number come the flags.  Then the name of the file
    341 and the line number where the cursor was the last time.
    342    The flags that can appear are these (from left to right):
    343 
    344 	u	Buffer is unlisted |unlisted-buffer|.
    345 	 %	Current buffer.
    346 	 #	Alternate buffer.
    347 	  a	Buffer is loaded and displayed.
    348 	  h	Buffer is loaded but hidden.
    349 	   =	Buffer is read-only.
    350 	   -	Buffer is not modifiable, the 'modifiable' option is off.
    351 	    +	Buffer has been modified.
    352 
    353 
    354 EDITING A BUFFER
    355 
    356 You can edit a buffer by its number.  That avoids having to type the file
    357 name: >
    358 
    359 	:buffer 2
    360 
    361 But the only way to know the number is by looking in the buffer list.  You can
    362 use the name, or part of it, instead: >
    363 
    364 	:buffer help
    365 
    366 Vim will find the best match for the name you type.  If there is only one
    367 buffer that matches the name, it will be used.  In this case "help.txt".
    368    To open a buffer in a new window: >
    369 
    370 	:sbuffer 3
    371 
    372 This works with a name as well.
    373 
    374 
    375 USING THE BUFFER LIST
    376 
    377 You can move around in the buffer list with these commands:
    378 
    379 	:bnext		go to next buffer
    380 	:bprevious	go to previous buffer
    381 	:bfirst		go to the first buffer
    382 	:blast		go to the last buffer
    383 
    384 To remove a buffer from the list, use this command: >
    385 
    386 	:bdelete 3
    387 
    388 Again, this also works with a name.
    389    If you delete a buffer that was active (visible in a window), that window
    390 will be closed.  If you delete the current buffer, the current window will be
    391 closed.  If it was the last window, Vim will find another buffer to edit.  You
    392 can't be editing nothing!
    393 
    394 	Note: Even after removing the buffer with ":bdelete" Vim still
    395 	remembers it.  It's actually made "unlisted", it no longer appears in
    396 	the list from ":buffers".  The ":buffers!" command will list unlisted
    397 	buffers (yes, Vim can do the impossible).  To really make Vim forget
    398 	about a buffer, use ":bwipe".  Also see the 'buflisted' option.
    399 
    400 ==============================================================================
    401 
    402 Next chapter: |usr_23.txt|  Editing other files
    403 
    404 Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: