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: