summaryrefslogtreecommitdiffstats
path: root/runtime/doc/editing.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/editing.txt')
-rw-r--r--runtime/doc/editing.txt1750
1 files changed, 1750 insertions, 0 deletions
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
new file mode 100644
index 0000000..1fc1c2f
--- /dev/null
+++ b/runtime/doc/editing.txt
@@ -0,0 +1,1750 @@
+*editing.txt* For Vim version 8.1. Last change: 2018 Dec 16
+
+
+ VIM REFERENCE MANUAL by Bram Moolenaar
+
+
+Editing files *edit-files*
+
+1. Introduction |edit-intro|
+2. Editing a file |edit-a-file|
+3. The argument list |argument-list|
+4. Writing |writing|
+5. Writing and quitting |write-quit|
+6. Dialogs |edit-dialogs|
+7. The current directory |current-directory|
+8. Editing binary files |edit-binary|
+9. Encryption |encryption|
+10. Timestamps |timestamps|
+11. File Searching |file-searching|
+
+==============================================================================
+1. Introduction *edit-intro*
+
+Editing a file with Vim means:
+
+1. reading the file into a buffer
+2. changing the buffer with editor commands
+3. writing the buffer into a file
+
+ *current-file*
+As long as you don't write the buffer, the original file remains unchanged.
+If you start editing a file (read a file into the buffer), the file name is
+remembered as the "current file name". This is also known as the name of the
+current buffer. It can be used with "%" on the command line |:_%|.
+
+ *alternate-file*
+If there already was a current file name, then that one becomes the alternate
+file name. It can be used with "#" on the command line |:_#| and you can use
+the |CTRL-^| command to toggle between the current and the alternate file.
+However, the alternate file name is not changed when |:keepalt| is used.
+An alternate file name is remembered for each window.
+
+ *:keepalt* *:keepa*
+:keepalt {cmd} Execute {cmd} while keeping the current alternate file
+ name. Note that commands invoked indirectly (e.g.,
+ with a function) may still set the alternate file
+ name. {not in Vi}
+
+All file names are remembered in the buffer list. When you enter a file name,
+for editing (e.g., with ":e filename") or writing (e.g., with ":w filename"),
+the file name is added to the list. You can use the buffer list to remember
+which files you edited and to quickly switch from one file to another (e.g.,
+to copy text) with the |CTRL-^| command. First type the number of the file
+and then hit CTRL-^. {Vi: only one alternate file name is remembered}
+
+
+CTRL-G or *CTRL-G* *:f* *:fi* *:file*
+:f[ile] Prints the current file name (as typed, unless ":cd"
+ was used), the cursor position (unless the 'ruler'
+ option is set), and the file status (readonly,
+ modified, read errors, new file). See the 'shortmess'
+ option about how to make this message shorter.
+ {Vi does not include column number}
+
+:f[ile]! like |:file|, but don't truncate the name even when
+ 'shortmess' indicates this.
+
+{count}CTRL-G Like CTRL-G, but prints the current file name with
+ full path. If the count is higher than 1 the current
+ buffer number is also given. {not in Vi}
+
+ *g_CTRL-G* *word-count* *byte-count*
+g CTRL-G Prints the current position of the cursor in five
+ ways: Column, Line, Word, Character and Byte. If the
+ number of Characters and Bytes is the same then the
+ Character position is omitted.
+ If there are characters in the line that take more
+ than one position on the screen (<Tab> or special
+ character), both the "real" column and the screen
+ column are shown, separated with a dash.
+ Also see the 'ruler' option and the |wordcount()|
+ function.
+ {not in Vi}
+
+ *v_g_CTRL-G*
+{Visual}g CTRL-G Similar to "g CTRL-G", but Word, Character, Line, and
+ Byte counts for the visually selected region are
+ displayed.
+ In Blockwise mode, Column count is also shown. (For
+ {Visual} see |Visual-mode|.)
+ {not in VI}
+
+ *:file_f*
+:f[ile][!] {name} Sets the current file name to {name}. The optional !
+ avoids truncating the message, as with |:file|.
+ If the buffer did have a name, that name becomes the
+ |alternate-file| name. An unlisted buffer is created
+ to hold the old name.
+ *:0file*
+:0f[ile][!] Remove the name of the current buffer. The optional !
+ avoids truncating the message, as with |:file|. {not
+ in Vi}
+
+:buffers
+:files
+:ls List all the currently known file names. See
+ 'windows.txt' |:files| |:buffers| |:ls|. {not in
+ Vi}
+
+Vim will remember the full path name of a file name that you enter. In most
+cases when the file name is displayed only the name you typed is shown, but
+the full path name is being used if you used the ":cd" command |:cd|.
+
+ *home-replace*
+If the environment variable $HOME is set, and the file name starts with that
+string, it is often displayed with HOME replaced with "~". This was done to
+keep file names short. When reading or writing files the full name is still
+used, the "~" is only used when displaying file names. When replacing the
+file name would result in just "~", "~/" is used instead (to avoid confusion
+between options set to $HOME with 'backupext' set to "~").
+
+When writing the buffer, the default is to use the current file name. Thus
+when you give the "ZZ" or ":wq" command, the original file will be
+overwritten. If you do not want this, the buffer can be written into another
+file by giving a file name argument to the ":write" command. For example: >
+
+ vim testfile
+ [change the buffer with editor commands]
+ :w newfile
+ :q
+
+This will create a file "newfile", that is a modified copy of "testfile".
+The file "testfile" will remain unchanged. Anyway, if the 'backup' option is
+set, Vim renames or copies the original file before it will be overwritten.
+You can use this file if you discover that you need the original file. See
+also the 'patchmode' option. The name of the backup file is normally the same
+as the original file with 'backupext' appended. The default "~" is a bit
+strange to avoid accidentally overwriting existing files. If you prefer ".bak"
+change the 'backupext' option. Extra dots are replaced with '_' on MS-DOS
+machines, when Vim has detected that an MS-DOS-like filesystem is being used
+(e.g., messydos or crossdos) or when the 'shortname' option is on. The
+backup file can be placed in another directory by setting 'backupdir'.
+
+ *auto-shortname*
+Technical: On the Amiga you can use 30 characters for a file name. But on an
+ MS-DOS-compatible filesystem only 8 plus 3 characters are
+ available. Vim tries to detect the type of filesystem when it is
+ creating the .swp file. If an MS-DOS-like filesystem is suspected,
+ a flag is set that has the same effect as setting the 'shortname'
+ option. This flag will be reset as soon as you start editing a
+ new file. The flag will be used when making the file name for the
+ ".swp" and ".~" files for the current file. But when you are
+ editing a file in a normal filesystem and write to an MS-DOS-like
+ filesystem the flag will not have been set. In that case the
+ creation of the ".~" file may fail and you will get an error
+ message. Use the 'shortname' option in this case.
+
+When you started editing without giving a file name, "No File" is displayed in
+messages. If the ":write" command is used with a file name argument, the file
+name for the current file is set to that file name. This only happens when
+the 'F' flag is included in 'cpoptions' (by default it is included) |cpo-F|.
+This is useful when entering text in an empty buffer and then writing it to a
+file. If 'cpoptions' contains the 'f' flag (by default it is NOT included)
+|cpo-f| the file name is set for the ":read file" command. This is useful
+when starting Vim without an argument and then doing ":read file" to start
+editing a file.
+When the file name was set and 'filetype' is empty the filetype detection
+autocommands will be triggered.
+ *not-edited*
+Because the file name was set without really starting to edit that file, you
+are protected from overwriting that file. This is done by setting the
+"notedited" flag. You can see if this flag is set with the CTRL-G or ":file"
+command. It will include "[Not edited]" when the "notedited" flag is set.
+When writing the buffer to the current file name (with ":w!"), the "notedited"
+flag is reset.
+
+ *abandon*
+Vim remembers whether you have changed the buffer. You are protected from
+losing the changes you made. If you try to quit without writing, or want to
+start editing another file, Vim will refuse this. In order to overrule this
+protection, add a '!' to the command. The changes will then be lost. For
+example: ":q" will not work if the buffer was changed, but ":q!" will. To see
+whether the buffer was changed use the "CTRL-G" command. The message includes
+the string "[Modified]" if the buffer has been changed, or "+" if the 'm' flag
+is in 'shortmess'.
+
+If you want to automatically save the changes without asking, switch on the
+'autowriteall' option. 'autowrite' is the associated Vi-compatible option
+that does not work for all commands.
+
+If you want to keep the changed buffer without saving it, switch on the
+'hidden' option. See |hidden-buffer|. Some commands work like this even when
+'hidden' is not set, check the help for the command.
+
+==============================================================================
+2. Editing a file *edit-a-file*
+
+ *:e* *:edit* *reload*
+:e[dit] [++opt] [+cmd] Edit the current file. This is useful to re-edit the
+ current file, when it has been changed outside of Vim.
+ This fails when changes have been made to the current
+ buffer and 'autowriteall' isn't set or the file can't
+ be written.
+ Also see |++opt| and |+cmd|.
+ {Vi: no ++opt}
+
+ *:edit!* *discard*
+:e[dit]! [++opt] [+cmd]
+ Edit the current file always. Discard any changes to
+ the current buffer. This is useful if you want to
+ start all over again.
+ Also see |++opt| and |+cmd|.
+ {Vi: no ++opt}
+
+ *:edit_f*
+:e[dit] [++opt] [+cmd] {file}
+ Edit {file}.
+ This fails when changes have been made to the current
+ buffer, unless 'hidden' is set or 'autowriteall' is
+ set and the file can be written.
+ Also see |++opt| and |+cmd|.
+ {Vi: no ++opt}
+
+ *:edit!_f*
+:e[dit]! [++opt] [+cmd] {file}
+ Edit {file} always. Discard any changes to the
+ current buffer.
+ Also see |++opt| and |+cmd|.
+ {Vi: no ++opt}
+
+:e[dit] [++opt] [+cmd] #[count]
+ Edit the [count]th buffer (as shown by |:files|).
+ This command does the same as [count] CTRL-^. But ":e
+ #" doesn't work if the alternate buffer doesn't have a
+ file name, while CTRL-^ still works then.
+ Also see |++opt| and |+cmd|.
+ {Vi: no ++opt}
+
+ *:ene* *:enew*
+:ene[w] Edit a new, unnamed buffer. This fails when changes
+ have been made to the current buffer, unless 'hidden'
+ is set or 'autowriteall' is set and the file can be
+ written.
+ If 'fileformats' is not empty, the first format given
+ will be used for the new buffer. If 'fileformats' is
+ empty, the 'fileformat' of the current buffer is used.
+ {not in Vi}
+
+ *:ene!* *:enew!*
+:ene[w]! Edit a new, unnamed buffer. Discard any changes to
+ the current buffer.
+ Set 'fileformat' like |:enew|.
+ {not in Vi}
+
+ *:fin* *:find*
+:fin[d][!] [++opt] [+cmd] {file}
+ Find {file} in 'path' and then |:edit| it.
+ {not in Vi} {not available when the |+file_in_path|
+ feature was disabled at compile time}
+
+:{count}fin[d][!] [++opt] [+cmd] {file}
+ Just like ":find", but use the {count} match in
+ 'path'. Thus ":2find file" will find the second
+ "file" found in 'path'. When there are fewer matches
+ for the file in 'path' than asked for, you get an
+ error message.
+
+ *:ex*
+:ex [++opt] [+cmd] [file]
+ Same as |:edit|.
+
+ *:vi* *:visual*
+:vi[sual][!] [++opt] [+cmd] [file]
+ When used in Ex mode: Leave |Ex-mode|, go back to
+ Normal mode. Otherwise same as |:edit|.
+
+ *:vie* *:view*
+:vie[w][!] [++opt] [+cmd] file
+ When used in Ex mode: Leave |Ex-mode|, go back to
+ Normal mode. Otherwise same as |:edit|, but set
+ 'readonly' option for this buffer. {not in Vi}
+
+ *CTRL-^* *CTRL-6*
+CTRL-^ Edit the alternate file. Mostly the alternate file is
+ the previously edited file. This is a quick way to
+ toggle between two files. It is equivalent to ":e #",
+ except that it also works when there is no file name.
+
+ If the 'autowrite' or 'autowriteall' option is on and
+ the buffer was changed, write it.
+ Mostly the ^ character is positioned on the 6 key,
+ pressing CTRL and 6 then gets you what we call CTRL-^.
+ But on some non-US keyboards CTRL-^ is produced in
+ another way.
+
+{count}CTRL-^ Edit [count]th file in the buffer list (equivalent to
+ ":e #[count]"). This is a quick way to switch between
+ files.
+ See |CTRL-^| above for further details.
+ {not in Vi}
+
+[count]]f *]f* *[f*
+[count][f Same as "gf". Deprecated.
+
+ *gf* *E446* *E447*
+[count]gf Edit the file whose name is under or after the cursor.
+ Mnemonic: "goto file".
+ Uses the 'isfname' option to find out which characters
+ are supposed to be in a file name. Trailing
+ punctuation characters ".,:;!" are ignored. Escaped
+ spaces "\ " are reduced to a single space.
+ Uses the 'path' option as a list of directory names to
+ look for the file. See the 'path' option for details
+ about relative directories and wildcards.
+ Uses the 'suffixesadd' option to check for file names
+ with a suffix added.
+ If the file can't be found, 'includeexpr' is used to
+ modify the name and another attempt is done.
+ If a [count] is given, the count'th file that is found
+ in the 'path' is edited.
+ This command fails if Vim refuses to |abandon| the
+ current file.
+ If you want to edit the file in a new window use
+ |CTRL-W_CTRL-F|.
+ If you do want to edit a new file, use: >
+ :e <cfile>
+< To make gf always work like that: >
+ :map gf :e <cfile><CR>
+< If the name is a hypertext link, that looks like
+ "type://machine/path", you need the |netrw| plugin.
+ For Unix the '~' character is expanded, like in
+ "~user/file". Environment variables are expanded too
+ |expand-env|.
+ {not in Vi}
+ {not available when the |+file_in_path| feature was
+ disabled at compile time}
+
+ *v_gf*
+{Visual}[count]gf Same as "gf", but the highlighted text is used as the
+ name of the file to edit. 'isfname' is ignored.
+ Leading blanks are skipped, otherwise all blanks and
+ special characters are included in the file name.
+ (For {Visual} see |Visual-mode|.)
+ {not in VI}
+
+ *gF*
+[count]gF Same as "gf", except if a number follows the file
+ name, then the cursor is positioned on that line in
+ the file. The file name and the number must be
+ separated by a non-filename (see 'isfname') and
+ non-numeric character. White space between the
+ filename, the separator and the number are ignored.
+ Examples:
+ eval.c:10 ~
+ eval.c @ 20 ~
+ eval.c (30) ~
+ eval.c 40 ~
+
+ *v_gF*
+{Visual}[count]gF Same as "v_gf".
+
+These commands are used to start editing a single file. This means that the
+file is read into the buffer and the current file name is set. The file that
+is opened depends on the current directory, see |:cd|.
+
+See |read-messages| for an explanation of the message that is given after the
+file has been read.
+
+You can use the ":e!" command if you messed up the buffer and want to start
+all over again. The ":e" command is only useful if you have changed the
+current file name.
+
+ *:filename* *{file}*
+Besides the things mentioned here, more special items for where a filename is
+expected are mentioned at |cmdline-special|.
+
+Note for systems other than Unix: When using a command that accepts a single
+file name (like ":edit file") spaces in the file name are allowed, but
+trailing spaces are ignored. This is useful on systems that regularly embed
+spaces in file names (like MS-Windows and the Amiga). Example: The command
+":e Long File Name " will edit the file "Long File Name". When using a
+command that accepts more than one file name (like ":next file1 file2")
+embedded spaces must be escaped with a backslash.
+
+ *wildcard* *wildcards*
+Wildcards in {file} are expanded, but as with file completion, 'wildignore'
+and 'suffixes' apply. Which wildcards are supported depends on the system.
+These are the common ones:
+ ? matches one character
+ * matches anything, including nothing
+ ** matches anything, including nothing, recurses into directories
+ [abc] match 'a', 'b' or 'c'
+
+To avoid the special meaning of the wildcards prepend a backslash. However,
+on MS-Windows the backslash is a path separator and "path\[abc]" is still seen
+as a wildcard when "[" is in the 'isfname' option. A simple way to avoid this
+is to use "path\[[]abc]", this matches the file "path\[abc]".
+
+ *starstar-wildcard*
+Expanding "**" is possible on Unix, Win32, Mac OS/X and a few other systems.
+This allows searching a directory tree. This goes up to 100 directories deep.
+Note there are some commands where this works slightly differently, see
+|file-searching|.
+Example: >
+ :n **/*.txt
+Finds files:
+ aaa.txt ~
+ subdir/bbb.txt ~
+ a/b/c/d/ccc.txt ~
+When non-wildcard characters are used right before or after "**" these are
+only matched in the top directory. They are not used for directories further
+down in the tree. For example: >
+ :n /usr/inc**/types.h
+Finds files:
+ /usr/include/types.h ~
+ /usr/include/sys/types.h ~
+ /usr/inc/old/types.h ~
+Note that the path with "/sys" is included because it does not need to match
+"/inc". Thus it's like matching "/usr/inc*/*/*...", not
+"/usr/inc*/inc*/inc*".
+
+ *backtick-expansion* *`-expansion*
+On Unix and a few other systems you can also use backticks for the file name
+argument, for example: >
+ :next `find . -name ver\\*.c -print`
+ :view `ls -t *.patch \| head -n1`
+Vim will run the command in backticks using the 'shell' and use the standard
+output as argument for the given Vim command (error messages from the shell
+command will be discarded).
+To see what shell command Vim is running, set the 'verbose' option to 4. When
+the shell command returns a non-zero exit code, an error message will be
+displayed and the Vim command will be aborted. To avoid this make the shell
+always return zero like so: >
+ :next `find . -name ver\\*.c -print \|\| true`
+
+The backslashes before the star are required to prevent the shell from
+expanding "ver*.c" prior to execution of the find program. The backslash
+before the shell pipe symbol "|" prevents Vim from parsing it as command
+termination.
+This also works for most other systems, with the restriction that the
+backticks must be around the whole item. It is not possible to have text
+directly before the first or just after the last backtick.
+
+ *`=*
+You can have the backticks expanded as a Vim expression, instead of as an
+external command, by putting an equal sign right after the first backtick,
+e.g.: >
+ :e `=tempname()`
+The expression can contain just about anything, thus this can also be used to
+avoid the special meaning of '"', '|', '%' and '#'. However, 'wildignore'
+does apply like to other wildcards.
+
+Environment variables in the expression are expanded when evaluating the
+expression, thus this works: >
+ :e `=$HOME . '/.vimrc'`
+This does not work, $HOME is inside a string and used literally: >
+ :e `='$HOME' . '/.vimrc'`
+
+If the expression returns a string then names are to be separated with line
+breaks. When the result is a |List| then each item is used as a name. Line
+breaks also separate names.
+Note that such expressions are only supported in places where a filename is
+expected as an argument to an Ex-command.
+
+ *++opt* *[++opt]*
+The [++opt] argument can be used to force the value of 'fileformat',
+'fileencoding' or 'binary' to a value for one command, and to specify the
+behavior for bad characters. The form is: >
+ ++{optname}
+Or: >
+ ++{optname}={value}
+
+Where {optname} is one of: *++ff* *++enc* *++bin* *++nobin* *++edit*
+ ff or fileformat overrides 'fileformat'
+ enc or encoding overrides 'fileencoding'
+ bin or binary sets 'binary'
+ nobin or nobinary resets 'binary'
+ bad specifies behavior for bad characters
+ edit for |:read| only: keep option values as if editing
+ a file
+
+{value} cannot contain white space. It can be any valid value for these
+options. Examples: >
+ :e ++ff=unix
+This edits the same file again with 'fileformat' set to "unix". >
+
+ :w ++enc=latin1 newfile
+This writes the current buffer to "newfile" in latin1 format.
+
+There may be several ++opt arguments, separated by white space. They must all
+appear before any |+cmd| argument.
+
+ *++bad*
+The argument of "++bad=" specifies what happens with characters that can't be
+converted and illegal bytes. It can be one of three things:
+ ++bad=X A single-byte character that replaces each bad character.
+ ++bad=keep Keep bad characters without conversion. Note that this may
+ result in illegal bytes in your text!
+ ++bad=drop Remove the bad characters.
+
+The default is like "++bad=?": Replace each bad character with a question
+mark. In some places an inverted question mark is used (0xBF).
+
+Note that not all commands use the ++bad argument, even though they do not
+give an error when you add it. E.g. |:write|.
+
+Note that when reading, the 'fileformat' and 'fileencoding' options will be
+set to the used format. When writing this doesn't happen, thus a next write
+will use the old value of the option. Same for the 'binary' option.
+
+
+ *+cmd* *[+cmd]*
+The [+cmd] argument can be used to position the cursor in the newly opened
+file, or execute any other command:
+ + Start at the last line.
+ +{num} Start at line {num}.
+ +/{pat} Start at first line containing {pat}.
+ +{command} Execute {command} after opening the new file.
+ {command} is any Ex command.
+To include a white space in the {pat} or {command}, precede it with a
+backslash. Double the number of backslashes. >
+ :edit +/The\ book file
+ :edit +/dir\ dirname\\ file
+ :edit +set\ dir=c:\\\\temp file
+Note that in the last example the number of backslashes is halved twice: Once
+for the "+cmd" argument and once for the ":set" command.
+
+ *file-formats*
+The 'fileformat' option sets the <EOL> style for a file:
+'fileformat' characters name ~
+ "dos" <CR><NL> or <NL> DOS format *DOS-format*
+ "unix" <NL> Unix format *Unix-format*
+ "mac" <CR> Mac format *Mac-format*
+Previously 'textmode' was used. It is obsolete now.
+
+When reading a file, the mentioned characters are interpreted as the <EOL>.
+In DOS format (default for MS-DOS, OS/2 and Win32), <CR><NL> and <NL> are both
+interpreted as the <EOL>. Note that when writing the file in DOS format,
+<CR> characters will be added for each single <NL>. Also see |file-read|.
+
+When writing a file, the mentioned characters are used for <EOL>. For DOS
+format <CR><NL> is used. Also see |DOS-format-write|.
+
+You can read a file in DOS format and write it in Unix format. This will
+replace all <CR><NL> pairs by <NL> (assuming 'fileformats' includes "dos"): >
+ :e file
+ :set fileformat=unix
+ :w
+If you read a file in Unix format and write with DOS format, all <NL>
+characters will be replaced with <CR><NL> (assuming 'fileformats' includes
+"unix"): >
+ :e file
+ :set fileformat=dos
+ :w
+
+If you start editing a new file and the 'fileformats' option is not empty
+(which is the default), Vim will try to detect whether the lines in the file
+are separated by the specified formats. When set to "unix,dos", Vim will
+check for lines with a single <NL> (as used on Unix and Amiga) or by a <CR>
+<NL> pair (MS-DOS). Only when ALL lines end in <CR><NL>, 'fileformat' is set
+to "dos", otherwise it is set to "unix". When 'fileformats' includes "mac",
+and no <NL> characters are found in the file, 'fileformat' is set to "mac".
+
+If the 'fileformat' option is set to "dos" on non-MS-DOS systems the message
+"[dos format]" is shown to remind you that something unusual is happening. On
+MS-DOS systems you get the message "[unix format]" if 'fileformat' is set to
+"unix". On all systems but the Macintosh you get the message "[mac format]"
+if 'fileformat' is set to "mac".
+
+If the 'fileformats' option is empty and DOS format is used, but while reading
+a file some lines did not end in <CR><NL>, "[CR missing]" will be included in
+the file message.
+If the 'fileformats' option is empty and Mac format is used, but while reading
+a file a <NL> was found, "[NL missing]" will be included in the file message.
+
+If the new file does not exist, the 'fileformat' of the current buffer is used
+when 'fileformats' is empty. Otherwise the first format from 'fileformats' is
+used for the new file.
+
+Before editing binary, executable or Vim script files you should set the
+'binary' option. A simple way to do this is by starting Vim with the "-b"
+option. This will avoid the use of 'fileformat'. Without this you risk that
+single <NL> characters are unexpectedly replaced with <CR><NL>.
+
+You can encrypt files that are written by setting the 'key' option. This
+provides some security against others reading your files. |encryption|
+
+
+==============================================================================
+3. The argument list *argument-list* *arglist*
+
+If you give more than one file name when starting Vim, this list is remembered
+as the argument list. You can jump to each file in this list.
+
+Do not confuse this with the buffer list, which you can see with the
+|:buffers| command. The argument list was already present in Vi, the buffer
+list is new in Vim. Every file name in the argument list will also be present
+in the buffer list (unless it was deleted with |:bdel| or |:bwipe|). But it's
+common that names in the buffer list are not in the argument list.
+
+This subject is introduced in section |07.2| of the user manual.
+
+There is one global argument list, which is used for all windows by default.
+It is possible to create a new argument list local to a window, see
+|:arglocal|.
+
+You can use the argument list with the following commands, and with the
+expression functions |argc()| and |argv()|. These all work on the argument
+list of the current window.
+
+ *:ar* *:args*
+:ar[gs] Print the argument list, with the current file in
+ square brackets.
+
+:ar[gs] [++opt] [+cmd] {arglist} *:args_f*
+ Define {arglist} as the new argument list and edit
+ the first one. This fails when changes have been made
+ and Vim does not want to |abandon| the current buffer.
+ Also see |++opt| and |+cmd|.
+ {Vi: no ++opt}
+
+:ar[gs]! [++opt] [+cmd] {arglist} *:args_f!*
+ Define {arglist} as the new argument list and edit
+ the first one. Discard any changes to the current
+ buffer.
+ Also see |++opt| and |+cmd|.
+ {Vi: no ++opt}
+
+:[count]arge[dit][!] [++opt] [+cmd] {name} .. *:arge* *:argedit*
+ Add {name}s to the argument list and edit it.
+ When {name} already exists in the argument list, this
+ entry is edited.
+ This is like using |:argadd| and then |:edit|.
+ Spaces in filenames have to be escaped with "\".
+ [count] is used like with |:argadd|.
+ If the current file cannot be |abandon|ed {name}s will
+ still be added to the argument list, but won't be
+ edited. No check for duplicates is done.
+ Also see |++opt| and |+cmd|.
+ {not in Vi}
+
+:[count]arga[dd] {name} .. *:arga* *:argadd* *E479*
+:[count]arga[dd]
+ Add the {name}s to the argument list. When {name} is
+ omitted add the current buffer name to the argument
+ list.
+ If [count] is omitted, the {name}s are added just
+ after the current entry in the argument list.
+ Otherwise they are added after the [count]'th file.
+ If the argument list is "a b c", and "b" is the
+ current argument, then these commands result in:
+ command new argument list ~
+ :argadd x a b x c
+ :0argadd x x a b c
+ :1argadd x a x b c
+ :$argadd x a b c x
+ And after the last one:
+ :+2argadd y a b c x y
+ There is no check for duplicates, it is possible to
+ add a file to the argument list twice.
+ The currently edited file is not changed.
+ {not in Vi}
+ Note: you can also use this method: >
+ :args ## x
+< This will add the "x" item and sort the new list.
+
+:argd[elete] {pattern} .. *:argd* *:argdelete* *E480*
+ Delete files from the argument list that match the
+ {pattern}s. {pattern} is used like a file pattern,
+ see |file-pattern|. "%" can be used to delete the
+ current entry.
+ This command keeps the currently edited file, also
+ when it's deleted from the argument list.
+ Example: >
+ :argdel *.obj
+< {not in Vi}
+
+:[range]argd[elete] Delete the {range} files from the argument list.
+ Example: >
+ :10,$argdel
+< Deletes arguments 10 and further, keeping 1-9. >
+ :$argd
+< Deletes just the last one. >
+ :argd
+ :.argd
+< Deletes the current argument. >
+ :%argd
+< Removes all the files from the arglist.
+ When the last number in the range is too high, up to
+ the last argument is deleted.
+ {not in Vi}
+
+ *:argu* *:argument*
+:[count]argu[ment] [count] [++opt] [+cmd]
+ Edit file [count] in the argument list. When [count]
+ is omitted the current entry is used. This fails
+ when changes have been made and Vim does not want to
+ |abandon| the current buffer.
+ Also see |++opt| and |+cmd|.
+ {not in Vi}
+
+:[count]argu[ment]! [count] [++opt] [+cmd]
+ Edit file [count] in the argument list, discard any
+ changes to the current buffer. When [count] is
+ omitted the current entry is used.
+ Also see |++opt| and |+cmd|.
+ {not in Vi}
+
+:[count]n[ext] [++opt] [+cmd] *:n* *:ne* *:next* *E165* *E163*
+ Edit [count] next file. This fails when changes have
+ been made and Vim does not want to |abandon| the
+ current buffer. Also see |++opt| and |+cmd|. {Vi: no
+ count or ++opt}.
+
+:[count]n[ext]! [++opt] [+cmd]
+ Edit [count] next file, discard any changes to the
+ buffer. Also see |++opt| and |+cmd|. {Vi: no count
+ or ++opt}.
+
+:n[ext] [++opt] [+cmd] {arglist} *:next_f*
+ Same as |:args_f|.
+
+:n[ext]! [++opt] [+cmd] {arglist}
+ Same as |:args_f!|.
+
+:[count]N[ext] [count] [++opt] [+cmd] *:Next* *:N* *E164*
+ Edit [count] previous file in argument list. This
+ fails when changes have been made and Vim does not
+ want to |abandon| the current buffer.
+ Also see |++opt| and |+cmd|. {Vi: no count or ++opt}.
+
+:[count]N[ext]! [count] [++opt] [+cmd]
+ Edit [count] previous file in argument list. Discard
+ any changes to the buffer. Also see |++opt| and
+ |+cmd|. {Vi: no count or ++opt}.
+
+:[count]prev[ious] [count] [++opt] [+cmd] *:prev* *:previous*
+ Same as :Next. Also see |++opt| and |+cmd|. {Vi:
+ only in some versions}
+
+ *:rew* *:rewind*
+:rew[ind] [++opt] [+cmd]
+ Start editing the first file in the argument list.
+ This fails when changes have been made and Vim does
+ not want to |abandon| the current buffer.
+ Also see |++opt| and |+cmd|. {Vi: no ++opt}
+
+:rew[ind]! [++opt] [+cmd]
+ Start editing the first file in the argument list.
+ Discard any changes to the buffer. Also see |++opt|
+ and |+cmd|. {Vi: no ++opt}
+
+ *:fir* *:first*
+:fir[st][!] [++opt] [+cmd]
+ Other name for ":rewind". {not in Vi}
+
+ *:la* *:last*
+:la[st] [++opt] [+cmd]
+ Start editing the last file in the argument list.
+ This fails when changes have been made and Vim does
+ not want to |abandon| the current buffer.
+ Also see |++opt| and |+cmd|. {not in Vi}
+
+:la[st]! [++opt] [+cmd]
+ Start editing the last file in the argument list.
+ Discard any changes to the buffer. Also see |++opt|
+ and |+cmd|. {not in Vi}
+
+ *:wn* *:wnext*
+:[count]wn[ext] [++opt]
+ Write current file and start editing the [count]
+ next file. Also see |++opt| and |+cmd|. {not in Vi}
+
+:[count]wn[ext] [++opt] {file}
+ Write current file to {file} and start editing the
+ [count] next file, unless {file} already exists and
+ the 'writeany' option is off. Also see |++opt| and
+ |+cmd|. {not in Vi}
+
+:[count]wn[ext]! [++opt] {file}
+ Write current file to {file} and start editing the
+ [count] next file. Also see |++opt| and |+cmd|. {not
+ in Vi}
+
+:[count]wN[ext][!] [++opt] [file] *:wN* *:wNext*
+:[count]wp[revious][!] [++opt] [file] *:wp* *:wprevious*
+ Same as :wnext, but go to previous file instead of
+ next. {not in Vi}
+
+The [count] in the commands above defaults to one. For some commands it is
+possible to use two counts. The last one (rightmost one) is used.
+
+If no [+cmd] argument is present, the cursor is positioned at the last known
+cursor position for the file. If 'startofline' is set, the cursor will be
+positioned at the first non-blank in the line, otherwise the last know column
+is used. If there is no last known cursor position the cursor will be in the
+first line (the last line in Ex mode).
+
+ *{arglist}*
+The wildcards in the argument list are expanded and the file names are sorted.
+Thus you can use the command "vim *.c" to edit all the C files. From within
+Vim the command ":n *.c" does the same.
+
+White space is used to separate file names. Put a backslash before a space or
+tab to include it in a file name. E.g., to edit the single file "foo bar": >
+ :next foo\ bar
+
+On Unix and a few other systems you can also use backticks, for example: >
+ :next `find . -name \\*.c -print`
+The backslashes before the star are required to prevent "*.c" to be expanded
+by the shell before executing the find program.
+
+ *arglist-position*
+When there is an argument list you can see which file you are editing in the
+title of the window (if there is one and 'title' is on) and with the file
+message you get with the "CTRL-G" command. You will see something like
+ (file 4 of 11)
+If 'shortmess' contains 'f' it will be
+ (4 of 11)
+If you are not really editing the file at the current position in the argument
+list it will be
+ (file (4) of 11)
+This means that you are position 4 in the argument list, but not editing the
+fourth file in the argument list. This happens when you do ":e file".
+
+
+LOCAL ARGUMENT LIST
+
+{not in Vi}
+
+ *:arglocal*
+:argl[ocal] Make a local copy of the global argument list.
+ Doesn't start editing another file.
+
+:argl[ocal][!] [++opt] [+cmd] {arglist}
+ Define a new argument list, which is local to the
+ current window. Works like |:args_f| otherwise.
+
+ *:argglobal*
+:argg[lobal] Use the global argument list for the current window.
+ Doesn't start editing another file.
+
+:argg[lobal][!] [++opt] [+cmd] {arglist}
+ Use the global argument list for the current window.
+ Define a new global argument list like |:args_f|.
+ All windows using the global argument list will see
+ this new list.
+
+There can be several argument lists. They can be shared between windows.
+When they are shared, changing the argument list in one window will also
+change it in the other window.
+
+When a window is split the new window inherits the argument list from the
+current window. The two windows then share this list, until one of them uses
+|:arglocal| or |:argglobal| to use another argument list.
+
+
+USING THE ARGUMENT LIST
+
+ *:argdo*
+:[range]argdo[!] {cmd} Execute {cmd} for each file in the argument list or
+ if [range] is specified only for arguments in that
+ range. It works like doing this: >
+ :rewind
+ :{cmd}
+ :next
+ :{cmd}
+ etc.
+< When the current file can't be |abandon|ed and the [!]
+ is not present, the command fails.
+ When an error is detected on one file, further files
+ in the argument list will not be visited.
+ The last file in the argument list (or where an error
+ occurred) becomes the current file.
+ {cmd} can contain '|' to concatenate several commands.
+ {cmd} must not change the argument list.
+ Note: While this command is executing, the Syntax
+ autocommand event is disabled by adding it to
+ 'eventignore'. This considerably speeds up editing
+ each file.
+ {not in Vi}
+ Also see |:windo|, |:tabdo|, |:bufdo|, |:cdo|, |:ldo|,
+ |:cfdo| and |:lfdo|
+
+Example: >
+ :args *.c
+ :argdo set ff=unix | update
+This sets the 'fileformat' option to "unix" and writes the file if it is now
+changed. This is done for all *.c files.
+
+Example: >
+ :args *.[ch]
+ :argdo %s/\<my_foo\>/My_Foo/ge | update
+This changes the word "my_foo" to "My_Foo" in all *.c and *.h files. The "e"
+flag is used for the ":substitute" command to avoid an error for files where
+"my_foo" isn't used. ":update" writes the file only if changes were made.
+
+==============================================================================
+4. Writing *writing* *save-file*
+
+Note: When the 'write' option is off, you are not able to write any file.
+
+ *:w* *:write*
+ *E502* *E503* *E504* *E505*
+ *E512* *E514* *E667* *E796* *E949*
+:w[rite] [++opt] Write the whole buffer to the current file. This is
+ the normal way to save changes to a file. It fails
+ when the 'readonly' option is set or when there is
+ another reason why the file can't be written.
+ For ++opt see |++opt|, but only ++bin, ++nobin, ++ff
+ and ++enc are effective.
+
+:w[rite]! [++opt] Like ":write", but forcefully write when 'readonly' is
+ set or there is another reason why writing was
+ refused.
+ Note: This may change the permission and ownership of
+ the file and break (symbolic) links. Add the 'W' flag
+ to 'cpoptions' to avoid this.
+
+:[range]w[rite][!] [++opt]
+ Write the specified lines to the current file. This
+ is unusual, because the file will not contain all
+ lines in the buffer.
+
+ *:w_f* *:write_f*
+:[range]w[rite] [++opt] {file}
+ Write the specified lines to {file}, unless it
+ already exists and the 'writeany' option is off.
+
+ *:w!*
+:[range]w[rite]! [++opt] {file}
+ Write the specified lines to {file}. Overwrite an
+ existing file.
+
+ *:w_a* *:write_a* *E494*
+:[range]w[rite][!] [++opt] >>
+ Append the specified lines to the current file.
+
+:[range]w[rite][!] [++opt] >> {file}
+ Append the specified lines to {file}. '!' forces the
+ write even if file does not exist.
+
+ *:w_c* *:write_c*
+:[range]w[rite] [++opt] !{cmd}
+ Execute {cmd} with [range] lines as standard input
+ (note the space in front of the '!'). {cmd} is
+ executed like with ":!{cmd}", any '!' is replaced with
+ the previous command |:!|.
+
+The default [range] for the ":w" command is the whole buffer (1,$). If you
+write the whole buffer, it is no longer considered changed. When you
+write it to a different file with ":w somefile" it depends on the "+" flag in
+'cpoptions'. When included, the write command will reset the 'modified' flag,
+even though the buffer itself may still be different from its file.
+
+If a file name is given with ":w" it becomes the alternate file. This can be
+used, for example, when the write fails and you want to try again later with
+":w #". This can be switched off by removing the 'A' flag from the
+'cpoptions' option.
+
+Note that the 'fsync' option matters here. If it's set it may make writes
+slower (but safer).
+
+ *:sav* *:saveas*
+:sav[eas][!] [++opt] {file}
+ Save the current buffer under the name {file} and set
+ the filename of the current buffer to {file}. The
+ previous name is used for the alternate file name.
+ The [!] is needed to overwrite an existing file.
+ When 'filetype' is empty filetype detection is done
+ with the new name, before the file is written.
+ When the write was successful 'readonly' is reset.
+ {not in Vi}
+
+ *:up* *:update*
+:[range]up[date][!] [++opt] [>>] [file]
+ Like ":write", but only write when the buffer has been
+ modified. {not in Vi}
+
+
+WRITING WITH MULTIPLE BUFFERS *buffer-write*
+
+ *:wa* *:wall*
+:wa[ll] Write all changed buffers. Buffers without a file
+ name cause an error message. Buffers which are
+ readonly are not written. {not in Vi}
+
+:wa[ll]! Write all changed buffers, even the ones that are
+ readonly. Buffers without a file name are not
+ written and cause an error message. {not in Vi}
+
+
+Vim will warn you if you try to overwrite a file that has been changed
+elsewhere. See |timestamp|.
+
+ *backup* *E207* *E506* *E507* *E508* *E509* *E510*
+If you write to an existing file (but do not append) while the 'backup',
+'writebackup' or 'patchmode' option is on, a backup of the original file is
+made. The file is either copied or renamed (see 'backupcopy'). After the
+file has been successfully written and when the 'writebackup' option is on and
+the 'backup' option is off, the backup file is deleted. When the 'patchmode'
+option is on the backup file may be renamed.
+
+ *backup-table*
+'backup' 'writebackup' action ~
+ off off no backup made
+ off on backup current file, deleted afterwards (default)
+ on off delete old backup, backup current file
+ on on delete old backup, backup current file
+
+When the 'backupskip' pattern matches with the name of the file which is
+written, no backup file is made. The values of 'backup' and 'writebackup' are
+ignored then.
+
+When the 'backup' option is on, an old backup file (with the same name as the
+new backup file) will be deleted. If 'backup' is not set, but 'writebackup'
+is set, an existing backup file will not be deleted. The backup file that is
+made while the file is being written will have a different name.
+
+On some filesystems it's possible that in a crash you lose both the backup and
+the newly written file (it might be there but contain bogus data). In that
+case try recovery, because the swap file is synced to disk and might still be
+there. |:recover|
+
+The directories given with the 'backupdir' option are used to put the backup
+file in. (default: same directory as the written file).
+
+Whether the backup is a new file, which is a copy of the original file, or the
+original file renamed depends on the 'backupcopy' option. See there for an
+explanation of when the copy is made and when the file is renamed.
+
+If the creation of a backup file fails, the write is not done. If you want
+to write anyway add a '!' to the command.
+
+ *write-permissions*
+When writing a new file the permissions are read-write. For unix the mask is
+0666 with additionally umask applied. When writing a file that was read Vim
+will preserve the permissions, but clear the s-bit.
+
+ *write-readonly*
+When the 'cpoptions' option contains 'W', Vim will refuse to overwrite a
+readonly file. When 'W' is not present, ":w!" will overwrite a readonly file,
+if the system allows it (the directory must be writable).
+
+ *write-fail*
+If the writing of the new file fails, you have to be careful not to lose
+your changes AND the original file. If there is no backup file and writing
+the new file failed, you have already lost the original file! DON'T EXIT VIM
+UNTIL YOU WRITE OUT THE FILE! If a backup was made, it is put back in place
+of the original file (if possible). If you exit Vim, and lose the changes
+you made, the original file will mostly still be there. If putting back the
+original file fails, there will be an error message telling you that you
+lost the original file.
+
+ *DOS-format-write*
+If the 'fileformat' is "dos", <CR> <NL> is used for <EOL>. This is default
+for MS-DOS, Win32 and OS/2. On other systems the message "[dos format]" is
+shown to remind you that an unusual <EOL> was used.
+ *Unix-format-write*
+If the 'fileformat' is "unix", <NL> is used for <EOL>. On MS-DOS, Win32 and
+OS/2 the message "[unix format]" is shown.
+ *Mac-format-write*
+If the 'fileformat' is "mac", <CR> is used for <EOL>. On non-Mac systems the
+message "[mac format]" is shown.
+
+See also |file-formats| and the 'fileformat' and 'fileformats' options.
+
+ *ACL*
+ACL stands for Access Control List. It is an advanced way to control access
+rights for a file. It is used on new MS-Windows and Unix systems, but only
+when the filesystem supports it.
+ Vim attempts to preserve the ACL info when writing a file. The backup file
+will get the ACL info of the original file.
+ The ACL info is also used to check if a file is read-only (when opening the
+file).
+
+ *read-only-share*
+When MS-Windows shares a drive on the network it can be marked as read-only.
+This means that even if the file read-only attribute is absent, and the ACL
+settings on NT network shared drives allow writing to the file, you can still
+not write to the file. Vim on Win32 platforms will detect read-only network
+drives and will mark the file as read-only. You will not be able to override
+it with |:write|.
+
+ *write-device*
+When the file name is actually a device name, Vim will not make a backup (that
+would be impossible). You need to use "!", since the device already exists.
+Example for Unix: >
+ :w! /dev/lpt0
+and for MS-DOS or MS-Windows: >
+ :w! lpt0
+For Unix a device is detected when the name doesn't refer to a normal file or
+a directory. A fifo or named pipe also looks like a device to Vim.
+For MS-DOS and MS-Windows the device is detected by its name:
+ AUX
+ CON
+ CLOCK$
+ NUL
+ PRN
+ COMn n=1,2,3... etc
+ LPTn n=1,2,3... etc
+The names can be in upper- or lowercase.
+
+==============================================================================
+5. Writing and quitting *write-quit*
+
+ *:q* *:quit*
+:q[uit] Quit the current window. Quit Vim if this is the last
+ window. This fails when changes have been made and
+ Vim refuses to |abandon| the current buffer, and when
+ the last file in the argument list has not been
+ edited.
+ If there are other tab pages and quitting the last
+ window in the current tab page the current tab page is
+ closed |tab-page|.
+ Triggers the |QuitPre| autocommand event.
+ See |CTRL-W_q| for quitting another window.
+
+:conf[irm] q[uit] Quit, but give prompt when changes have been made, or
+ the last file in the argument list has not been
+ edited. See |:confirm| and 'confirm'. {not in Vi}
+
+:q[uit]! Quit without writing, also when the current buffer has
+ changes. The buffer is unloaded, also when it has
+ 'hidden' set.
+ If this is the last window and there is a modified
+ hidden buffer, the current buffer is abandoned and the
+ first changed hidden buffer becomes the current
+ buffer.
+ Use ":qall!" to exit always.
+
+:cq[uit] Quit always, without writing, and return an error
+ code. See |:cq|. Used for Manx's QuickFix mode (see
+ |quickfix|). {not in Vi}
+
+ *:wq*
+:wq [++opt] Write the current file and quit. Writing fails when
+ the file is read-only or the buffer does not have a
+ name. Quitting fails when the last file in the
+ argument list has not been edited.
+
+:wq! [++opt] Write the current file and quit. Writing fails when
+ the current buffer does not have a name.
+
+:wq [++opt] {file} Write to {file} and quit. Quitting fails when the
+ last file in the argument list has not been edited.
+
+:wq! [++opt] {file} Write to {file} and quit.
+
+:[range]wq[!] [++opt] [file]
+ Same as above, but only write the lines in [range].
+
+ *:x* *:xit*
+:[range]x[it][!] [++opt] [file]
+ Like ":wq", but write only when changes have been
+ made.
+ When 'hidden' is set and there are more windows, the
+ current buffer becomes hidden, after writing the file.
+
+ *:exi* *:exit*
+:[range]exi[t][!] [++opt] [file]
+ Same as :xit.
+
+ *ZZ*
+ZZ Write current file, if modified, and quit (same as
+ ":x"). (Note: If there are several windows for the
+ current file, the file is written if it was modified
+ and the window is closed).
+
+ *ZQ*
+ZQ Quit without checking for changes (same as ":q!").
+ {not in Vi}
+
+MULTIPLE WINDOWS AND BUFFERS *window-exit*
+
+ *:qa* *:qall*
+:qa[ll] Exit Vim, unless there are some buffers which have been
+ changed. (Use ":bmod" to go to the next modified buffer).
+ When 'autowriteall' is set all changed buffers will be
+ written, like |:wqall|. {not in Vi}
+
+:conf[irm] qa[ll]
+ Exit Vim. Bring up a prompt when some buffers have been
+ changed. See |:confirm|. {not in Vi}
+
+:qa[ll]! Exit Vim. Any changes to buffers are lost. {not in Vi}
+ Also see |:cquit|, it does the same but exits with a non-zero
+ value.
+
+ *:quita* *:quitall*
+:quita[ll][!] Same as ":qall". {not in Vi}
+
+:wqa[ll] [++opt] *:wqa* *:wqall* *:xa* *:xall*
+:xa[ll] Write all changed buffers and exit Vim. If there are buffers
+ without a file name, which are readonly or which cannot be
+ written for another reason, Vim will not quit. {not in Vi}
+
+:conf[irm] wqa[ll] [++opt]
+:conf[irm] xa[ll]
+ Write all changed buffers and exit Vim. Bring up a prompt
+ when some buffers are readonly or cannot be written for
+ another reason. See |:confirm|. {not in Vi}
+
+:wqa[ll]! [++opt]
+:xa[ll]! Write all changed buffers, even the ones that are readonly,
+ and exit Vim. If there are buffers without a file name or
+ which cannot be written for another reason, or there is a
+ terminal with a running job, Vim will not quit.
+ {not in Vi}
+
+==============================================================================
+6. Dialogs *edit-dialogs*
+
+ *:confirm* *:conf*
+:conf[irm] {command} Execute {command}, and use a dialog when an
+ operation has to be confirmed. Can be used on the
+ |:q|, |:qa| and |:w| commands (the latter to override
+ a read-only setting), and any other command that can
+ fail in such a way, such as |:only|, |:buffer|,
+ |:bdelete|, etc.
+
+Examples: >
+ :confirm w foo
+< Will ask for confirmation when "foo" already exists. >
+ :confirm q
+< Will ask for confirmation when there are changes. >
+ :confirm qa
+< If any modified, unsaved buffers exist, you will be prompted to save
+ or abandon each one. There are also choices to "save all" or "abandon
+ all".
+
+If you want to always use ":confirm", set the 'confirm' option.
+
+ *:browse* *:bro* *E338* *E614* *E615* *E616*
+:bro[wse] {command} Open a file selection dialog for an argument to
+ {command}. At present this works for |:e|, |:w|,
+ |:wall|, |:wq|, |:wqall|, |:x|, |:xall|, |:exit|,
+ |:view|, |:sview|, |:r|, |:saveas|, |:sp|, |:mkexrc|,
+ |:mkvimrc|, |:mksession|, |:mkview|, |:split|,
+ |:vsplit|, |:tabe|, |:tabnew|, |:cfile|, |:cgetfile|,
+ |:caddfile|, |:lfile|, |:lgetfile|, |:laddfile|,
+ |:diffsplit|, |:diffpatch|, |:open|, |:pedit|,
+ |:redir|, |:source|, |:update|, |:visual|, |:vsplit|,
+ and |:qall| if 'confirm' is set.
+ {only in Win32, Athena, Motif, GTK and Mac GUI}
+ When ":browse" is not possible you get an error
+ message. If the |+browse| feature is missing or the
+ {command} doesn't support browsing, the {command} is
+ executed without a dialog.
+ ":browse set" works like |:options|.
+ See also |:oldfiles| for ":browse oldfiles".
+
+The syntax is best shown via some examples: >
+ :browse e $vim/foo
+< Open the browser in the $vim/foo directory, and edit the
+ file chosen. >
+ :browse e
+< Open the browser in the directory specified with 'browsedir',
+ and edit the file chosen. >
+ :browse w
+< Open the browser in the directory of the current buffer,
+ with the current buffer filename as default, and save the
+ buffer under the filename chosen. >
+ :browse w C:/bar
+< Open the browser in the C:/bar directory, with the current
+ buffer filename as default, and save the buffer under the
+ filename chosen.
+Also see the |'browsedir'| option.
+For versions of Vim where browsing is not supported, the command is executed
+unmodified.
+
+ *browsefilter*
+For MS Windows and GTK, you can modify the filters that are used in the browse
+dialog. By setting the g:browsefilter or b:browsefilter variables, you can
+change the filters globally or locally to the buffer. The variable is set to
+a string in the format "{filter label}\t{pattern};{pattern}\n" where {filter
+label} is the text that appears in the "Files of Type" comboBox, and {pattern}
+is the pattern which filters the filenames. Several patterns can be given,
+separated by ';'.
+
+For Motif the same format is used, but only the very first pattern is actually
+used (Motif only offers one pattern, but you can edit it).
+
+For example, to have only Vim files in the dialog, you could use the following
+command: >
+
+ let g:browsefilter = "Vim Scripts\t*.vim\nVim Startup Files\t*vimrc\n"
+
+You can override the filter setting on a per-buffer basis by setting the
+b:browsefilter variable. You would most likely set b:browsefilter in a
+filetype plugin, so that the browse dialog would contain entries related to
+the type of file you are currently editing. Disadvantage: This makes it
+difficult to start editing a file of a different type. To overcome this, you
+may want to add "All Files\t*.*\n" as the final filter, so that the user can
+still access any desired file.
+
+To avoid setting browsefilter when Vim does not actually support it, you can
+use has("browsefilter"): >
+
+ if has("browsefilter")
+ let g:browsefilter = "whatever"
+ endif
+
+==============================================================================
+7. The current directory *current-directory*
+
+You may use the |:cd| and |:lcd| commands to change to another directory, so
+you will not have to type that directory name in front of the file names. It
+also makes a difference for executing external commands, e.g. ":!ls".
+
+Changing directory fails when the current buffer is modified, the '.' flag is
+present in 'cpoptions' and "!" is not used in the command.
+
+ *:cd* *E747* *E472*
+:cd[!] On non-Unix systems: Print the current directory
+ name. On Unix systems: Change the current directory
+ to the home directory. Use |:pwd| to print the
+ current directory on all systems.
+
+:cd[!] {path} Change the current directory to {path}.
+ If {path} is relative, it is searched for in the
+ directories listed in |'cdpath'|.
+ Does not change the meaning of an already opened file,
+ because its full path name is remembered. Files from
+ the |arglist| may change though!
+ On MS-DOS this also changes the active drive.
+ To change to the directory of the current file: >
+ :cd %:h
+<
+ *:cd-* *E186*
+:cd[!] - Change to the previous current directory (before the
+ previous ":cd {path}" command). {not in Vi}
+
+ *:chd* *:chdir*
+:chd[ir][!] [path] Same as |:cd|.
+
+ *:lc* *:lcd*
+:lc[d][!] {path} Like |:cd|, but only set the current directory when
+ the cursor is in the current window. The current
+ directory for other windows is not changed, switching
+ to another window will stop using {path}.
+ {not in Vi}
+
+ *:lch* *:lchdir*
+:lch[dir][!] Same as |:lcd|. {not in Vi}
+
+ *:pw* *:pwd* *E187*
+:pw[d] Print the current directory name. {Vi: no pwd}
+ Also see |getcwd()|.
+
+So long as no |:lcd| command has been used, all windows share the same current
+directory. Using a command to jump to another window doesn't change anything
+for the current directory.
+When a |:lcd| command has been used for a window, the specified directory
+becomes the current directory for that window. Windows where the |:lcd|
+command has not been used stick to the global current directory. When jumping
+to another window the current directory will become the last specified local
+current directory. If none was specified, the global current directory is
+used.
+When a |:cd| command is used, the current window will lose his local current
+directory and will use the global current directory from now on.
+
+After using |:cd| the full path name will be used for reading and writing
+files. On some networked file systems this may cause problems. The result of
+using the full path name is that the file names currently in use will remain
+referring to the same file. Example: If you have a file a:test and a
+directory a:vim the commands ":e test" ":cd vim" ":w" will overwrite the file
+a:test and not write a:vim/test. But if you do ":w test" the file a:vim/test
+will be written, because you gave a new file name and did not refer to a
+filename before the ":cd".
+
+==============================================================================
+8. Editing binary files *edit-binary*
+
+Although Vim was made to edit text files, it is possible to edit binary
+files. The |-b| Vim argument (b for binary) makes Vim do file I/O in binary
+mode, and sets some options for editing binary files ('binary' on, 'textwidth'
+to 0, 'modeline' off, 'expandtab' off). Setting the 'binary' option has the
+same effect. Don't forget to do this before reading the file.
+
+There are a few things to remember when editing binary files:
+- When editing executable files the number of characters must not change.
+ Use only the "R" or "r" command to change text. Do not delete characters
+ with "x" or by backspacing.
+- Set the 'textwidth' option to 0. Otherwise lines will unexpectedly be
+ split in two.
+- When there are not many <EOL>s, the lines will become very long. If you
+ want to edit a line that does not fit on the screen reset the 'wrap' option.
+ Horizontal scrolling is used then. If a line becomes too long (more than
+ about 32767 characters on the Amiga, much more on 32-bit systems, see
+ |limits|) you cannot edit that line. The line will be split when reading
+ the file. It is also possible that you get an "out of memory" error when
+ reading the file.
+- Make sure the 'binary' option is set BEFORE loading the
+ file. Otherwise both <CR> <NL> and <NL> are considered to end a line
+ and when the file is written the <NL> will be replaced with <CR> <NL>.
+- <Nul> characters are shown on the screen as ^@. You can enter them with
+ "CTRL-V CTRL-@" or "CTRL-V 000" {Vi cannot handle <Nul> characters in the
+ file}
+- To insert a <NL> character in the file split a line. When writing the
+ buffer to a file a <NL> will be written for the <EOL>.
+- Vim normally appends an <EOL> at the end of the file if there is none.
+ Setting the 'binary' option prevents this. If you want to add the final
+ <EOL>, set the 'endofline' option. You can also read the value of this
+ option to see if there was an <EOL> for the last line (you cannot see this
+ in the text).
+
+==============================================================================
+9. Encryption *encryption*
+
+Vim is able to write files encrypted, and read them back. The encrypted text
+cannot be read without the right key.
+{only available when compiled with the |+cryptv| feature} *E833*
+
+The text in the swap file and the undo file is also encrypted. *E843*
+However, this is done block-by-block and may reduce the time needed to crack a
+password. You can disable the swap file, but then a crash will cause you to
+lose your work. The undo file can be disabled without too much disadvantage. >
+ :set noundofile
+ :noswapfile edit secrets
+
+Note: The text in memory is not encrypted. A system administrator may be able
+to see your text while you are editing it. When filtering text with
+":!filter" or using ":w !command" the text is also not encrypted, this may
+reveal it to others. The 'viminfo' file is not encrypted.
+
+You could do this to edit very secret text: >
+ :set noundofile viminfo=
+ :noswapfile edit secrets.txt
+Keep in mind that without a swap file you risk losing your work in the event
+of a crash or a power failure.
+
+WARNING: If you make a typo when entering the key and then write the file and
+exit, the text will be lost!
+
+The normal way to work with encryption, is to use the ":X" command, which will
+ask you to enter a key. A following write command will use that key to
+encrypt the file. If you later edit the same file, Vim will ask you to enter
+a key. If you type the same key as that was used for writing, the text will
+be readable again. If you use a wrong key, it will be a mess.
+
+ *:X*
+:X Prompt for an encryption key. The typing is done without showing the
+ actual text, so that someone looking at the display won't see it.
+ The typed key is stored in the 'key' option, which is used to encrypt
+ the file when it is written. The file will remain unchanged until you
+ write it. See also |-x|.
+
+The value of the 'key' options is used when text is written. When the option
+is not empty, the written file will be encrypted, using the value as the
+encryption key. A magic number is prepended, so that Vim can recognize that
+the file is encrypted.
+
+To disable the encryption, reset the 'key' option to an empty value: >
+ :set key=
+
+You can use the 'cryptmethod' option to select the type of encryption, use one
+of these: >
+ :setlocal cm=zip " weak method, backwards compatible
+ :setlocal cm=blowfish " method with flaws
+ :setlocal cm=blowfish2 " medium strong method
+
+Do this before writing the file. When reading an encrypted file it will be
+set automatically to the method used when that file was written. You can
+change 'cryptmethod' before writing that file to change the method.
+
+To set the default method, used for new files, use this in your |vimrc|
+file: >
+ set cm=blowfish2
+Using "blowfish2" is highly recommended. Only use another method if you
+must use an older Vim version that does not support it.
+
+The message given for reading and writing a file will show "[crypted]" when
+using zip, "[blowfish]" when using blowfish, etc.
+
+When writing an undo file, the same key and method will be used for the text
+in the undo file. |persistent-undo|.
+
+To test for blowfish support you can use these conditions: >
+ has('crypt-blowfish')
+ has('crypt-blowfish2')
+This works since Vim 7.4.1099 while blowfish support was added earlier.
+Thus the condition failing doesn't mean blowfish is not supported. You can
+test for blowfish with: >
+ v:version >= 703
+And for blowfish2 with: >
+ v:version > 704 || (v:version == 704 && has('patch401'))
+If you are sure Vim includes patch 7.4.237 a simpler check is: >
+ has('patch-7.4.401')
+<
+ *E817* *E818* *E819* *E820*
+When encryption does not work properly, you would be able to write your text
+to a file and never be able to read it back. Therefore a test is performed to
+check if the encryption works as expected. If you get one of these errors
+don't write the file encrypted! You need to rebuild the Vim binary to fix
+this.
+
+*E831* This is an internal error, "cannot happen". If you can reproduce it,
+please report to the developers.
+
+When reading a file that has been encrypted and the 'key' option is not empty,
+it will be used for decryption. If the value is empty, you will be prompted
+to enter the key. If you don't enter a key, or you enter the wrong key, the
+file is edited without being decrypted. There is no warning about using the
+wrong key (this makes brute force methods to find the key more difficult).
+
+If want to start reading a file that uses a different key, set the 'key'
+option to an empty string, so that Vim will prompt for a new one. Don't use
+the ":set" command to enter the value, other people can read the command over
+your shoulder.
+
+Since the value of the 'key' option is supposed to be a secret, its value can
+never be viewed. You should not set this option in a vimrc file.
+
+An encrypted file can be recognized by the "file" command, if you add these
+lines to "/etc/magic", "/usr/share/misc/magic" or wherever your system has the
+"magic" file: >
+ 0 string VimCrypt~ Vim encrypted file
+ >9 string 01 - "zip" cryptmethod
+ >9 string 02 - "blowfish" cryptmethod
+ >9 string 03 - "blowfish2" cryptmethod
+
+Notes:
+- Encryption is not possible when doing conversion with 'charconvert'.
+- Text you copy or delete goes to the numbered registers. The registers can
+ be saved in the .viminfo file, where they could be read. Change your
+ 'viminfo' option to be safe.
+- Someone can type commands in Vim when you walk away for a moment, he should
+ not be able to get the key.
+- If you make a typing mistake when entering the key, you might not be able to
+ get your text back!
+- If you type the key with a ":set key=value" command, it can be kept in the
+ history, showing the 'key' value in a viminfo file.
+- There is never 100% safety. The encryption in Vim has not been tested for
+ robustness.
+- The algorithm used for 'cryptmethod' "zip" is breakable. A 4 character key
+ in about one hour, a 6 character key in one day (on a Pentium 133 PC). This
+ requires that you know some text that must appear in the file. An expert
+ can break it for any key. When the text has been decrypted, this also means
+ that the key can be revealed, and other files encrypted with the same key
+ can be decrypted.
+- Pkzip uses the same encryption as 'cryptmethod' "zip", and US Govt has no
+ objection to its export. Pkzip's public file APPNOTE.TXT describes this
+ algorithm in detail.
+- The implementation of 'cryptmethod' "blowfish" has a flaw. It is possible
+ to crack the first 64 bytes of a file and in some circumstances more of the
+ file. Use of it is not recommended, but it's still the strongest method
+ supported by Vim 7.3 and 7.4. The "zip" method is even weaker.
+- Vim originates from the Netherlands. That is where the sources come from.
+ Thus the encryption code is not exported from the USA.
+
+==============================================================================
+10. Timestamps *timestamp* *timestamps*
+
+Vim remembers the modification timestamp, mode and size of a file when you
+begin editing it. This is used to avoid that you have two different versions
+of the same file (without you knowing this).
+
+After a shell command is run (|:!cmd| |suspend| |:read!| |K|) timestamps,
+file modes and file sizes are compared for all buffers in a window. Vim will
+run any associated |FileChangedShell| autocommands or display a warning for
+any files that have changed. In the GUI this happens when Vim regains input
+focus.
+
+ *E321* *E462*
+If you want to automatically reload a file when it has been changed outside of
+Vim, set the 'autoread' option. This doesn't work at the moment you write the
+file though, only when the file wasn't changed inside of Vim.
+
+If you do not want to be asked or automatically reload the file, you can use
+this: >
+ set buftype=nofile
+
+Or, when starting gvim from a shell: >
+ gvim file.log -c "set buftype=nofile"
+
+Note that if a FileChangedShell autocommand is defined you will not get a
+warning message or prompt. The autocommand is expected to handle this.
+
+There is no warning for a directory (e.g., with |netrw-browse|). But you do
+get warned if you started editing a new file and it was created as a directory
+later.
+
+When Vim notices the timestamp of a file has changed, and the file is being
+edited in a buffer but has not changed, Vim checks if the contents of the file
+is equal. This is done by reading the file again (into a hidden buffer, which
+is immediately deleted again) and comparing the text. If the text is equal,
+you will get no warning.
+
+If you don't get warned often enough you can use the following command.
+
+ *:checkt* *:checktime*
+:checkt[ime] Check if any buffers were changed outside of Vim.
+ This checks and warns you if you would end up with two
+ versions of a file.
+ If this is called from an autocommand, a ":global"
+ command or is not typed the actual check is postponed
+ until a moment the side effects (reloading the file)
+ would be harmless.
+ Each loaded buffer is checked for its associated file
+ being changed. If the file was changed Vim will take
+ action. If there are no changes in the buffer and
+ 'autoread' is set, the buffer is reloaded. Otherwise,
+ you are offered the choice of reloading the file. If
+ the file was deleted you get an error message.
+ If the file previously didn't exist you get a warning
+ if it exists now.
+ Once a file has been checked the timestamp is reset,
+ you will not be warned again.
+
+:[N]checkt[ime] {filename}
+:[N]checkt[ime] [N]
+ Check the timestamp of a specific buffer. The buffer
+ may be specified by name, number or with a pattern.
+
+
+ *E813* *E814*
+Vim will reload the buffer if you chose to. If a window is visible that
+contains this buffer, the reloading will happen in the context of this window.
+Otherwise a special window is used, so that most autocommands will work. You
+can't close this window. A few other restrictions apply. Best is to make
+sure nothing happens outside of the current buffer. E.g., setting
+window-local options may end up in the wrong window. Splitting the window,
+doing something there and closing it should be OK (if there are no side
+effects from other autocommands). Closing unrelated windows and buffers will
+get you into trouble.
+
+Before writing a file the timestamp is checked. If it has changed, Vim will
+ask if you really want to overwrite the file:
+
+ WARNING: The file has been changed since reading it!!!
+ Do you really want to write to it (y/n)?
+
+If you hit 'y' Vim will continue writing the file. If you hit 'n' the write is
+aborted. If you used ":wq" or "ZZ" Vim will not exit, you will get another
+chance to write the file.
+
+The message would normally mean that somebody has written to the file after
+the edit session started. This could be another person, in which case you
+probably want to check if your changes to the file and the changes from the
+other person should be merged. Write the file under another name and check for
+differences (the "diff" program can be used for this).
+
+It is also possible that you modified the file yourself, from another edit
+session or with another command (e.g., a filter command). Then you will know
+which version of the file you want to keep.
+
+There is one situation where you get the message while there is nothing wrong:
+On a Win32 system on the day daylight saving time starts. There is something
+in the Win32 libraries that confuses Vim about the hour time difference. The
+problem goes away the next day.
+
+==============================================================================
+11. File Searching *file-searching*
+
+{not available when compiled without the |+path_extra| feature}
+
+The file searching is currently used for the 'path', 'cdpath' and 'tags'
+options, for |finddir()| and |findfile()|. Other commands use |wildcards|
+which is slightly different.
+
+There are three different types of searching:
+
+1) Downward search: *starstar*
+ Downward search uses the wildcards '*', '**' and possibly others
+ supported by your operating system. '*' and '**' are handled inside Vim,
+ so they work on all operating systems. Note that "**" only acts as a
+ special wildcard when it is at the start of a name.
+
+ The usage of '*' is quite simple: It matches 0 or more characters. In a
+ search pattern this would be ".*". Note that the "." is not used for file
+ searching.
+
+ '**' is more sophisticated:
+ - It ONLY matches directories.
+ - It matches up to 30 directories deep by default, so you can use it to
+ search an entire directory tree
+ - The maximum number of levels matched can be given by appending a number
+ to '**'.
+ Thus '/usr/**2' can match: >
+ /usr
+ /usr/include
+ /usr/include/sys
+ /usr/include/g++
+ /usr/lib
+ /usr/lib/X11
+ ....
+< It does NOT match '/usr/include/g++/std' as this would be three
+ levels.
+ The allowed number range is 0 ('**0' is removed) to 100
+ If the given number is smaller than 0 it defaults to 30, if it's
+ bigger than 100 then 100 is used. The system also has a limit on the
+ path length, usually 256 or 1024 bytes.
+ - '**' can only be at the end of the path or be followed by a path
+ separator or by a number and a path separator.
+
+ You can combine '*' and '**' in any order: >
+ /usr/**/sys/*
+ /usr/*tory/sys/**
+ /usr/**2/sys/*
+
+2) Upward search:
+ Here you can give a directory and then search the directory tree upward for
+ a file. You could give stop-directories to limit the upward search. The
+ stop-directories are appended to the path (for the 'path' option) or to
+ the filename (for the 'tags' option) with a ';'. If you want several
+ stop-directories separate them with ';'. If you want no stop-directory
+ ("search upward till the root directory) just use ';'. >
+ /usr/include/sys;/usr
+< will search in: >
+ /usr/include/sys
+ /usr/include
+ /usr
+<
+ If you use a relative path the upward search is started in Vim's current
+ directory or in the directory of the current file (if the relative path
+ starts with './' and 'd' is not included in 'cpoptions').
+
+ If Vim's current path is /u/user_x/work/release and you do >
+ :set path=include;/u/user_x
+< and then search for a file with |gf| the file is searched in: >
+ /u/user_x/work/release/include
+ /u/user_x/work/include
+ /u/user_x/include
+
+3) Combined up/downward search:
+ If Vim's current path is /u/user_x/work/release and you do >
+ set path=**;/u/user_x
+< and then search for a file with |gf| the file is searched in: >
+ /u/user_x/work/release/**
+ /u/user_x/work/**
+ /u/user_x/**
+<
+ BE CAREFUL! This might consume a lot of time, as the search of
+ '/u/user_x/**' includes '/u/user_x/work/**' and
+ '/u/user_x/work/release/**'. So '/u/user_x/work/release/**' is searched
+ three times and '/u/user_x/work/**' is searched twice.
+
+ In the above example you might want to set path to: >
+ :set path=**,/u/user_x/**
+< This searches:
+ /u/user_x/work/release/** ~
+ /u/user_x/** ~
+ This searches the same directories, but in a different order.
+
+ Note that completion for ":find", ":sfind", and ":tabfind" commands do not
+ currently work with 'path' items that contain a URL or use the double star
+ with depth limiter (/usr/**2) or upward search (;) notations.
+
+ vim:tw=78:ts=8:noet:ft=help:norl: