Vim documentation: editing
main help file
*editing.txt* For Vim version 5.8. Last change: 2001 Jan 18
VIM REFERENCE MANUAL by Bram Moolenaar
Editing files *edit-files*
1. Introduction |edit-intro|
2. Editing a file |edit-a-file|
3. The current directory |current-directory|
4. The argument list |argument-list|
5. Writing and quitting |write-quit|
6. Editing binary files |edit-binary|
7. Encryption |encryption|
==============================================================================
1. Introduction *edit-intro*
Editing a file with Vim means:
1. reading the file into the internal 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".
*alternate-file*
If there already was a current file name, then that one becomes the alternate
file name. All file names are remembered in the file list. When you enter a
file name, for editing (e.g., with ":e filename") or writing (e.g., with (:w
file name"), the file name is added to the list. You can use this list to
remember which files you edited and to quickly switch from one file to
another with the CTRL-^ command (e.g., to copy text). First type the number
of the file and then hit CTRL-^. {Vi: only one alternate file name}
CTRL-G or *CTRL-G* *:f* *:fi* *:file*
:f[ile] Prints the current file name (as typed), 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 tho
make this message shorter. {Vi does not include
column number}
{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*
g CTRL-G Prints the current position of the cursor in three
ways: Column, Line and Character. 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. See also 'ruler'
option. {not in Vi}
*:file_f*
:f[ile] {name} Sets the current file name to {name}.
: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
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). 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) 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.
*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.
If you want to automatically save the changes without asking, switch on the
'autowrite' option. Note that ":e file" will fail if there are changes in the
current buffer, also when the 'autowrite' option is on. This is illogical,
because with other commands (e.g., ":next") the current buffer would be
written and abandoned, but this behavior is compatible with Vi. If you
encounter this problem, you can use CTRL-^ to jump to the file, because the
alternate file name is set to the argument of the ":e" command.
If you want to keep the changed buffer without saving it, switch on the
'hidden' option. See |hidden-buffer|.
*: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 over-ride
a read-only setting).
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*
:bro[wse] {command} Open a file selection dialog for an argument to
{command}. At present this works for ":e", ":w",
":r", ":sp", ":mkexrc", ":mkvimrc" and ":mksession".
{only in Win32, Motif and Athena GUI}
When ":browse" is not supported it's ignored,
{command} is executed without a dialog.
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 of the current buffer,
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.
==============================================================================
2. Editing a file *edit-a-file*
*:e* *:edit*
:e[dit] [+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. Also see |+cmd|.
*:edit!*
:e[dit]! [+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 |+cmd|.
*:edit_f*
:e[dit] [+cmd] {file} Edit {file}. This fails when changes have been made
to the current buffer, unless 'hidden' is set. Also
see |+cmd|.
*:edit!_f*
:e[dit]! [+cmd] {file} Edit {file} always. Discard any changes to the
current buffer. Also see |+cmd|.
:e[dit] [+cmd] #[count] Edit the [count]th alternate file name (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 |+cmd|.
*:fin* *:find*
:fin[d][!] [+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}
*:ex*
:ex [+cmd] [file] Same as :edit, but also switch to "Ex" mode. See
|Ex-mode|.
*:vi* *:visual*
:vi[sual][!] [+cmd] [file]
When entered in Ex mode: Leave Ex mode, go back to
Normal mode. Otherwise same as :edit.
*:vie* *:view*
:vie[w] [+cmd] file When entered 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-^*
[count]CTRL-^ Edit [count]th alternate file (equivalent to ":e
#[count]"). Without count this gets you to the
previously edited file. This is a quick way to
toggle between two (or more) files. If the
'autowrite' option is on and the buffer was
changed, write it.
[count]]f *]f* *[f*
[count][f Same as "gf". Deprecated.
*gf*
[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.
Uses the 'path' variable as a list of directory names
to look for the file. Also looks for the file
relative to the current file.
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 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", only "/path" is used.
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}
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|.
*:filename*
Note for systems other than Unix and MS-DOS: 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
allow file names with embedded spaces (like 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.
On Unix you can also use backticks in the file name, for example:
:e `find . -name ver\\*.c -print`
The backslashes before the star are required to prevent "ver*.c" to be
expanded by the shell before executing the find program.
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 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.
*+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. To end with a backslash, use a double backslash.
:edit +/The\ book file
:edit +/dir\ dirname\\ file
*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 current directory *current-directory*
*:cd*
:cd On non-Unix systems: Print the current directory
name. On Unix systems: Change the current directory
to the home directory.
:cd {path} Change the current directory to {path}. Does not
change the meaning of an already entered file name,
because its full path name is remembered. On MS-DOS
this also changes the active drive.
*:cd-*
:cd - Change to the previous current directory (before the
previous ":cd {path}" command).
*:chd* *:chdir*
:chd[ir] [path] Same as :cd.
*:pw* *:pwd*
:pw[d] Print the current directory name. {Vi: no pwd}
Also see |getcwd()|.
You may use the |:cd| command to get to another directory, so you will not
have to type that directory name in front of the file names. One warning:
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".
==============================================================================
4. 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. Do not confuse this with the file list,
which you can see with the ":files" command |:files|. The argument list was
already present in Vi, the file list is new in Vim. The file names in the
argument list will also be present in the file list (unless they were
deleted with ":bdel").
You can use the argument list with the following commands, and with the
expression functions |argc()| and |argv()|.
*:ar* *:args*
:ar[gs] Print the argument list, with the current file in
square brackets.
*:argu* *:argument*
:[count]argu[ment] [count] [+cmd]
Edit file [count] in the argument list. This fails
when changes have been made and Vim does not want to
|abandon| the current buffer. Also see |+cmd|. {Vi:
no such command}
:[count]argu[ment]! [count] [+cmd]
Edit file [count] in the argument list, discard any
changes to the current buffer. Also see |+cmd|. {Vi:
no such command}
*:n* *:ne* *:next*
:[count]n[ext] [+cmd] Edit [count] next file. This fails when changes have
been made and Vim does not want to |abandon| the
current buffer. Also see |+cmd|. {Vi: no count}.
:[count]n[ext]! [+cmd] Edit [count] next file, discard any changes to the
buffer. Also see |+cmd|. {Vi: no count}.
:ar[gs] [+cmd] {arglist}
:n[ext] [+cmd] {arglist}
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 |+cmd|.
:ar[gs]! [+cmd] {arglist}
:n[ext]! [+cmd] {arglist} *:next_f*
Define {arglist} as the new argument list and edit
the first one. Discard any changes to the buffer.
Also see |+cmd|.
:[count]N[ext] [count] [+cmd] *:Next* *:N*
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 |+cmd|. {Vi: no count}.
:[count]N[ext]! [count] [+cmd]
Edit [count] previous file in argument list. Discard
any changes to the buffer. Also see |+cmd|. {Vi: no
count}.
:[count]prev[ious] [count] [+cmd] *:prev* *:previous*
Same as :Next. Also see |+cmd|. {Vi: only in some
versions}
*:rew* *:rewind*
:rew[ind] [+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 |+cmd|.
:rew[ind]! [+cmd] Start editing the first file in the argument list.
Discard any changes to the buffer. Also see |+cmd|.
*:la* *:last*
:la[st] [+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 |+cmd|. {not in Vi}
:la[st]! [+cmd] Start editing the last file in the argument list.
Discard any changes to the buffer. Also see |+cmd|.
{not in Vi}
*:wn* *:wnext*
:[count]wn[ext] [+cmd] Write current file and start editing the [count]
next file. Also see |+cmd|. {not in Vi}
:[count]wn[ext] [+cmd] {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 |+cmd|. {not
in Vi}
:[count]wn[ext]! [+cmd] {file}
Write current file to {file} and start editing the
[count] next file. Also see |+cmd|. {not in Vi}
:[count]wN[ext][!] [+cmd] [file] *:wN* *:wNext*
:[count]wp[revous][!] [+cmd] [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).
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. On Unix you can also use backticks,
for example:
:n `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-quit*
You are protected from leaving Vim if you have not been editing the last file
in the argument list. This prevents you from forgetting that you were editing
one out of several files. To exit anyway try to exit twice. If there are
changes in the current buffer this will fail. You can exit anyway, and save
any changes, with the ":wq!" command. To lose any changes use the ":q!"
command.
*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".
==============================================================================
5. Writing and quitting *write-quit* *save-file*
Note: When the 'write' option is off, you are not able to write any file.
*:w* *:write*
:[range]w[rite][!] Write the specified lines to the current file.
*:w_f* *:write_f*
:[range]w[rite] {file} Write the specified lines to {file}, unless it
already exists and the 'writeany' option is off.
*:w!*
:[range]w[rite]! {file} Write the specified lines to {file}. Overwrite an
existing file.
*:w_a* *:write_a*
:[range]w[rite][!] >> Append the specified lines to the current file.
:[range]w[rite][!] >> {file}
Append the specified lines to {file}. '!' forces the
write even if file does not exist.
*:w_c* *:write_c*
:[range]w[rite] !{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 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.
*:up* *:update*
:[range]up[date][!] [>>] [file]
Like ":write", but only write when the buffer has been
modified. {not in Vi}
*:q* *:quit*
:q[uit] Quit Vim. This fails when changes have been made and
Vim refuses to |abandon| the current buffer, and when
not editing the last file in the argument list.
:conf[irm] q[uit] Quit, but give prompt when changes have been made, or
not editing the last file in the argument list. See
|:confirm| and 'confirm'. {not in Vi}
:q[uit]! Quit without writing, also when visible buffers have
changes. Does not exit when there are changed hidden
buffers. 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 Write the current file and exit (unless editing the
last file in the argument list or the file is
read-only).
:wq! Write the current file and exit.
:wq {file} Write to {file}. Exit if not editing the last
file in the argument list.
:wq! {file} Write to {file} and exit.
:[range]wq[!] [file] Same as above, but only write the lines in [range].
*:x* *:xit*
:[range]x[it][!] [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][!] [file]
Same as :xit.
*ZZ*
ZZ Write current file, if modified, and exit (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 current file and exit (same as ":q!"). (Note: If
there are several windows for the current file, only
the window is closed).
*timestamp*
Vim remembers the modification timestamp of a file when you begin editing it.
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.
Alternatively, after a shell command is run (|:!cmd| |suspend| |:read!| |K|)
ALL timestamps are compared. Vim will run any associated |FileChangedShell|
autocommands or display the above WARNING for any files that have changed.
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.
*backup*
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. On Unix systems the file is copied, on other systems the file is
renamed. 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 '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.
The directories given with the 'backupdir' option is used to put the backup
file in. (default: same directory as the written file).
On Unix systems:
When you write to an existing file, that file is truncated and then filled
with the new text. This means that protection bits, owner and symbolic links
are unmodified. The backup file however, is a new file, owned by the user who
edited the file. The group of the backup is set to the group of the original
file. If this fails, the protection bits for the group are made the same as
for others.
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-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.
==============================================================================
6. 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 up 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).
==============================================================================
7. Encryption *encryption*
Vim is able to write files encrypted, and read them back. The encrypted text
cannot be read without the right key.
Note: The swapfile and text in memory are not encrypted. A system
administrator will be able to see your text while you are editing it.
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. 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=
When reading a file that has been encrypted and this 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, the file is edited without being
decrypted.
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 this
line to "/etc/magic", "/usr/share/misc/magic" or wherever your system has the
"magic" file:
0 string VimCrypt~ Vim encrypted file
Notes:
- 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 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.
- Pkzip uses the same encryption, and US Govt has no objection to its export.
Pkzip's public file APPNOTE.TXT describes this algorithm in detail.
- Vim originates from the Netherlands. That is where the sources come from.
Thus the encryption code is not exported from the USA.
top - main help file