1*editing.txt* For Vim version 8.2. Last change: 2020 May 12 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Editing files *edit-files* 8 91. Introduction |edit-intro| 102. Editing a file |edit-a-file| 113. The argument list |argument-list| 124. Writing |writing| 135. Writing and quitting |write-quit| 146. Dialogs |edit-dialogs| 157. The current directory |current-directory| 168. Editing binary files |edit-binary| 179. Encryption |encryption| 1810. Timestamps |timestamps| 1911. File Searching |file-searching| 20 21============================================================================== 221. Introduction *edit-intro* 23 24Editing a file with Vim means: 25 261. reading the file into a buffer 272. changing the buffer with editor commands 283. writing the buffer into a file 29 30 *current-file* 31As long as you don't write the buffer, the original file remains unchanged. 32If you start editing a file (read a file into the buffer), the file name is 33remembered as the "current file name". This is also known as the name of the 34current buffer. It can be used with "%" on the command line |:_%|. 35 36 *alternate-file* 37If there already was a current file name, then that one becomes the alternate 38file name. It can be used with "#" on the command line |:_#| and you can use 39the |CTRL-^| command to toggle between the current and the alternate file. 40However, the alternate file name is not changed when |:keepalt| is used. 41An alternate file name is remembered for each window. 42 43 *:keepalt* *:keepa* 44:keepalt {cmd} Execute {cmd} while keeping the current alternate file 45 name. Note that commands invoked indirectly (e.g., 46 with a function) may still set the alternate file 47 name. 48 49All file names are remembered in the buffer list. When you enter a file name, 50for editing (e.g., with ":e filename") or writing (e.g., with ":w filename"), 51the file name is added to the list. You can use the buffer list to remember 52which files you edited and to quickly switch from one file to another (e.g., 53to copy text) with the |CTRL-^| command. First type the number of the file 54and then hit CTRL-^. 55 56 57CTRL-G or *CTRL-G* *:f* *:fi* *:file* 58:f[ile] Prints the current file name (as typed, unless ":cd" 59 was used), the cursor position (unless the 'ruler' 60 option is set), and the file status (readonly, 61 modified, read errors, new file). See the 'shortmess' 62 option about how to make this message shorter. 63 64:f[ile]! like |:file|, but don't truncate the name even when 65 'shortmess' indicates this. 66 67{count}CTRL-G Like CTRL-G, but prints the current file name with 68 full path. If the count is higher than 1 the current 69 buffer number is also given. 70 71 *g_CTRL-G* *word-count* *byte-count* 72g CTRL-G Prints the current position of the cursor in five 73 ways: Column, Line, Word, Character and Byte. If the 74 number of Characters and Bytes is the same then the 75 Character position is omitted. 76 If there are characters in the line that take more 77 than one position on the screen (<Tab> or special 78 character), both the "real" column and the screen 79 column are shown, separated with a dash. 80 Also see the 'ruler' option and the |wordcount()| 81 function. 82 83 *v_g_CTRL-G* 84{Visual}g CTRL-G Similar to "g CTRL-G", but Word, Character, Line, and 85 Byte counts for the visually selected region are 86 displayed. 87 In Blockwise mode, Column count is also shown. (For 88 {Visual} see |Visual-mode|.) 89 90 *:file_f* 91:f[ile][!] {name} Sets the current file name to {name}. The optional ! 92 avoids truncating the message, as with |:file|. 93 If the buffer did have a name, that name becomes the 94 |alternate-file| name. An unlisted buffer is created 95 to hold the old name. 96 *:0file* 97:0f[ile][!] Remove the name of the current buffer. The optional ! 98 avoids truncating the message, as with |:file|. 99 100:buffers 101:files 102:ls List all the currently known file names. See 103 |windows.txt| |:files| |:buffers| |:ls|. 104 105Vim will remember the full path name of a file name that you enter. In most 106cases when the file name is displayed only the name you typed is shown, but 107the full path name is being used if you used the ":cd" command |:cd|. 108 109 *home-replace* 110If the environment variable $HOME is set, and the file name starts with that 111string, it is often displayed with HOME replaced with "~". This was done to 112keep file names short. When reading or writing files the full name is still 113used, the "~" is only used when displaying file names. When replacing the 114file name would result in just "~", "~/" is used instead (to avoid confusion 115between options set to $HOME with 'backupext' set to "~"). 116 117When writing the buffer, the default is to use the current file name. Thus 118when you give the "ZZ" or ":wq" command, the original file will be 119overwritten. If you do not want this, the buffer can be written into another 120file by giving a file name argument to the ":write" command. For example: > 121 122 vim testfile 123 [change the buffer with editor commands] 124 :w newfile 125 :q 126 127This will create a file "newfile", that is a modified copy of "testfile". 128The file "testfile" will remain unchanged. Anyway, if the 'backup' option is 129set, Vim renames or copies the original file before it will be overwritten. 130You can use this file if you discover that you need the original file. See 131also the 'patchmode' option. The name of the backup file is normally the same 132as the original file with 'backupext' appended. The default "~" is a bit 133strange to avoid accidentally overwriting existing files. If you prefer ".bak" 134change the 'backupext' option. Extra dots are replaced with '_' on MS-Windows 135machines, when Vim has detected that an MS-DOS-like filesystem is being used 136(e.g., messydos or crossdos) or when the 'shortname' option is on. The 137backup file can be placed in another directory by setting 'backupdir'. 138 139 *auto-shortname* 140Technical: On the Amiga you can use 30 characters for a file name. But on an 141 MS-DOS-compatible filesystem only 8 plus 3 characters are 142 available. Vim tries to detect the type of filesystem when it is 143 creating the .swp file. If an MS-DOS-like filesystem is suspected, 144 a flag is set that has the same effect as setting the 'shortname' 145 option. This flag will be reset as soon as you start editing a 146 new file. The flag will be used when making the file name for the 147 ".swp" and ".~" files for the current file. But when you are 148 editing a file in a normal filesystem and write to an MS-DOS-like 149 filesystem the flag will not have been set. In that case the 150 creation of the ".~" file may fail and you will get an error 151 message. Use the 'shortname' option in this case. 152 153When you started editing without giving a file name, "No File" is displayed in 154messages. If the ":write" command is used with a file name argument, the file 155name for the current file is set to that file name. This only happens when 156the 'F' flag is included in 'cpoptions' (by default it is included) |cpo-F|. 157This is useful when entering text in an empty buffer and then writing it to a 158file. If 'cpoptions' contains the 'f' flag (by default it is NOT included) 159|cpo-f| the file name is set for the ":read file" command. This is useful 160when starting Vim without an argument and then doing ":read file" to start 161editing a file. 162When the file name was set and 'filetype' is empty the filetype detection 163autocommands will be triggered. 164 *not-edited* 165Because the file name was set without really starting to edit that file, you 166are protected from overwriting that file. This is done by setting the 167"notedited" flag. You can see if this flag is set with the CTRL-G or ":file" 168command. It will include "[Not edited]" when the "notedited" flag is set. 169When writing the buffer to the current file name (with ":w!"), the "notedited" 170flag is reset. 171 172 *abandon* 173Vim remembers whether you have changed the buffer. You are protected from 174losing the changes you made. If you try to quit without writing, or want to 175start editing another file, Vim will refuse this. In order to overrule this 176protection, add a '!' to the command. The changes will then be lost. For 177example: ":q" will not work if the buffer was changed, but ":q!" will. To see 178whether the buffer was changed use the "CTRL-G" command. The message includes 179the string "[Modified]" if the buffer has been changed, or "+" if the 'm' flag 180is in 'shortmess'. 181 182If you want to automatically save the changes without asking, switch on the 183'autowriteall' option. 'autowrite' is the associated Vi-compatible option 184that does not work for all commands. 185 186If you want to keep the changed buffer without saving it, switch on the 187'hidden' option. See |hidden-buffer|. Some commands work like this even when 188'hidden' is not set, check the help for the command. 189 190============================================================================== 1912. Editing a file *edit-a-file* 192 193 *:e* *:edit* *reload* 194:e[dit] [++opt] [+cmd] Edit the current file. This is useful to re-edit the 195 current file, when it has been changed outside of Vim. 196 This fails when changes have been made to the current 197 buffer and 'autowriteall' isn't set or the file can't 198 be written. 199 Also see |++opt| and |+cmd|. 200 201 *:edit!* *discard* 202:e[dit]! [++opt] [+cmd] 203 Edit the current file always. Discard any changes to 204 the current buffer. This is useful if you want to 205 start all over again. 206 Also see |++opt| and |+cmd|. 207 208 *:edit_f* 209:e[dit] [++opt] [+cmd] {file} 210 Edit {file}. 211 This fails when changes have been made to the current 212 buffer, unless 'hidden' is set or 'autowriteall' is 213 set and the file can be written. 214 Also see |++opt| and |+cmd|. 215 216 *:edit!_f* 217:e[dit]! [++opt] [+cmd] {file} 218 Edit {file} always. Discard any changes to the 219 current buffer. 220 Also see |++opt| and |+cmd|. 221 222:e[dit] [++opt] [+cmd] #[count] 223 Edit the [count]th buffer (as shown by |:files|). 224 This command does the same as [count] CTRL-^. But ":e 225 #" doesn't work if the alternate buffer doesn't have a 226 file name, while CTRL-^ still works then. 227 Also see |++opt| and |+cmd|. 228 229 *:ene* *:enew* 230:ene[w] Edit a new, unnamed buffer. This fails when changes 231 have been made to the current buffer, unless 'hidden' 232 is set or 'autowriteall' is set and the file can be 233 written. 234 If 'fileformats' is not empty, the first format given 235 will be used for the new buffer. If 'fileformats' is 236 empty, the 'fileformat' of the current buffer is used. 237 238 *:ene!* *:enew!* 239:ene[w]! Edit a new, unnamed buffer. Discard any changes to 240 the current buffer. 241 Set 'fileformat' like |:enew|. 242 243 *:fin* *:find* 244:fin[d][!] [++opt] [+cmd] {file} 245 Find {file} in 'path' and then |:edit| it. 246 {not available when the |+file_in_path| feature was 247 disabled at compile time} 248 249:{count}fin[d][!] [++opt] [+cmd] {file} 250 Just like ":find", but use the {count} match in 251 'path'. Thus ":2find file" will find the second 252 "file" found in 'path'. When there are fewer matches 253 for the file in 'path' than asked for, you get an 254 error message. 255 256 *:ex* 257:ex [++opt] [+cmd] [file] 258 Same as |:edit|. 259 260 *:vi* *:visual* 261:vi[sual][!] [++opt] [+cmd] [file] 262 When used in Ex mode: Leave |Ex-mode|, go back to 263 Normal mode. Otherwise same as |:edit|. 264 265 *:vie* *:view* 266:vie[w][!] [++opt] [+cmd] file 267 When used in Ex mode: Leave |Ex-mode|, go back to 268 Normal mode. Otherwise same as |:edit|, but set 269 'readonly' option for this buffer. 270 271 *CTRL-^* *CTRL-6* 272CTRL-^ Edit the alternate file. Mostly the alternate file is 273 the previously edited file. This is a quick way to 274 toggle between two files. It is equivalent to ":e #", 275 except that it also works when there is no file name. 276 277 If the 'autowrite' or 'autowriteall' option is on and 278 the buffer was changed, write it. 279 Mostly the ^ character is positioned on the 6 key, 280 pressing CTRL and 6 then gets you what we call CTRL-^. 281 But on some non-US keyboards CTRL-^ is produced in 282 another way. 283 284{count}CTRL-^ Edit [count]th file in the buffer list (equivalent to 285 ":e #[count]"). This is a quick way to switch between 286 files. 287 See |CTRL-^| above for further details. 288 289[count]]f *]f* *[f* 290[count][f Same as "gf". Deprecated. 291 292 *gf* *E446* *E447* 293[count]gf Edit the file whose name is under or after the cursor. 294 Mnemonic: "goto file". 295 Uses the 'isfname' option to find out which characters 296 are supposed to be in a file name. Trailing 297 punctuation characters ".,:;!" are ignored. Escaped 298 spaces "\ " are reduced to a single space. 299 Uses the 'path' option as a list of directory names to 300 look for the file. See the 'path' option for details 301 about relative directories and wildcards. 302 Uses the 'suffixesadd' option to check for file names 303 with a suffix added. 304 If the file can't be found, 'includeexpr' is used to 305 modify the name and another attempt is done. 306 If a [count] is given, the count'th file that is found 307 in the 'path' is edited. 308 This command fails if Vim refuses to |abandon| the 309 current file. 310 If you want to edit the file in a new window use 311 |CTRL-W_CTRL-F|. 312 If you do want to edit a new file, use: > 313 :e <cfile> 314< To make gf always work like that: > 315 :map gf :e <cfile><CR> 316< If the name is a hypertext link, that looks like 317 "type://machine/path", you need the |netrw| plugin. 318 For Unix the '~' character is expanded, like in 319 "~user/file". Environment variables are expanded too 320 |expand-env|. 321 {not available when the |+file_in_path| feature was 322 disabled at compile time} 323 324 *v_gf* 325{Visual}[count]gf Same as "gf", but the highlighted text is used as the 326 name of the file to edit. 'isfname' is ignored. 327 Leading blanks are skipped, otherwise all blanks and 328 special characters are included in the file name. 329 (For {Visual} see |Visual-mode|.) 330 331 *gF* 332[count]gF Same as "gf", except if a number follows the file 333 name, then the cursor is positioned on that line in 334 the file. 335 The file name and the number must be separated by a 336 non-filename (see 'isfname') and non-numeric 337 character. " line " is also recognized, like it is 338 used in the output of `:verbose command UserCmd` 339 White space between the filename, the separator and 340 the number are ignored. 341 Examples: 342 eval.c:10 ~ 343 eval.c @ 20 ~ 344 eval.c (30) ~ 345 eval.c 40 ~ 346 347 *v_gF* 348{Visual}[count]gF Same as "v_gf". 349 350These commands are used to start editing a single file. This means that the 351file is read into the buffer and the current file name is set. The file that 352is opened depends on the current directory, see |:cd|. 353 354See |read-messages| for an explanation of the message that is given after the 355file has been read. 356 357You can use the ":e!" command if you messed up the buffer and want to start 358all over again. The ":e" command is only useful if you have changed the 359current file name. 360 361 *:filename* *{file}* 362Besides the things mentioned here, more special items for where a filename is 363expected are mentioned at |cmdline-special|. 364 365Note for systems other than Unix: When using a command that accepts a single 366file name (like ":edit file") spaces in the file name are allowed, but 367trailing spaces are ignored. This is useful on systems that regularly embed 368spaces in file names (like MS-Windows and the Amiga). Example: The command 369":e Long File Name " will edit the file "Long File Name". When using a 370command that accepts more than one file name (like ":next file1 file2") 371embedded spaces must be escaped with a backslash. 372 373 *wildcard* *wildcards* 374Wildcards in {file} are expanded, but as with file completion, 'wildignore' 375and 'suffixes' apply. Which wildcards are supported depends on the system. 376These are the common ones: 377 ? matches one character 378 * matches anything, including nothing 379 ** matches anything, including nothing, recurses into directories 380 [abc] match 'a', 'b' or 'c' 381 382To avoid the special meaning of the wildcards prepend a backslash. However, 383on MS-Windows the backslash is a path separator and "path\[abc]" is still seen 384as a wildcard when "[" is in the 'isfname' option. A simple way to avoid this 385is to use "path\[[]abc]", this matches the file "path\[abc]". 386 387 *starstar-wildcard* 388Expanding "**" is possible on Unix, Win32, Mac OS/X and a few other systems. 389This allows searching a directory tree. This goes up to 100 directories deep. 390Note there are some commands where this works slightly differently, see 391|file-searching|. 392Example: > 393 :n **/*.txt 394Finds files: 395 aaa.txt ~ 396 subdir/bbb.txt ~ 397 a/b/c/d/ccc.txt ~ 398When non-wildcard characters are used right before or after "**" these are 399only matched in the top directory. They are not used for directories further 400down in the tree. For example: > 401 :n /usr/inc**/types.h 402Finds files: 403 /usr/include/types.h ~ 404 /usr/include/sys/types.h ~ 405 /usr/inc/old/types.h ~ 406Note that the path with "/sys" is included because it does not need to match 407"/inc". Thus it's like matching "/usr/inc*/*/*...", not 408"/usr/inc*/inc*/inc*". 409 410 *backtick-expansion* *`-expansion* 411On Unix and a few other systems you can also use backticks for the file name 412argument, for example: > 413 :next `find . -name ver\\*.c -print` 414 :view `ls -t *.patch \| head -n1` 415Vim will run the command in backticks using the 'shell' and use the standard 416output as argument for the given Vim command (error messages from the shell 417command will be discarded). 418To see what shell command Vim is running, set the 'verbose' option to 4. When 419the shell command returns a non-zero exit code, an error message will be 420displayed and the Vim command will be aborted. To avoid this make the shell 421always return zero like so: > 422 :next `find . -name ver\\*.c -print \|\| true` 423 424The backslashes before the star are required to prevent the shell from 425expanding "ver*.c" prior to execution of the find program. The backslash 426before the shell pipe symbol "|" prevents Vim from parsing it as command 427termination. 428This also works for most other systems, with the restriction that the 429backticks must be around the whole item. It is not possible to have text 430directly before the first or just after the last backtick. 431 432 *`=* 433You can have the backticks expanded as a Vim expression, instead of as an 434external command, by putting an equal sign right after the first backtick, 435e.g.: > 436 :e `=tempname()` 437The expression can contain just about anything, thus this can also be used to 438avoid the special meaning of '"', '|', '%' and '#'. However, 'wildignore' 439does apply like to other wildcards. 440 441Environment variables in the expression are expanded when evaluating the 442expression, thus this works: > 443 :e `=$HOME . '/.vimrc'` 444This does not work, $HOME is inside a string and used literally: > 445 :e `='$HOME' . '/.vimrc'` 446 447If the expression returns a string then names are to be separated with line 448breaks. When the result is a |List| then each item is used as a name. Line 449breaks also separate names. 450Note that such expressions are only supported in places where a filename is 451expected as an argument to an Ex-command. 452 453 *++opt* *[++opt]* 454The [++opt] argument can be used to force the value of 'fileformat', 455'fileencoding' or 'binary' to a value for one command, and to specify the 456behavior for bad characters. The form is: > 457 ++{optname} 458Or: > 459 ++{optname}={value} 460 461Where {optname} is one of: *++ff* *++enc* *++bin* *++nobin* *++edit* 462 ff or fileformat overrides 'fileformat' 463 enc or encoding overrides 'fileencoding' 464 bin or binary sets 'binary' 465 nobin or nobinary resets 'binary' 466 bad specifies behavior for bad characters 467 edit for |:read| only: keep option values as if editing 468 a file 469 470{value} cannot contain white space. It can be any valid value for these 471options. Examples: > 472 :e ++ff=unix 473This edits the same file again with 'fileformat' set to "unix". > 474 475 :w ++enc=latin1 newfile 476This writes the current buffer to "newfile" in latin1 format. 477 478The message given when writing a file will show "[converted]" when 479'fileencoding' or the value specified with ++enc differs from 'encoding'. 480 481There may be several ++opt arguments, separated by white space. They must all 482appear before any |+cmd| argument. 483 484 *++bad* 485The argument of "++bad=" specifies what happens with characters that can't be 486converted and illegal bytes. It can be one of three things: 487 ++bad=X A single-byte character that replaces each bad character. 488 ++bad=keep Keep bad characters without conversion. Note that this may 489 result in illegal bytes in your text! 490 ++bad=drop Remove the bad characters. 491 492The default is like "++bad=?": Replace each bad character with a question 493mark. In some places an inverted question mark is used (0xBF). 494 495Note that not all commands use the ++bad argument, even though they do not 496give an error when you add it. E.g. |:write|. 497 498Note that when reading, the 'fileformat' and 'fileencoding' options will be 499set to the used format. When writing this doesn't happen, thus a next write 500will use the old value of the option. Same for the 'binary' option. 501 502 503 *+cmd* *[+cmd]* 504The [+cmd] argument can be used to position the cursor in the newly opened 505file, or execute any other command: 506 + Start at the last line. 507 +{num} Start at line {num}. 508 +/{pat} Start at first line containing {pat}. 509 +{command} Execute {command} after opening the new file. 510 {command} is any Ex command. 511To include a white space in the {pat} or {command}, precede it with a 512backslash. Double the number of backslashes. > 513 :edit +/The\ book file 514 :edit +/dir\ dirname\\ file 515 :edit +set\ dir=c:\\\\temp file 516Note that in the last example the number of backslashes is halved twice: Once 517for the "+cmd" argument and once for the ":set" command. 518 519 *file-formats* 520The 'fileformat' option sets the <EOL> style for a file: 521'fileformat' characters name ~ 522 "dos" <CR><NL> or <NL> DOS format *DOS-format* 523 "unix" <NL> Unix format *Unix-format* 524 "mac" <CR> Mac format *Mac-format* 525Previously 'textmode' was used. It is obsolete now. 526 527When reading a file, the mentioned characters are interpreted as the <EOL>. 528In DOS format (default for Win32), <CR><NL> and <NL> are both interpreted as 529the <EOL>. Note that when writing the file in DOS format, <CR> characters 530will be added for each single <NL>. Also see |file-read|. 531 532When writing a file, the mentioned characters are used for <EOL>. For DOS 533format <CR><NL> is used. Also see |DOS-format-write|. 534 535You can read a file in DOS format and write it in Unix format. This will 536replace all <CR><NL> pairs by <NL> (assuming 'fileformats' includes "dos"): > 537 :e file 538 :set fileformat=unix 539 :w 540If you read a file in Unix format and write with DOS format, all <NL> 541characters will be replaced with <CR><NL> (assuming 'fileformats' includes 542"unix"): > 543 :e file 544 :set fileformat=dos 545 :w 546 547If you start editing a new file and the 'fileformats' option is not empty 548(which is the default), Vim will try to detect whether the lines in the file 549are separated by the specified formats. When set to "unix,dos", Vim will 550check for lines with a single <NL> (as used on Unix and Amiga) or by a <CR> 551<NL> pair (MS-Windows). Only when ALL lines end in <CR><NL>, 'fileformat' is 552set to "dos", otherwise it is set to "unix". When 'fileformats' includes 553"mac", and no <NL> characters are found in the file, 'fileformat' is set to 554"mac". 555 556If the 'fileformat' option is set to "dos" on non-MS-Windows systems the 557message "[dos format]" is shown to remind you that something unusual is 558happening. On MS-Windows systems you get the message "[unix format]" if 559'fileformat' is set to "unix". On all systems but the Macintosh you get the 560message "[mac format]" if 'fileformat' is set to "mac". 561 562If the 'fileformats' option is empty and DOS format is used, but while reading 563a file some lines did not end in <CR><NL>, "[CR missing]" will be included in 564the file message. 565If the 'fileformats' option is empty and Mac format is used, but while reading 566a file a <NL> was found, "[NL missing]" will be included in the file message. 567 568If the new file does not exist, the 'fileformat' of the current buffer is used 569when 'fileformats' is empty. Otherwise the first format from 'fileformats' is 570used for the new file. 571 572Before editing binary, executable or Vim script files you should set the 573'binary' option. A simple way to do this is by starting Vim with the "-b" 574option. This will avoid the use of 'fileformat'. Without this you risk that 575single <NL> characters are unexpectedly replaced with <CR><NL>. 576 577You can encrypt files that are written by setting the 'key' option. This 578provides some security against others reading your files. |encryption| 579 580 581============================================================================== 5823. The argument list *argument-list* *arglist* 583 584If you give more than one file name when starting Vim, this list is remembered 585as the argument list. You can jump to each file in this list. 586 587Do not confuse this with the buffer list, which you can see with the 588|:buffers| command. The argument list was already present in Vi, the buffer 589list is new in Vim. Every file name in the argument list will also be present 590in the buffer list (unless it was deleted with |:bdel| or |:bwipe|). But it's 591common that names in the buffer list are not in the argument list. 592 593This subject is introduced in section |07.2| of the user manual. 594 595There is one global argument list, which is used for all windows by default. 596It is possible to create a new argument list local to a window, see 597|:arglocal|. 598 599You can use the argument list with the following commands, and with the 600expression functions |argc()| and |argv()|. These all work on the argument 601list of the current window. 602 603 *:ar* *:arg* *:args* 604:ar[gs] Print the argument list, with the current file in 605 square brackets. 606 607:ar[gs] [++opt] [+cmd] {arglist} *:args_f* 608 Define {arglist} as the new argument list and edit 609 the first one. This fails when changes have been made 610 and Vim does not want to |abandon| the current buffer. 611 Also see |++opt| and |+cmd|. 612 613:ar[gs]! [++opt] [+cmd] {arglist} *:args_f!* 614 Define {arglist} as the new argument list and edit 615 the first one. Discard any changes to the current 616 buffer. 617 Also see |++opt| and |+cmd|. 618 619:[count]arge[dit][!] [++opt] [+cmd] {name} .. *:arge* *:argedit* 620 Add {name}s to the argument list and edit it. 621 When {name} already exists in the argument list, this 622 entry is edited. 623 This is like using |:argadd| and then |:edit|. 624 Spaces in filenames have to be escaped with "\". 625 [count] is used like with |:argadd|. 626 If the current file cannot be |abandon|ed {name}s will 627 still be added to the argument list, but won't be 628 edited. No check for duplicates is done. 629 Also see |++opt| and |+cmd|. 630 631:[count]arga[dd] {name} .. *:arga* *:argadd* *E479* 632:[count]arga[dd] 633 Add the {name}s to the argument list. When {name} is 634 omitted add the current buffer name to the argument 635 list. 636 If [count] is omitted, the {name}s are added just 637 after the current entry in the argument list. 638 Otherwise they are added after the [count]'th file. 639 If the argument list is "a b c", and "b" is the 640 current argument, then these commands result in: 641 command new argument list ~ 642 :argadd x a b x c 643 :0argadd x x a b c 644 :1argadd x a x b c 645 :$argadd x a b c x 646 And after the last one: 647 :+2argadd y a b c x y 648 There is no check for duplicates, it is possible to 649 add a file to the argument list twice. 650 The currently edited file is not changed. 651 Note: you can also use this method: > 652 :args ## x 653< This will add the "x" item and sort the new list. 654 655:argd[elete] {pattern} .. *:argd* *:argdelete* *E480* 656 Delete files from the argument list that match the 657 {pattern}s. {pattern} is used like a file pattern, 658 see |file-pattern|. "%" can be used to delete the 659 current entry. 660 This command keeps the currently edited file, also 661 when it's deleted from the argument list. 662 Example: > 663 :argdel *.obj 664 665:[range]argd[elete] Delete the {range} files from the argument list. 666 Example: > 667 :10,$argdel 668< Deletes arguments 10 and further, keeping 1-9. > 669 :$argd 670< Deletes just the last one. > 671 :argd 672 :.argd 673< Deletes the current argument. > 674 :%argd 675< Removes all the files from the arglist. 676 When the last number in the range is too high, up to 677 the last argument is deleted. 678 679 *:argu* *:argument* 680:[count]argu[ment] [count] [++opt] [+cmd] 681 Edit file [count] in the argument list. When [count] 682 is omitted the current entry is used. This fails 683 when changes have been made and Vim does not want to 684 |abandon| the current buffer. 685 Also see |++opt| and |+cmd|. 686 687:[count]argu[ment]! [count] [++opt] [+cmd] 688 Edit file [count] in the argument list, discard any 689 changes to the current buffer. When [count] is 690 omitted the current entry is used. 691 Also see |++opt| and |+cmd|. 692 693:[count]n[ext] [++opt] [+cmd] *:n* *:ne* *:next* *E165* *E163* 694 Edit [count] next file. This fails when changes have 695 been made and Vim does not want to |abandon| the 696 current buffer. Also see |++opt| and |+cmd|. 697 698:[count]n[ext]! [++opt] [+cmd] 699 Edit [count] next file, discard any changes to the 700 buffer. Also see |++opt| and |+cmd|. 701 702:n[ext] [++opt] [+cmd] {arglist} *:next_f* 703 Same as |:args_f|. 704 705:n[ext]! [++opt] [+cmd] {arglist} 706 Same as |:args_f!|. 707 708:[count]N[ext] [count] [++opt] [+cmd] *:Next* *:N* *E164* 709 Edit [count] previous file in argument list. This 710 fails when changes have been made and Vim does not 711 want to |abandon| the current buffer. 712 Also see |++opt| and |+cmd|. 713 714:[count]N[ext]! [count] [++opt] [+cmd] 715 Edit [count] previous file in argument list. Discard 716 any changes to the buffer. Also see |++opt| and 717 |+cmd|. 718 719:[count]prev[ious] [count] [++opt] [+cmd] *:prev* *:previous* 720 Same as :Next. Also see |++opt| and |+cmd|. 721 722 *:rew* *:rewind* 723:rew[ind] [++opt] [+cmd] 724 Start editing the first file in the argument list. 725 This fails when changes have been made and Vim does 726 not want to |abandon| the current buffer. 727 Also see |++opt| and |+cmd|. 728 729:rew[ind]! [++opt] [+cmd] 730 Start editing the first file in the argument list. 731 Discard any changes to the buffer. Also see |++opt| 732 and |+cmd|. 733 734 *:fir* *:first* 735:fir[st][!] [++opt] [+cmd] 736 Other name for ":rewind". 737 738 *:la* *:last* 739:la[st] [++opt] [+cmd] 740 Start editing the last file in the argument list. 741 This fails when changes have been made and Vim does 742 not want to |abandon| the current buffer. 743 Also see |++opt| and |+cmd|. 744 745:la[st]! [++opt] [+cmd] 746 Start editing the last file in the argument list. 747 Discard any changes to the buffer. Also see |++opt| 748 and |+cmd|. 749 750 *:wn* *:wnext* 751:[count]wn[ext] [++opt] 752 Write current file and start editing the [count] 753 next file. Also see |++opt| and |+cmd|. 754 755:[count]wn[ext] [++opt] {file} 756 Write current file to {file} and start editing the 757 [count] next file, unless {file} already exists and 758 the 'writeany' option is off. Also see |++opt| and 759 |+cmd|. 760 761:[count]wn[ext]! [++opt] {file} 762 Write current file to {file} and start editing the 763 [count] next file. Also see |++opt| and |+cmd|. 764 765:[count]wN[ext][!] [++opt] [file] *:wN* *:wNext* 766:[count]wp[revious][!] [++opt] [file] *:wp* *:wprevious* 767 Same as :wnext, but go to previous file instead of 768 next. 769 770The [count] in the commands above defaults to one. For some commands it is 771possible to use two counts. The last one (rightmost one) is used. 772 773If no [+cmd] argument is present, the cursor is positioned at the last known 774cursor position for the file. If 'startofline' is set, the cursor will be 775positioned at the first non-blank in the line, otherwise the last know column 776is used. If there is no last known cursor position the cursor will be in the 777first line (the last line in Ex mode). 778 779 *{arglist}* 780The wildcards in the argument list are expanded and the file names are sorted. 781Thus you can use the command "vim *.c" to edit all the C files. From within 782Vim the command ":n *.c" does the same. 783 784White space is used to separate file names. Put a backslash before a space or 785tab to include it in a file name. E.g., to edit the single file "foo bar": > 786 :next foo\ bar 787 788On Unix and a few other systems you can also use backticks, for example: > 789 :next `find . -name \\*.c -print` 790The backslashes before the star are required to prevent "*.c" to be expanded 791by the shell before executing the find program. 792 793 *arglist-position* 794When there is an argument list you can see which file you are editing in the 795title of the window (if there is one and 'title' is on) and with the file 796message you get with the "CTRL-G" command. You will see something like 797 (file 4 of 11) 798If 'shortmess' contains 'f' it will be 799 (4 of 11) 800If you are not really editing the file at the current position in the argument 801list it will be 802 (file (4) of 11) 803This means that you are position 4 in the argument list, but not editing the 804fourth file in the argument list. This happens when you do ":e file". 805 806 807LOCAL ARGUMENT LIST 808 809 *:arglocal* 810:argl[ocal] Make a local copy of the global argument list. 811 Doesn't start editing another file. 812 813:argl[ocal][!] [++opt] [+cmd] {arglist} 814 Define a new argument list, which is local to the 815 current window. Works like |:args_f| otherwise. 816 817 *:argglobal* 818:argg[lobal] Use the global argument list for the current window. 819 Doesn't start editing another file. 820 821:argg[lobal][!] [++opt] [+cmd] {arglist} 822 Use the global argument list for the current window. 823 Define a new global argument list like |:args_f|. 824 All windows using the global argument list will see 825 this new list. 826 827There can be several argument lists. They can be shared between windows. 828When they are shared, changing the argument list in one window will also 829change it in the other window. 830 831When a window is split the new window inherits the argument list from the 832current window. The two windows then share this list, until one of them uses 833|:arglocal| or |:argglobal| to use another argument list. 834 835 836USING THE ARGUMENT LIST 837 838 *:argdo* 839:[range]argdo[!] {cmd} Execute {cmd} for each file in the argument list or 840 if [range] is specified only for arguments in that 841 range. It works like doing this: > 842 :rewind 843 :{cmd} 844 :next 845 :{cmd} 846 etc. 847< When the current file can't be |abandon|ed and the [!] 848 is not present, the command fails. 849 When an error is detected on one file, further files 850 in the argument list will not be visited. 851 The last file in the argument list (or where an error 852 occurred) becomes the current file. 853 {cmd} can contain '|' to concatenate several commands. 854 {cmd} must not change the argument list. 855 Note: While this command is executing, the Syntax 856 autocommand event is disabled by adding it to 857 'eventignore'. This considerably speeds up editing 858 each file. 859 Also see |:windo|, |:tabdo|, |:bufdo|, |:cdo|, |:ldo|, 860 |:cfdo| and |:lfdo| 861 862Example: > 863 :args *.c 864 :argdo set ff=unix | update 865This sets the 'fileformat' option to "unix" and writes the file if it is now 866changed. This is done for all *.c files. 867 868Example: > 869 :args *.[ch] 870 :argdo %s/\<my_foo\>/My_Foo/ge | update 871This changes the word "my_foo" to "My_Foo" in all *.c and *.h files. The "e" 872flag is used for the ":substitute" command to avoid an error for files where 873"my_foo" isn't used. ":update" writes the file only if changes were made. 874 875============================================================================== 8764. Writing *writing* *save-file* 877 878Note: When the 'write' option is off, you are not able to write any file. 879 880 *:w* *:write* 881 *E502* *E503* *E504* *E505* 882 *E512* *E514* *E667* *E796* *E949* 883:w[rite] [++opt] Write the whole buffer to the current file. This is 884 the normal way to save changes to a file. It fails 885 when the 'readonly' option is set or when there is 886 another reason why the file can't be written. 887 For ++opt see |++opt|, but only ++bin, ++nobin, ++ff 888 and ++enc are effective. 889 890:w[rite]! [++opt] Like ":write", but forcefully write when 'readonly' is 891 set or there is another reason why writing was 892 refused. 893 Note: This may change the permission and ownership of 894 the file and break (symbolic) links. Add the 'W' flag 895 to 'cpoptions' to avoid this. 896 897:[range]w[rite][!] [++opt] 898 Write the specified lines to the current file. This 899 is unusual, because the file will not contain all 900 lines in the buffer. 901 902 *:w_f* *:write_f* 903:[range]w[rite] [++opt] {file} 904 Write the specified lines to {file}, unless it 905 already exists and the 'writeany' option is off. 906 907 *:w!* 908:[range]w[rite]! [++opt] {file} 909 Write the specified lines to {file}. Overwrite an 910 existing file. 911 912 *:w_a* *:write_a* *E494* 913:[range]w[rite][!] [++opt] >> 914 Append the specified lines to the current file. 915 916:[range]w[rite][!] [++opt] >> {file} 917 Append the specified lines to {file}. '!' forces the 918 write even if file does not exist. 919 920 *:w_c* *:write_c* 921:[range]w[rite] [++opt] !{cmd} 922 Execute {cmd} with [range] lines as standard input 923 (note the space in front of the '!'). {cmd} is 924 executed like with ":!{cmd}", any '!' is replaced with 925 the previous command |:!|. 926 927The default [range] for the ":w" command is the whole buffer (1,$). If you 928write the whole buffer, it is no longer considered changed. When you 929write it to a different file with ":w somefile" it depends on the "+" flag in 930'cpoptions'. When included, the write command will reset the 'modified' flag, 931even though the buffer itself may still be different from its file. 932 933If a file name is given with ":w" it becomes the alternate file. This can be 934used, for example, when the write fails and you want to try again later with 935":w #". This can be switched off by removing the 'A' flag from the 936'cpoptions' option. 937 938Note that the 'fsync' option matters here. If it's set it may make writes 939slower (but safer). 940 941 *:sav* *:saveas* 942:sav[eas][!] [++opt] {file} 943 Save the current buffer under the name {file} and set 944 the filename of the current buffer to {file}. The 945 previous name is used for the alternate file name. 946 The [!] is needed to overwrite an existing file. 947 When 'filetype' is empty filetype detection is done 948 with the new name, before the file is written. 949 When the write was successful 'readonly' is reset. 950 951 *:up* *:update* 952:[range]up[date][!] [++opt] [>>] [file] 953 Like ":write", but only write when the buffer has been 954 modified. 955 956 957WRITING WITH MULTIPLE BUFFERS *buffer-write* 958 959 *:wa* *:wall* 960:wa[ll] Write all changed buffers. Buffers without a file 961 name cause an error message. Buffers which are 962 readonly are not written. 963 964:wa[ll]! Write all changed buffers, even the ones that are 965 readonly. Buffers without a file name are not 966 written and cause an error message. 967 968 969Vim will warn you if you try to overwrite a file that has been changed 970elsewhere. See |timestamp|. 971 972 *backup* *E207* *E506* *E507* *E508* *E509* *E510* 973If you write to an existing file (but do not append) while the 'backup', 974'writebackup' or 'patchmode' option is on, a backup of the original file is 975made. The file is either copied or renamed (see 'backupcopy'). After the 976file has been successfully written and when the 'writebackup' option is on and 977the 'backup' option is off, the backup file is deleted. When the 'patchmode' 978option is on the backup file may be renamed. 979 980 *backup-table* 981'backup' 'writebackup' action ~ 982 off off no backup made 983 off on backup current file, deleted afterwards (default) 984 on off delete old backup, backup current file 985 on on delete old backup, backup current file 986 987When the 'backupskip' pattern matches with the name of the file which is 988written, no backup file is made. The values of 'backup' and 'writebackup' are 989ignored then. 990 991When the 'backup' option is on, an old backup file (with the same name as the 992new backup file) will be deleted. If 'backup' is not set, but 'writebackup' 993is set, an existing backup file will not be deleted. The backup file that is 994made while the file is being written will have a different name. 995 996On some filesystems it's possible that in a crash you lose both the backup and 997the newly written file (it might be there but contain bogus data). In that 998case try recovery, because the swap file is synced to disk and might still be 999there. |:recover| 1000 1001The directories given with the 'backupdir' option are used to put the backup 1002file in. (default: same directory as the written file). 1003 1004Whether the backup is a new file, which is a copy of the original file, or the 1005original file renamed depends on the 'backupcopy' option. See there for an 1006explanation of when the copy is made and when the file is renamed. 1007 1008If the creation of a backup file fails, the write is not done. If you want 1009to write anyway add a '!' to the command. 1010 1011 *write-permissions* 1012When writing a new file the permissions are read-write. For unix the mask is 10130666 with additionally umask applied. When writing a file that was read Vim 1014will preserve the permissions, but clear the s-bit. 1015 1016 *write-readonly* 1017When the 'cpoptions' option contains 'W', Vim will refuse to overwrite a 1018readonly file. When 'W' is not present, ":w!" will overwrite a readonly file, 1019if the system allows it (the directory must be writable). 1020 1021 *write-fail* 1022If the writing of the new file fails, you have to be careful not to lose 1023your changes AND the original file. If there is no backup file and writing 1024the new file failed, you have already lost the original file! DON'T EXIT VIM 1025UNTIL YOU WRITE OUT THE FILE! If a backup was made, it is put back in place 1026of the original file (if possible). If you exit Vim, and lose the changes 1027you made, the original file will mostly still be there. If putting back the 1028original file fails, there will be an error message telling you that you 1029lost the original file. 1030 1031 *DOS-format-write* 1032If the 'fileformat' is "dos", <CR> <NL> is used for <EOL>. This is default 1033for Win32. On other systems the message "[dos format]" is shown to remind you 1034that an unusual <EOL> was used. 1035 *Unix-format-write* 1036If the 'fileformat' is "unix", <NL> is used for <EOL>. On Win32 the message 1037"[unix format]" is shown. 1038 *Mac-format-write* 1039If the 'fileformat' is "mac", <CR> is used for <EOL>. On non-Mac systems the 1040message "[mac format]" is shown. 1041 1042See also |file-formats| and the 'fileformat' and 'fileformats' options. 1043 1044 *ACL* 1045ACL stands for Access Control List. It is an advanced way to control access 1046rights for a file. It is used on new MS-Windows and Unix systems, but only 1047when the filesystem supports it. 1048 Vim attempts to preserve the ACL info when writing a file. The backup file 1049will get the ACL info of the original file. 1050 The ACL info is also used to check if a file is read-only (when opening the 1051file). 1052 1053 *read-only-share* 1054When MS-Windows shares a drive on the network it can be marked as read-only. 1055This means that even if the file read-only attribute is absent, and the ACL 1056settings on NT network shared drives allow writing to the file, you can still 1057not write to the file. Vim on Win32 platforms will detect read-only network 1058drives and will mark the file as read-only. You will not be able to override 1059it with |:write|. 1060 1061 *write-device* 1062When the file name is actually a device name, Vim will not make a backup (that 1063would be impossible). You need to use "!", since the device already exists. 1064Example for Unix: > 1065 :w! /dev/lpt0 1066and for MS-Windows: > 1067 :w! lpt0 1068For Unix a device is detected when the name doesn't refer to a normal file or 1069a directory. A fifo or named pipe also looks like a device to Vim. 1070For MS-Windows the device is detected by its name: 1071 AUX 1072 CON 1073 CLOCK$ 1074 NUL 1075 PRN 1076 COMn n=1,2,3... etc 1077 LPTn n=1,2,3... etc 1078The names can be in upper- or lowercase. 1079 1080============================================================================== 10815. Writing and quitting *write-quit* 1082 1083 *:q* *:quit* 1084:q[uit] Quit the current window. Quit Vim if this is the last 1085 |edit-window|. This fails when changes have been made 1086 and Vim refuses to |abandon| the current buffer, and 1087 when the last file in the argument list has not been 1088 edited. 1089 If there are other tab pages and quitting the last 1090 window in the current tab page the current tab page is 1091 closed |tab-page|. 1092 Triggers the |QuitPre| autocommand event. 1093 See |CTRL-W_q| for quitting another window. 1094 1095:conf[irm] q[uit] Quit, but give prompt when changes have been made, or 1096 the last file in the argument list has not been 1097 edited. See |:confirm| and 'confirm'. 1098 1099:q[uit]! Quit without writing, also when the current buffer has 1100 changes. The buffer is unloaded, also when it has 1101 'hidden' set. 1102 If this is the last window and there is a modified 1103 hidden buffer, the current buffer is abandoned and the 1104 first changed hidden buffer becomes the current 1105 buffer. 1106 Use ":qall!" to exit always. 1107 1108:cq[uit] Quit always, without writing, and return an error 1109 code. See |:cq|. Used for Manx's QuickFix mode (see 1110 |quickfix|). 1111 1112 *:wq* 1113:wq [++opt] Write the current file and close the window. If this 1114 was the last |edit-window| Vim quits. 1115 Writing fails when the file is read-only or the buffer 1116 does not have a name. Quitting fails when the last 1117 file in the argument list has not been edited. 1118 1119:wq! [++opt] Write the current file and close the window. If this 1120 was the last |edit-window| Vim quits. Writing fails 1121 when the current buffer does not have a name. 1122 1123:wq [++opt] {file} Write to {file} and close the window. If this was the 1124 last |edit-window| Vim quits. Quitting fails when the 1125 last file in the argument list has not been edited. 1126 1127:wq! [++opt] {file} Write to {file} and close the current window. Quit 1128 Vim if this was the last |edit-window|. 1129 1130:[range]wq[!] [++opt] [file] 1131 Same as above, but only write the lines in [range]. 1132 1133 *:x* *:xit* 1134:[range]x[it][!] [++opt] [file] 1135 Like ":wq", but write only when changes have been 1136 made. 1137 When 'hidden' is set and there are more windows, the 1138 current buffer becomes hidden, after writing the file. 1139 1140 *:exi* *:exit* 1141:[range]exi[t][!] [++opt] [file] 1142 Same as :xit. 1143 1144 *ZZ* 1145ZZ Write current file, if modified, and close the current 1146 window (same as ":x"). 1147 If there are several windows for the current file, 1148 only the current window is closed. 1149 1150 *ZQ* 1151ZQ Quit without checking for changes (same as ":q!"). 1152 1153 1154MULTIPLE WINDOWS AND BUFFERS *window-exit* 1155 1156 *:qa* *:qall* 1157:qa[ll] Exit Vim, unless there are some buffers which have been 1158 changed. (Use ":bmod" to go to the next modified buffer). 1159 When 'autowriteall' is set all changed buffers will be 1160 written, like |:wqall|. 1161 1162:conf[irm] qa[ll] 1163 Exit Vim. Bring up a prompt when some buffers have been 1164 changed. See |:confirm|. 1165 1166:qa[ll]! Exit Vim. Any changes to buffers are lost. 1167 Also see |:cquit|, it does the same but exits with a non-zero 1168 value. 1169 1170 *:quita* *:quitall* 1171:quita[ll][!] Same as ":qall". 1172 1173:wqa[ll] [++opt] *:wqa* *:wqall* *:xa* *:xall* 1174:xa[ll] Write all changed buffers and exit Vim. If there are buffers 1175 without a file name, which are readonly or which cannot be 1176 written for another reason, Vim will not quit. 1177 1178:conf[irm] wqa[ll] [++opt] 1179:conf[irm] xa[ll] 1180 Write all changed buffers and exit Vim. Bring up a prompt 1181 when some buffers are readonly or cannot be written for 1182 another reason. See |:confirm|. 1183 1184:wqa[ll]! [++opt] 1185:xa[ll]! Write all changed buffers, even the ones that are readonly, 1186 and exit Vim. If there are buffers without a file name or 1187 which cannot be written for another reason, or there is a 1188 terminal with a running job, Vim will not quit. 1189 1190============================================================================== 11916. Dialogs *edit-dialogs* 1192 1193 *:confirm* *:conf* 1194:conf[irm] {command} Execute {command}, and use a dialog when an 1195 operation has to be confirmed. Can be used on the 1196 |:q|, |:qa| and |:w| commands (the latter to override 1197 a read-only setting), and any other command that can 1198 fail in such a way, such as |:only|, |:buffer|, 1199 |:bdelete|, etc. 1200 1201Examples: > 1202 :confirm w foo 1203< Will ask for confirmation when "foo" already exists. > 1204 :confirm q 1205< Will ask for confirmation when there are changes. > 1206 :confirm qa 1207< If any modified, unsaved buffers exist, you will be prompted to save 1208 or abandon each one. There are also choices to "save all" or "abandon 1209 all". 1210 1211If you want to always use ":confirm", set the 'confirm' option. 1212 1213 *:browse* *:bro* *E338* *E614* *E615* *E616* 1214:bro[wse] {command} Open a file selection dialog for an argument to 1215 {command}. At present this works for |:e|, |:w|, 1216 |:wall|, |:wq|, |:wqall|, |:x|, |:xall|, |:exit|, 1217 |:view|, |:sview|, |:r|, |:saveas|, |:sp|, |:mkexrc|, 1218 |:mkvimrc|, |:mksession|, |:mkview|, |:split|, 1219 |:vsplit|, |:tabe|, |:tabnew|, |:cfile|, |:cgetfile|, 1220 |:caddfile|, |:lfile|, |:lgetfile|, |:laddfile|, 1221 |:diffsplit|, |:diffpatch|, |:open|, |:pedit|, 1222 |:redir|, |:source|, |:update|, |:visual|, |:vsplit|, 1223 and |:qall| if 'confirm' is set. 1224 {only in Win32, Athena, Motif, GTK and Mac GUI} 1225 When ":browse" is not possible you get an error 1226 message. If the |+browse| feature is missing or the 1227 {command} doesn't support browsing, the {command} is 1228 executed without a dialog. 1229 ":browse set" works like |:options|. 1230 See also |:oldfiles| for ":browse oldfiles". 1231 1232The syntax is best shown via some examples: > 1233 :browse e $vim/foo 1234< Open the browser in the $vim/foo directory, and edit the 1235 file chosen. > 1236 :browse e 1237< Open the browser in the directory specified with 'browsedir', 1238 and edit the file chosen. > 1239 :browse w 1240< Open the browser in the directory of the current buffer, 1241 with the current buffer filename as default, and save the 1242 buffer under the filename chosen. > 1243 :browse w C:/bar 1244< Open the browser in the C:/bar directory, with the current 1245 buffer filename as default, and save the buffer under the 1246 filename chosen. 1247Also see the 'browsedir' option. 1248For versions of Vim where browsing is not supported, the command is executed 1249unmodified. 1250 1251 *browsefilter* 1252For MS Windows and GTK, you can modify the filters that are used in the browse 1253dialog. By setting the g:browsefilter or b:browsefilter variables, you can 1254change the filters globally or locally to the buffer. The variable is set to 1255a string in the format "{filter label}\t{pattern};{pattern}\n" where {filter 1256label} is the text that appears in the "Files of Type" comboBox, and {pattern} 1257is the pattern which filters the filenames. Several patterns can be given, 1258separated by ';'. 1259 1260For Motif the same format is used, but only the very first pattern is actually 1261used (Motif only offers one pattern, but you can edit it). 1262 1263For example, to have only Vim files in the dialog, you could use the following 1264command: > 1265 1266 let g:browsefilter = "Vim Scripts\t*.vim\nVim Startup Files\t*vimrc\n" 1267 1268You can override the filter setting on a per-buffer basis by setting the 1269b:browsefilter variable. You would most likely set b:browsefilter in a 1270filetype plugin, so that the browse dialog would contain entries related to 1271the type of file you are currently editing. Disadvantage: This makes it 1272difficult to start editing a file of a different type. To overcome this, you 1273may want to add "All Files\t*.*\n" as the final filter, so that the user can 1274still access any desired file. 1275 1276To avoid setting browsefilter when Vim does not actually support it, you can 1277use has("browsefilter"): > 1278 1279 if has("browsefilter") 1280 let g:browsefilter = "whatever" 1281 endif 1282 1283============================================================================== 12847. The current directory *current-directory* 1285 1286You can use the |:cd|, |:tcd| and |:lcd| commands to change to another 1287directory, so you will not have to type that directory name in front of the 1288file names. It also makes a difference for executing external commands, e.g. 1289":!ls". 1290 1291Changing directory fails when the current buffer is modified, the '.' flag is 1292present in 'cpoptions' and "!" is not used in the command. 1293 1294 *:cd* *E747* *E472* 1295:cd[!] On non-Unix systems: Print the current directory 1296 name. On Unix systems: Change the current directory 1297 to the home directory. Use |:pwd| to print the 1298 current directory on all systems. 1299 On Unix systems: clear any window-local directory. 1300 1301:cd[!] {path} Change the current directory to {path}. 1302 If {path} is relative, it is searched for in the 1303 directories listed in |'cdpath'|. 1304 Clear any window-local directory. 1305 Does not change the meaning of an already opened file, 1306 because its full path name is remembered. Files from 1307 the |arglist| may change though! 1308 On MS-Windows this also changes the active drive. 1309 To change to the directory of the current file: > 1310 :cd %:h 1311< 1312 *:cd-* *E186* 1313:cd[!] - Change to the previous current directory (before the 1314 previous ":cd {path}" command). 1315 1316 *:chd* *:chdir* 1317:chd[ir][!] [path] Same as |:cd|. 1318 1319 *:tcd* 1320:tcd[!] {path} Like |:cd|, but only set the directory for the current 1321 tab. The current window will also use this directory. 1322 The current directory is not changed for windows in 1323 other tabs and for windows in the current tab that 1324 have their own window-local directory. 1325 1326 *:tch* *:tchdir* 1327:tch[dir][!] Same as |:tcd|. 1328 1329 *:tcd-* 1330:tcd[!] - Change to the previous current directory, before the 1331 last ":tcd {path}" command. 1332 1333 *:lc* *:lcd* 1334:lc[d][!] {path} Like |:cd|, but only set the current directory when 1335 the cursor is in the current window. The current 1336 directory for other windows is not changed, switching 1337 to another window will stop using {path}. 1338 1339 *:lch* *:lchdir* 1340:lch[dir][!] Same as |:lcd|. 1341 1342 *:lcd-* 1343:lcd[!] - Change to the previous current directory, before the 1344 last ":lcd {path}" command. 1345 1346 *:pw* *:pwd* *E187* 1347:pw[d] Print the current directory name. 1348 Also see |getcwd()|. 1349 *:pwd-verbose* 1350 When 'verbose' is non-zero, |:pwd| will also display 1351 what scope the current directory was set. Example: > 1352 1353 " Set by :cd 1354 :verbose pwd 1355 [global] /path/to/current 1356 1357 " Set by :lcd 1358 :verbose pwd 1359 [window] /path/to/current 1360 1361 " Set by :tcd 1362 :verbose pwd 1363 [tabpage] /path/to/current 1364 1365So long as no |:lcd| or |:tcd| command has been used, all windows share the 1366same current directory. Using a command to jump to another window doesn't 1367change anything for the current directory. 1368 1369When a |:lcd| command has been used for a window, the specified directory 1370becomes the current directory for that window. Windows where the |:lcd| 1371command has not been used stick to the global or tab-local current directory. 1372When jumping to another window the current directory will become the last 1373specified local current directory. If none was specified, the global or 1374tab-local current directory is used. 1375 1376When a |:tcd| command has been used for a tab page, the specified directory 1377becomes the current directory for the current tab page and the current window. 1378The current directory of other tab pages is not affected. When jumping to 1379another tab page, the current directory will become the last specified local 1380directory for that tab page. If the current tab has no local current directory 1381the global current directory is used. 1382 1383When a |:cd| command is used, the current window and tab page will lose the 1384local current directory and will use the global current directory from now on. 1385 1386After using |:cd| the full path name will be used for reading and writing 1387files. On some networked file systems this may cause problems. The result of 1388using the full path name is that the file names currently in use will remain 1389referring to the same file. Example: If you have a file a:test and a 1390directory a:vim the commands ":e test" ":cd vim" ":w" will overwrite the file 1391a:test and not write a:vim/test. But if you do ":w test" the file a:vim/test 1392will be written, because you gave a new file name and did not refer to a 1393filename before the ":cd". 1394 1395============================================================================== 13968. Editing binary files *edit-binary* 1397 1398Although Vim was made to edit text files, it is possible to edit binary 1399files. The |-b| Vim argument (b for binary) makes Vim do file I/O in binary 1400mode, and sets some options for editing binary files ('binary' on, 'textwidth' 1401to 0, 'modeline' off, 'expandtab' off). Setting the 'binary' option has the 1402same effect. Don't forget to do this before reading the file. 1403 1404There are a few things to remember when editing binary files: 1405- When editing executable files the number of characters must not change. 1406 Use only the "R" or "r" command to change text. Do not delete characters 1407 with "x" or by backspacing. 1408- Set the 'textwidth' option to 0. Otherwise lines will unexpectedly be 1409 split in two. 1410- When there are not many <EOL>s, the lines will become very long. If you 1411 want to edit a line that does not fit on the screen reset the 'wrap' option. 1412 Horizontal scrolling is used then. If a line becomes too long (more than 1413 about 32767 characters on the Amiga, much more on 32-bit systems, see 1414 |limits|) you cannot edit that line. The line will be split when reading 1415 the file. It is also possible that you get an "out of memory" error when 1416 reading the file. 1417- Make sure the 'binary' option is set BEFORE loading the 1418 file. Otherwise both <CR> <NL> and <NL> are considered to end a line 1419 and when the file is written the <NL> will be replaced with <CR> <NL>. 1420- <Nul> characters are shown on the screen as ^@. You can enter them with 1421 "CTRL-V CTRL-@" or "CTRL-V 000" 1422- To insert a <NL> character in the file split a line. When writing the 1423 buffer to a file a <NL> will be written for the <EOL>. 1424- Vim normally appends an <EOL> at the end of the file if there is none. 1425 Setting the 'binary' option prevents this. If you want to add the final 1426 <EOL>, set the 'endofline' option. You can also read the value of this 1427 option to see if there was an <EOL> for the last line (you cannot see this 1428 in the text). 1429 1430============================================================================== 14319. Encryption *encryption* 1432 1433Vim is able to write files encrypted, and read them back. The encrypted text 1434cannot be read without the right key. 1435{only available when compiled with the |+cryptv| feature} *E833* 1436 1437The text in the swap file and the undo file is also encrypted. *E843* 1438However, this is done block-by-block and may reduce the time needed to crack a 1439password. You can disable the swap file, but then a crash will cause you to 1440lose your work. The undo file can be disabled without too much disadvantage. > 1441 :set noundofile 1442 :noswapfile edit secrets 1443 1444Note: The text in memory is not encrypted. A system administrator may be able 1445to see your text while you are editing it. When filtering text with 1446":!filter" or using ":w !command" the text is also not encrypted, this may 1447reveal it to others. The 'viminfo' file is not encrypted. 1448 1449You could do this to edit very secret text: > 1450 :set noundofile viminfo= 1451 :noswapfile edit secrets.txt 1452Keep in mind that without a swap file you risk losing your work in the event 1453of a crash or a power failure. 1454 1455WARNING: If you make a typo when entering the key and then write the file and 1456exit, the text will be lost! 1457 1458The normal way to work with encryption, is to use the ":X" command, which will 1459ask you to enter a key. A following write command will use that key to 1460encrypt the file. If you later edit the same file, Vim will ask you to enter 1461a key. If you type the same key as that was used for writing, the text will 1462be readable again. If you use a wrong key, it will be a mess. 1463 1464 *:X* 1465:X Prompt for an encryption key. The typing is done without showing the 1466 actual text, so that someone looking at the display won't see it. 1467 The typed key is stored in the 'key' option, which is used to encrypt 1468 the file when it is written. The file will remain unchanged until you 1469 write it. See also |-x|. 1470 1471The value of the 'key' options is used when text is written. When the option 1472is not empty, the written file will be encrypted, using the value as the 1473encryption key. A magic number is prepended, so that Vim can recognize that 1474the file is encrypted. 1475 1476To disable the encryption, reset the 'key' option to an empty value: > 1477 :set key= 1478 1479You can use the 'cryptmethod' option to select the type of encryption, use one 1480of these: > 1481 :setlocal cm=zip " weak method, backwards compatible 1482 :setlocal cm=blowfish " method with flaws 1483 :setlocal cm=blowfish2 " medium strong method 1484 1485Do this before writing the file. When reading an encrypted file it will be 1486set automatically to the method used when that file was written. You can 1487change 'cryptmethod' before writing that file to change the method. 1488 1489To set the default method, used for new files, use this in your |vimrc| 1490file: > 1491 set cm=blowfish2 1492Using "blowfish2" is highly recommended. Only use another method if you 1493must use an older Vim version that does not support it. 1494 1495The message given for reading and writing a file will show "[crypted]" when 1496using zip, "[blowfish]" when using blowfish, etc. 1497 1498When writing an undo file, the same key and method will be used for the text 1499in the undo file. |persistent-undo|. 1500 1501To test for blowfish support you can use these conditions: > 1502 has('crypt-blowfish') 1503 has('crypt-blowfish2') 1504This works since Vim 7.4.1099 while blowfish support was added earlier. 1505Thus the condition failing doesn't mean blowfish is not supported. You can 1506test for blowfish with: > 1507 v:version >= 703 1508And for blowfish2 with: > 1509 v:version > 704 || (v:version == 704 && has('patch401')) 1510If you are sure Vim includes patch 7.4.237 a simpler check is: > 1511 has('patch-7.4.401') 1512< 1513 *E817* *E818* *E819* *E820* 1514When encryption does not work properly, you would be able to write your text 1515to a file and never be able to read it back. Therefore a test is performed to 1516check if the encryption works as expected. If you get one of these errors 1517don't write the file encrypted! You need to rebuild the Vim binary to fix 1518this. 1519 1520*E831* This is an internal error, "cannot happen". If you can reproduce it, 1521please report to the developers. 1522 1523When reading a file that has been encrypted and the 'key' option is not empty, 1524it will be used for decryption. If the value is empty, you will be prompted 1525to enter the key. If you don't enter a key, or you enter the wrong key, the 1526file is edited without being decrypted. There is no warning about using the 1527wrong key (this makes brute force methods to find the key more difficult). 1528 1529If want to start reading a file that uses a different key, set the 'key' 1530option to an empty string, so that Vim will prompt for a new one. Don't use 1531the ":set" command to enter the value, other people can read the command over 1532your shoulder. 1533 1534Since the value of the 'key' option is supposed to be a secret, its value can 1535never be viewed. You should not set this option in a vimrc file. 1536 1537An encrypted file can be recognized by the "file" command, if you add these 1538lines to "/etc/magic", "/usr/share/misc/magic" or wherever your system has the 1539"magic" file: > 1540 0 string VimCrypt~ Vim encrypted file 1541 >9 string 01 - "zip" cryptmethod 1542 >9 string 02 - "blowfish" cryptmethod 1543 >9 string 03 - "blowfish2" cryptmethod 1544 1545Notes: 1546- Encryption is not possible when doing conversion with 'charconvert'. 1547- Text you copy or delete goes to the numbered registers. The registers can 1548 be saved in the .viminfo file, where they could be read. Change your 1549 'viminfo' option to be safe. 1550- Someone can type commands in Vim when you walk away for a moment, he should 1551 not be able to get the key. 1552- If you make a typing mistake when entering the key, you might not be able to 1553 get your text back! 1554- If you type the key with a ":set key=value" command, it can be kept in the 1555 history, showing the 'key' value in a viminfo file. 1556- There is never 100% safety. The encryption in Vim has not been tested for 1557 robustness. 1558- The algorithm used for 'cryptmethod' "zip" is breakable. A 4 character key 1559 in about one hour, a 6 character key in one day (on a Pentium 133 PC). This 1560 requires that you know some text that must appear in the file. An expert 1561 can break it for any key. When the text has been decrypted, this also means 1562 that the key can be revealed, and other files encrypted with the same key 1563 can be decrypted. 1564- Pkzip uses the same encryption as 'cryptmethod' "zip", and US Govt has no 1565 objection to its export. Pkzip's public file APPNOTE.TXT describes this 1566 algorithm in detail. 1567- The implementation of 'cryptmethod' "blowfish" has a flaw. It is possible 1568 to crack the first 64 bytes of a file and in some circumstances more of the 1569 file. Use of it is not recommended, but it's still the strongest method 1570 supported by Vim 7.3 and 7.4. The "zip" method is even weaker. 1571- Vim originates from the Netherlands. That is where the sources come from. 1572 Thus the encryption code is not exported from the USA. 1573 1574============================================================================== 157510. Timestamps *timestamp* *timestamps* 1576 1577Vim remembers the modification timestamp, mode and size of a file when you 1578begin editing it. This is used to avoid that you have two different versions 1579of the same file (without you knowing this). 1580 1581After a shell command is run (|:!cmd| |suspend| |:read!| |K|) timestamps, 1582file modes and file sizes are compared for all buffers in a window. Vim will 1583run any associated |FileChangedShell| autocommands or display a warning for 1584any files that have changed. In the GUI this happens when Vim regains input 1585focus. 1586 1587 *E321* *E462* 1588If you want to automatically reload a file when it has been changed outside of 1589Vim, set the 'autoread' option. This doesn't work at the moment you write the 1590file though, only when the file wasn't changed inside of Vim. 1591 *ignore-timestamp* 1592If you do not want to be asked or automatically reload the file, you can use 1593this: > 1594 set buftype=nofile 1595 1596Or, when starting gvim from a shell: > 1597 gvim file.log -c "set buftype=nofile" 1598 1599Note that if a FileChangedShell autocommand is defined you will not get a 1600warning message or prompt. The autocommand is expected to handle this. 1601 1602There is no warning for a directory (e.g., with |netrw-browse|). But you do 1603get warned if you started editing a new file and it was created as a directory 1604later. 1605 1606When Vim notices the timestamp of a file has changed, and the file is being 1607edited in a buffer but has not changed, Vim checks if the contents of the file 1608is equal. This is done by reading the file again (into a hidden buffer, which 1609is immediately deleted again) and comparing the text. If the text is equal, 1610you will get no warning. 1611 1612If you don't get warned often enough you can use the following command. 1613 1614 *:checkt* *:checktime* 1615:checkt[ime] Check if any buffers were changed outside of Vim. 1616 This checks and warns you if you would end up with two 1617 versions of a file. 1618 If this is called from an autocommand, a ":global" 1619 command or is not typed the actual check is postponed 1620 until a moment the side effects (reloading the file) 1621 would be harmless. 1622 Each loaded buffer is checked for its associated file 1623 being changed. If the file was changed Vim will take 1624 action. If there are no changes in the buffer and 1625 'autoread' is set, the buffer is reloaded. Otherwise, 1626 you are offered the choice of reloading the file. If 1627 the file was deleted you get an error message. 1628 If the file previously didn't exist you get a warning 1629 if it exists now. 1630 Once a file has been checked the timestamp is reset, 1631 you will not be warned again. 1632 1633:[N]checkt[ime] {filename} 1634:[N]checkt[ime] [N] 1635 Check the timestamp of a specific buffer. The buffer 1636 may be specified by name, number or with a pattern. 1637 1638 1639 *E813* *E814* 1640Vim will reload the buffer if you chose to. If a window is visible that 1641contains this buffer, the reloading will happen in the context of this window. 1642Otherwise a special window is used, so that most autocommands will work. You 1643can't close this window. A few other restrictions apply. Best is to make 1644sure nothing happens outside of the current buffer. E.g., setting 1645window-local options may end up in the wrong window. Splitting the window, 1646doing something there and closing it should be OK (if there are no side 1647effects from other autocommands). Closing unrelated windows and buffers will 1648get you into trouble. 1649 1650Before writing a file the timestamp is checked. If it has changed, Vim will 1651ask if you really want to overwrite the file: 1652 1653 WARNING: The file has been changed since reading it!!! 1654 Do you really want to write to it (y/n)? 1655 1656If you hit 'y' Vim will continue writing the file. If you hit 'n' the write is 1657aborted. If you used ":wq" or "ZZ" Vim will not exit, you will get another 1658chance to write the file. 1659 1660The message would normally mean that somebody has written to the file after 1661the edit session started. This could be another person, in which case you 1662probably want to check if your changes to the file and the changes from the 1663other person should be merged. Write the file under another name and check for 1664differences (the "diff" program can be used for this). 1665 1666It is also possible that you modified the file yourself, from another edit 1667session or with another command (e.g., a filter command). Then you will know 1668which version of the file you want to keep. 1669 1670There is one situation where you get the message while there is nothing wrong: 1671On a Win32 system on the day daylight saving time starts. There is something 1672in the Win32 libraries that confuses Vim about the hour time difference. The 1673problem goes away the next day. 1674 1675============================================================================== 167611. File Searching *file-searching* 1677 1678{not available when compiled without the |+path_extra| feature} 1679 1680The file searching is currently used for the 'path', 'cdpath' and 'tags' 1681options, for |finddir()| and |findfile()|. Other commands use |wildcards| 1682which is slightly different. 1683 1684There are three different types of searching: 1685 16861) Downward search: *starstar* 1687 Downward search uses the wildcards '*', '**' and possibly others 1688 supported by your operating system. '*' and '**' are handled inside Vim, 1689 so they work on all operating systems. Note that "**" only acts as a 1690 special wildcard when it is at the start of a name. 1691 1692 The usage of '*' is quite simple: It matches 0 or more characters. In a 1693 search pattern this would be ".*". Note that the "." is not used for file 1694 searching. 1695 1696 '**' is more sophisticated: 1697 - It ONLY matches directories. 1698 - It matches up to 30 directories deep by default, so you can use it to 1699 search an entire directory tree 1700 - The maximum number of levels matched can be given by appending a number 1701 to '**'. 1702 Thus '/usr/**2' can match: > 1703 /usr 1704 /usr/include 1705 /usr/include/sys 1706 /usr/include/g++ 1707 /usr/lib 1708 /usr/lib/X11 1709 .... 1710< It does NOT match '/usr/include/g++/std' as this would be three 1711 levels. 1712 The allowed number range is 0 ('**0' is removed) to 100 1713 If the given number is smaller than 0 it defaults to 30, if it's 1714 bigger than 100 then 100 is used. The system also has a limit on the 1715 path length, usually 256 or 1024 bytes. 1716 - '**' can only be at the end of the path or be followed by a path 1717 separator or by a number and a path separator. 1718 1719 You can combine '*' and '**' in any order: > 1720 /usr/**/sys/* 1721 /usr/*tory/sys/** 1722 /usr/**2/sys/* 1723 17242) Upward search: 1725 Here you can give a directory and then search the directory tree upward for 1726 a file. You could give stop-directories to limit the upward search. The 1727 stop-directories are appended to the path (for the 'path' option) or to 1728 the filename (for the 'tags' option) with a ';'. If you want several 1729 stop-directories separate them with ';'. If you want no stop-directory 1730 ("search upward till the root directory) just use ';'. > 1731 /usr/include/sys;/usr 1732< will search in: > 1733 /usr/include/sys 1734 /usr/include 1735 /usr 1736< 1737 If you use a relative path the upward search is started in Vim's current 1738 directory or in the directory of the current file (if the relative path 1739 starts with './' and 'd' is not included in 'cpoptions'). 1740 1741 If Vim's current path is /u/user_x/work/release and you do > 1742 :set path=include;/u/user_x 1743< and then search for a file with |gf| the file is searched in: > 1744 /u/user_x/work/release/include 1745 /u/user_x/work/include 1746 /u/user_x/include 1747 17483) Combined up/downward search: 1749 If Vim's current path is /u/user_x/work/release and you do > 1750 set path=**;/u/user_x 1751< and then search for a file with |gf| the file is searched in: > 1752 /u/user_x/work/release/** 1753 /u/user_x/work/** 1754 /u/user_x/** 1755< 1756 BE CAREFUL! This might consume a lot of time, as the search of 1757 '/u/user_x/**' includes '/u/user_x/work/**' and 1758 '/u/user_x/work/release/**'. So '/u/user_x/work/release/**' is searched 1759 three times and '/u/user_x/work/**' is searched twice. 1760 1761 In the above example you might want to set path to: > 1762 :set path=**,/u/user_x/** 1763< This searches: 1764 /u/user_x/work/release/** ~ 1765 /u/user_x/** ~ 1766 This searches the same directories, but in a different order. 1767 1768 Note that completion for ":find", ":sfind", and ":tabfind" commands do not 1769 currently work with 'path' items that contain a URL or use the double star 1770 with depth limiter (/usr/**2) or upward search (;) notations. 1771 1772 vim:tw=78:ts=8:noet:ft=help:norl: 1773