| blob | 1b51b2c0c63bc046fb5560728d423462691ad254 |
1 *editing.txt* For Vim version 5.8. Last change: 2001 Jan 18
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Editing files *edit-files*
9 1. Introduction |edit-intro|
10 2. Editing a file |edit-a-file|
11 3. The current directory |current-directory|
12 4. The argument list |argument-list|
13 5. Writing and quitting |write-quit|
14 6. Editing binary files |edit-binary|
15 7. Encryption |encryption|
17 ==============================================================================
18 1. Introduction *edit-intro*
20 Editing a file with Vim means:
22 1. reading the file into the internal buffer
23 2. changing the buffer with editor commands
24 3. writing the buffer into a file
26 *current-file*
27 As long as you don't write the buffer, the original file remains unchanged.
28 If you start editing a file (read a file into the buffer), the file name is
29 remembered as the "current file name".
31 *alternate-file*
32 If there already was a current file name, then that one becomes the alternate
33 file name. All file names are remembered in the file list. When you enter a
34 file name, for editing (e.g., with ":e filename") or writing (e.g., with (:w
35 file name"), the file name is added to the list. You can use this list to
36 remember which files you edited and to quickly switch from one file to
37 another with the CTRL-^ command (e.g., to copy text). First type the number
38 of the file and then hit CTRL-^. {Vi: only one alternate file name}
40 CTRL-G or *CTRL-G* *:f* *:fi* *:file*
41 :f[ile] Prints the current file name (as typed), the
42 cursor position (unless the 'ruler' option is set),
43 and the file status (readonly, modified, read errors,
44 new file)). See the 'shortmess' option about how tho
45 make this message shorter. {Vi does not include
46 column number}
48 {count}CTRL-G Like CTRL-G, but prints the current file name with
49 full path. If the count is higher than 1 the current
50 buffer number is also given. {not in Vi}
52 *g_CTRL-G*
53 g CTRL-G Prints the current position of the cursor in three
54 ways: Column, Line and Character. If there are
55 characters in the line that take more than one
56 position on the screen (<Tab> or special character),
57 both the "real" column and the screen column are
58 shown, separated with a dash. See also 'ruler'
59 option. {not in Vi}
61 *:file_f*
62 :f[ile] {name} Sets the current file name to {name}.
64 :buffers
65 :files
66 :ls List all the currently known file names. See
67 'windows.txt' |:files| |:buffers| |:ls|. {not in
68 Vi}
70 Vim will remember the full path name of a file name that you enter. In most
71 cases when the file name is displayed only the name you typed is shown, but
72 the full path name is being used if you used the ":cd" command |:cd|.
74 *home-replace*
75 If the environment variable $HOME is set, and the file name starts with that
76 string, it is often displayed with HOME replaced with "~". This was done to
77 keep file names short. When reading or writing files the full name is still
78 used, the "~" is only used when displaying file names. When replacing the
79 file name would result in just "~", "~/" is used instead (to avoid confusion
80 with 'backupext' set to "~").
82 When writing the buffer, the default is to use the current file name. Thus
83 when you give the "ZZ" or ":wq" command, the original file will be
84 overwritten. If you do not want this, the buffer can be written into another
85 file by giving a file name argument to the ":write" command. For example:
87 > vim testfile
88 > [change the buffer with editor commands]
89 > :w newfile
90 > :q
92 This will create a file "newfile", that is a modified copy of "testfile".
93 The file "testfile" will remain unchanged. Anyway, if the 'backup' option is
94 set, Vim renames or copies the original file before it will be overwritten.
95 You can use this file if you discover that you need the original file. See
96 also the 'patchmode' option. The name of the backup file is normally the same
97 as the original file with 'backupext' appended. The default "~" is a bit
98 strange to avoid accidentally overwriting existing files. If you prefer ".bak"
99 change the 'backupext' option. Extra dots are replaced with '_' on MS-DOS
100 machines, when Vim has detected that an MS-DOS-like filesystem is being used
101 (e.g., messydos or crossdos) or when the 'shortname' option is on. The
102 backup file can be placed in another directory by setting 'backupdir'.
104 *auto-shortname*
105 Technical: On the Amiga you can use 30 characters for a file name. But on an
106 MS-DOS-compatible filesystem only 8 plus 3 characters are
107 available. Vim tries to detect the type of filesystem when it is
108 creating the .swp file. If an MS-DOS-like filesystem is suspected,
109 a flag is set that has the same effect as setting the 'shortname'
110 option. This flag will be reset as soon as you start editing a
111 new file. The flag will be used when making the file name for the
112 ".swp" and ".~" files for the current file. But when you are
113 editing a file in a normal filesystem and write to an MS-DOS-like
114 filesystem the flag will not have been set. In that case the
115 creation of the ".~" file may fail and you will get an error
116 message. Use the 'shortname' option in this case.
118 When you started editing without giving a file name, "No File" is displayed in
119 messages. If the ":write" command is used with a file name argument, the file
120 name for the current file is set to that file name. This only happens when
121 the 'F' flag is included in 'cpoptions' (by default it is included). This is
122 useful when entering text in an empty buffer and then writing it to a file.
123 If 'cpoptions' contains the 'f' flag (by default it is NOT included) the file
124 name is set for the ":read file" command. This is useful when starting Vim
125 without an argument and then doing ":read file" to start editing a file.
126 *not-edited*
127 Because the file name was set without really starting to edit that file, you
128 are protected from overwriting that file. This is done by setting the
129 "notedited" flag. You can see if this flag is set with the CTRL-G or ":file"
130 command. It will include "[Not edited]" when the "notedited" flag is set.
131 When writing the buffer to the current file name (with ":w!"), the "notedited"
132 flag is reset.
134 *abandon*
135 Vim remembers whether you have changed the buffer. You are protected from
136 losing the changes you made. If you try to quit without writing, or want to
137 start editing another file, Vim will refuse this. In order to overrule this
138 protection, add a '!' to the command. The changes will then be lost. For
139 example: ":q" will not work if the buffer was changed, but ":q!" will. To see
140 whether the buffer was changed use the "CTRL-G" command. The message includes
141 the string "[Modified]" if the buffer has been changed.
143 If you want to automatically save the changes without asking, switch on the
144 'autowrite' option. Note that ":e file" will fail if there are changes in the
145 current buffer, also when the 'autowrite' option is on. This is illogical,
146 because with other commands (e.g., ":next") the current buffer would be
147 written and abandoned, but this behavior is compatible with Vi. If you
148 encounter this problem, you can use CTRL-^ to jump to the file, because the
149 alternate file name is set to the argument of the ":e" command.
151 If you want to keep the changed buffer without saving it, switch on the
152 'hidden' option. See |hidden-buffer|.
154 *:confirm* *:conf*
155 :conf[irm] {command} Execute {command}, and use a dialog when an
156 operation has to be confirmed. Can be used on the
157 ":q", ":qa" and ":w" commands (the latter to over-ride
158 a read-only setting).
160 Examples:
161 > :confirm w foo
162 Will ask for confirmation when "foo" already exists.
163 > :confirm q
164 Will ask for confirmation when there are changes.
165 > :confirm qa
166 If any modified, unsaved buffers exist, you will be prompted to save
167 or abandon each one. There are also choices to "save all" or "abandon
168 all".
170 If you want to always use ":confirm", set the 'confirm' option.
172 *:browse* *:bro*
173 :bro[wse] {command} Open a file selection dialog for an argument to
174 {command}. At present this works for ":e", ":w",
175 ":r", ":sp", ":mkexrc", ":mkvimrc" and ":mksession".
176 {only in Win32, Motif and Athena GUI}
177 When ":browse" is not supported it's ignored,
178 {command} is executed without a dialog.
180 The syntax is best shown via some examples:
181 > :browse e $vim/foo
182 Open the browser in the $vim/foo directory, and edit the
183 file chosen.
184 > :browse e
185 Open the browser in the directory of the current buffer,
186 and edit the file chosen.
187 > :browse w
188 Open the browser in the directory of the current buffer,
189 with the current buffer filename as default, and save the
190 buffer under the filename chosen.
191 > :browse w C:/bar
192 Open the browser in the C:/bar directory, with the current
193 buffer filename as default, and save the buffer under the
194 filename chosen.
195 Also see the |'browsedir'| option.
196 For versions of Vim where browsing is not supported, the command is executed
197 unmodified.
199 ==============================================================================
200 2. Editing a file *edit-a-file*
202 *:e* *:edit*
203 :e[dit] [+cmd] Edit the current file. This is useful to re-edit the
204 current file, when it has been changed outside of Vim.
205 This fails when changes have been made to the current
206 buffer. Also see |+cmd|.
208 *:edit!*
209 :e[dit]! [+cmd] Edit the current file always. Discard any changes to
210 the current buffer. This is useful if you want to
211 start all over again. Also see |+cmd|.
213 *:edit_f*
214 :e[dit] [+cmd] {file} Edit {file}. This fails when changes have been made
215 to the current buffer, unless 'hidden' is set. Also
216 see |+cmd|.
218 *:edit!_f*
219 :e[dit]! [+cmd] {file} Edit {file} always. Discard any changes to the
220 current buffer. Also see |+cmd|.
222 :e[dit] [+cmd] #[count] Edit the [count]th alternate file name (as shown by
223 :files). This command does the same as
224 [count] CTRL-^. But ":e #" doesn't work if the
225 alternate buffer doesn't have a file name, while
226 CTRL-^ still works then. Also see |+cmd|.
228 *:fin* *:find*
229 :fin[d][!] [+cmd] {file}
230 Find {file} in 'path' and then ":edit" it.
231 {not in Vi} {not available when the |+file_in_path|
232 feature was disabled at compile time}
234 *:ex*
235 :ex [+cmd] [file] Same as :edit, but also switch to "Ex" mode. See
236 |Ex-mode|.
238 *:vi* *:visual*
239 :vi[sual][!] [+cmd] [file]
240 When entered in Ex mode: Leave Ex mode, go back to
241 Normal mode. Otherwise same as :edit.
243 *:vie* *:view*
244 :vie[w] [+cmd] file When entered in Ex mode: Leave Ex mode, go back to
245 Normal mode. Otherwise same as :edit, but set
246 'readonly' option for this buffer. {not in Vi}
248 *CTRL-^*
249 [count]CTRL-^ Edit [count]th alternate file (equivalent to ":e
250 #[count]"). Without count this gets you to the
251 previously edited file. This is a quick way to
252 toggle between two (or more) files. If the
253 'autowrite' option is on and the buffer was
254 changed, write it.
256 [count]]f *]f* *[f*
257 [count][f Same as "gf". Deprecated.
259 *gf*
260 [count]gf Edit the file whose name is under or after the cursor.
261 Mnemonic: "goto file".
262 Uses the 'isfname' option to find out which characters
263 are supposed to be in a file name.
264 Uses the 'path' variable as a list of directory names
265 to look for the file. Also looks for the file
266 relative to the current file.
267 If a [count] is given, the count'th file that is found
268 in the 'path' is edited.
269 This command fails if Vim refuses to |abandon| the
270 current file.
271 If you do want to edit a new file, use:
272 > :e <cfile>
273 To make gf always work like that:
274 > :map gf :e <cfile><CR>
275 If the name is a hypertext link, that looks like
276 "type://machine/path", only "/path" is used.
277 For Unix the '~' character is expanded, like in
278 "~user/file". Environment variables are expanded too
279 |expand-env|.
280 {not in Vi}
281 {not available when the |+file_in_path| feature was
282 disabled at compile time}
284 These commands are used to start editing a single file. This means that the
285 file is read into the buffer and the current file name is set. The file that
286 is opened depends on the current directory, see |:cd|.
288 *:filename*
289 Note for systems other than Unix and MS-DOS: When using a command that
290 accepts a single file name (like ":edit file") spaces in the file name are
291 allowed, but trailing spaces are ignored. This is useful on systems that
292 allow file names with embedded spaces (like the Amiga). Example: The command
293 ":e Long File Name " will edit the file "Long File Name". When using a
294 command that accepts more than one file name (like ":next file1 file2")
295 embedded spaces must be escaped with a backslash.
297 On Unix you can also use backticks in the file name, for example:
298 > :e `find . -name ver\\*.c -print`
299 The backslashes before the star are required to prevent "ver*.c" to be
300 expanded by the shell before executing the find program.
301 This also works for most other systems, with the restriction that the
302 backticks must be around the whole item. It is not possible to have text
303 directly before the first or just after the last backtick.
305 You can use the ":e!" command if you messed up the buffer and want to start
306 all over again. The ":e" command is only useful if you have changed the
307 current file name.
309 *+cmd* *[+cmd]*
310 The [+cmd] argument can be used to position the cursor in the newly opened
311 file, or execute any other command:
312 + Start at the last line.
313 +{num} Start at line {num}.
314 +/{pat} Start at first line containing {pat}.
315 +{command} Execute {command} after opening the new file.
316 {command} is any Ex command.
317 To include a white space in the {pat} or {command}, precede it with a
318 backslash. To end with a backslash, use a double backslash.
319 :edit +/The\ book file
320 :edit +/dir\ dirname\\ file
322 *file-formats*
323 The 'fileformat' option sets the <EOL> style for a file:
324 'fileformat' characters name ~
325 "dos" <CR><NL> or <NL> DOS format *DOS-format*
326 "unix" <NL> Unix format *Unix-format*
327 "mac" <CR> Mac format *Mac-format*
328 Previously 'textmode' was used. It is obsolete now.
330 When reading a file, the mentioned characters are interpreted as the <EOL>.
331 In DOS format (default for MS-DOS, OS/2 and Win32), <CR><NL> and <NL> are both
332 interpreted as the <EOL>. Note that when writing the file in DOS format,
333 <CR> characters will be added for each single <NL>. Also see |file-read|.
335 When writing a file, the mentioned characters are used for <EOL>. For DOS
336 format <CR><NL> is used. Also see |DOS-format-write|.
338 You can read a file in DOS format and write it in Unix format. This will
339 replace all <CR><NL> pairs by <NL> (assuming 'fileformats' includes "dos"):
340 > :e file
341 > :set fileformat=unix
342 > :w
343 If you read a file in Unix format and write with DOS format, all <NL>
344 characters will be replaced with <CR><NL> (assuming 'fileformats' includes
345 "unix"):
346 > :e file
347 > :set fileformat=dos
348 > :w
350 If you start editing a new file and the 'fileformats' option is not empty
351 (which is the default), Vim will try to detect whether the lines in the file
352 are separated by the specified formats. When set to "unix,dos", Vim will
353 check for lines with a single <NL> (as used on Unix and Amiga) or by a <CR>
354 <NL> pair (MS-DOS). Only when ALL lines end in <CR><NL>, 'fileformat' is set
355 to "dos", otherwise it is set to "unix". When 'fileformats' includes "mac",
356 and no <NL> characters are found in the file, 'fileformat' is set to "mac".
358 If the 'fileformat' option is set to "dos" on non-MS-DOS systems the message
359 "[dos format]" is shown to remind you that something unusual is happening. On
360 MS-DOS systems you get the message "[unix format]" if 'fileformat' is set to
361 "unix". On all systems but the Macintosh you get the message "[mac format]"
362 if 'fileformat' is set to "mac".
364 If the 'fileformats' option is empty and DOS format is used, but while reading
365 a file some lines did not end in <CR><NL>, "[CR missing]" will be included in
366 the file message.
367 If the 'fileformats' option is empty and Mac format is used, but while reading
368 a file a <NL> was found, "[NL missing]" will be included in the file message.
370 If the new file does not exist, the 'fileformat' of the current buffer is used
371 when 'fileformats' is empty. Otherwise the first format from 'fileformats' is
372 used for the new file.
374 Before editing binary, executable or Vim script files you should set the
375 'binary' option. A simple way to do this is by starting Vim with the "-b"
376 option. This will avoid the use of 'fileformat'. Without this you risk that
377 single <NL> characters are unexpectedly replaced with <CR><NL>.
379 You can encrypt files that are written by setting the 'key' option. This
380 provides some security against others reading your files. |encryption|
382 ==============================================================================
383 3. The current directory *current-directory*
385 *:cd*
386 :cd On non-Unix systems: Print the current directory
387 name. On Unix systems: Change the current directory
388 to the home directory.
390 :cd {path} Change the current directory to {path}. Does not
391 change the meaning of an already entered file name,
392 because its full path name is remembered. On MS-DOS
393 this also changes the active drive.
395 *:cd-*
396 :cd - Change to the previous current directory (before the
397 previous ":cd {path}" command).
399 *:chd* *:chdir*
400 :chd[ir] [path] Same as :cd.
402 *:pw* *:pwd*
403 :pw[d] Print the current directory name. {Vi: no pwd}
404 Also see |getcwd()|.
406 You may use the |:cd| command to get to another directory, so you will not
407 have to type that directory name in front of the file names. One warning:
408 After using |:cd| the full path name will be used for reading and writing
409 files. On some networked file systems this may cause problems. The result of
410 using the full path name is that the file names currently in use will remain
411 referring to the same file. Example: If you have a file a:test and a
412 directory a:vim the commands ":e test" ":cd vim" ":w" will overwrite the file
413 a:test and not write a:vim/test. But if you do ":w test" the file a:vim/test
414 will be written, because you gave a new file name and did not refer to a
415 filename before the ":cd".
417 ==============================================================================
418 4. The argument list *argument-list* *arglist*
420 If you give more than one file name when starting Vim, this list is
421 remembered as the argument list. Do not confuse this with the file list,
422 which you can see with the ":files" command |:files|. The argument list was
423 already present in Vi, the file list is new in Vim. The file names in the
424 argument list will also be present in the file list (unless they were
425 deleted with ":bdel").
427 You can use the argument list with the following commands, and with the
428 expression functions |argc()| and |argv()|.
430 *:ar* *:args*
431 :ar[gs] Print the argument list, with the current file in
432 square brackets.
434 *:argu* *:argument*
435 :[count]argu[ment] [count] [+cmd]
436 Edit file [count] in the argument list. This fails
437 when changes have been made and Vim does not want to
438 |abandon| the current buffer. Also see |+cmd|. {Vi:
439 no such command}
441 :[count]argu[ment]! [count] [+cmd]
442 Edit file [count] in the argument list, discard any
443 changes to the current buffer. Also see |+cmd|. {Vi:
444 no such command}
446 *:n* *:ne* *:next*
447 :[count]n[ext] [+cmd] Edit [count] next file. This fails when changes have
448 been made and Vim does not want to |abandon| the
449 current buffer. Also see |+cmd|. {Vi: no count}.
451 :[count]n[ext]! [+cmd] Edit [count] next file, discard any changes to the
452 buffer. Also see |+cmd|. {Vi: no count}.
454 :ar[gs] [+cmd] {arglist}
455 :n[ext] [+cmd] {arglist}
456 Define {arglist} as the new argument list and edit
457 the first one. This fails when changes have been made
458 and Vim does not want to |abandon| the current buffer.
459 Also see |+cmd|.
461 :ar[gs]! [+cmd] {arglist}
462 :n[ext]! [+cmd] {arglist} *:next_f*
463 Define {arglist} as the new argument list and edit
464 the first one. Discard any changes to the buffer.
465 Also see |+cmd|.
467 :[count]N[ext] [count] [+cmd] *:Next* *:N*
468 Edit [count] previous file in argument list. This
469 fails when changes have been made and Vim does not
470 want to |abandon| the current buffer.
471 Also see |+cmd|. {Vi: no count}.
473 :[count]N[ext]! [count] [+cmd]
474 Edit [count] previous file in argument list. Discard
475 any changes to the buffer. Also see |+cmd|. {Vi: no
476 count}.
478 :[count]prev[ious] [count] [+cmd] *:prev* *:previous*
479 Same as :Next. Also see |+cmd|. {Vi: only in some
480 versions}
482 *:rew* *:rewind*
483 :rew[ind] [+cmd] Start editing the first file in the argument list.
484 This fails when changes have been made and Vim does
485 not want to |abandon| the current buffer.
486 Also see |+cmd|.
488 :rew[ind]! [+cmd] Start editing the first file in the argument list.
489 Discard any changes to the buffer. Also see |+cmd|.
491 *:la* *:last*
492 :la[st] [+cmd] Start editing the last file in the argument list.
493 This fails when changes have been made and Vim does
494 not want to |abandon| the current buffer.
495 Also see |+cmd|. {not in Vi}
497 :la[st]! [+cmd] Start editing the last file in the argument list.
498 Discard any changes to the buffer. Also see |+cmd|.
499 {not in Vi}
501 *:wn* *:wnext*
502 :[count]wn[ext] [+cmd] Write current file and start editing the [count]
503 next file. Also see |+cmd|. {not in Vi}
505 :[count]wn[ext] [+cmd] {file}
506 Write current file to {file} and start editing the
507 [count] next file, unless {file} already exists and
508 the 'writeany' option is off. Also see |+cmd|. {not
509 in Vi}
511 :[count]wn[ext]! [+cmd] {file}
512 Write current file to {file} and start editing the
513 [count] next file. Also see |+cmd|. {not in Vi}
515 :[count]wN[ext][!] [+cmd] [file] *:wN* *:wNext*
516 :[count]wp[revous][!] [+cmd] [file] *:wp* *:wprevious*
517 Same as :wnext, but go to previous file instead of
518 next. {not in Vi}
520 The [count] in the commands above defaults to one. For some commands it is
521 possible to use two counts. The last one (rightmost one) is used.
523 If no [+cmd] argument is present, the cursor is positioned at the last known
524 cursor position for the file. If 'startofline' is set, the cursor will be
525 positioned at the first non-blank in the line, otherwise the last know column
526 is used. If there is no last known cursor position the cursor will be in the
527 first line (the last line in Ex mode).
529 The wildcards in the argument list are expanded and the file names are sorted.
530 Thus you can use the command "vim *.c" to edit all the C files. From within
531 Vim the command ":n *.c" does the same. On Unix you can also use backticks,
532 for example:
533 > :n `find . -name \\*.c -print`
534 The backslashes before the star are required to prevent "*.c" to be expanded
535 by the shell before executing the find program.
537 *arglist-quit*
538 You are protected from leaving Vim if you have not been editing the last file
539 in the argument list. This prevents you from forgetting that you were editing
540 one out of several files. To exit anyway try to exit twice. If there are
541 changes in the current buffer this will fail. You can exit anyway, and save
542 any changes, with the ":wq!" command. To lose any changes use the ":q!"
543 command.
545 *arglist-position*
546 When there is an argument list you can see which file you are editing in the
547 title of the window (if there is one and 'title' is on) and with the file
548 message you get with the "CTRL-G" command. You will see something like
549 (file 4 of 11)
550 If 'shortmess' contains 'f' it will be
551 (4 of 11)
552 If you are not really editing the file at the current position in the argument
553 list it will be
554 (file (4) of 11)
555 This means that you are position 4 in the argument list, but not editing the
556 fourth file in the argument list. This happens when you do ":e file".
558 ==============================================================================
559 5. Writing and quitting *write-quit* *save-file*
561 Note: When the 'write' option is off, you are not able to write any file.
563 *:w* *:write*
564 :[range]w[rite][!] Write the specified lines to the current file.
566 *:w_f* *:write_f*
567 :[range]w[rite] {file} Write the specified lines to {file}, unless it
568 already exists and the 'writeany' option is off.
570 *:w!*
571 :[range]w[rite]! {file} Write the specified lines to {file}. Overwrite an
572 existing file.
574 *:w_a* *:write_a*
575 :[range]w[rite][!] >> Append the specified lines to the current file.
577 :[range]w[rite][!] >> {file}
578 Append the specified lines to {file}. '!' forces the
579 write even if file does not exist.
581 *:w_c* *:write_c*
582 :[range]w[rite] !{cmd} Execute {cmd} with [range] lines as standard input
583 (note the space in front of the '!'). {cmd} is
584 executed like with ":!{cmd}", any '!' is replaced with
585 the previous command |:!|.
587 The default [range] for the ":w" command is the whole buffer (1,$).
588 If a file name is given with ":w" it becomes the alternate file. This can be
589 used, for example, when the write fails and you want to try again later with
590 ":w #". This can be switched off by removing the 'A' flag from the
591 'cpoptions' option.
593 *:up* *:update*
594 :[range]up[date][!] [>>] [file]
595 Like ":write", but only write when the buffer has been
596 modified. {not in Vi}
598 *:q* *:quit*
599 :q[uit] Quit Vim. This fails when changes have been made and
600 Vim refuses to |abandon| the current buffer, and when
601 not editing the last file in the argument list.
603 :conf[irm] q[uit] Quit, but give prompt when changes have been made, or
604 not editing the last file in the argument list. See
605 |:confirm| and 'confirm'. {not in Vi}
607 :q[uit]! Quit without writing, also when visible buffers have
608 changes. Does not exit when there are changed hidden
609 buffers. Use ":qall!" to exit always.
611 :cq[uit] Quit always, without writing, and return an error
612 code. See |:cq|. Used for Manx's QuickFix mode (see
613 |quickfix|). {not in Vi}
615 *:wq*
616 :wq Write the current file and exit (unless editing the
617 last file in the argument list or the file is
618 read-only).
620 :wq! Write the current file and exit.
622 :wq {file} Write to {file}. Exit if not editing the last
623 file in the argument list.
625 :wq! {file} Write to {file} and exit.
627 :[range]wq[!] [file] Same as above, but only write the lines in [range].
629 *:x* *:xit*
630 :[range]x[it][!] [file]
631 Like ":wq", but write only when changes have been
632 made.
633 When 'hidden' is set and there are more windows, the
634 current buffer becomes hidden, after writing the file.
636 *:exi* *:exit*
637 :[range]exi[t][!] [file]
638 Same as :xit.
640 *ZZ*
641 ZZ Write current file, if modified, and exit (same as
642 ":x"). (Note: If there are several windows for the
643 current file, the file is written if it was modified
644 and the window is closed).
646 *ZQ*
647 ZQ Quit current file and exit (same as ":q!"). (Note: If
648 there are several windows for the current file, only
649 the window is closed).
651 *timestamp*
652 Vim remembers the modification timestamp of a file when you begin editing it.
653 Before writing a file the timestamp is checked. If it has changed, Vim will
654 ask if you really want to overwrite the file:
656 WARNING: The file has been changed since reading it!!!
657 Do you really want to write to it (y/n)?
659 If you hit 'y' Vim will continue writing the file. If you hit 'n' the write is
660 aborted. If you used ":wq" or "ZZ" Vim will not exit, you will get another
661 chance to write the file.
663 Alternatively, after a shell command is run (|:!cmd| |suspend| |:read!| |K|)
664 ALL timestamps are compared. Vim will run any associated |FileChangedShell|
665 autocommands or display the above WARNING for any files that have changed.
667 The message would normally mean that somebody has written to the file after
668 the edit session started. This could be another person, in which case you
669 probably want to check if your changes to the file and the changes from the
670 other person should be merged. Write the file under another name and check for
671 differences (the "diff" program can be used for this).
672 It is also possible that you modified the file yourself, from another edit
673 session or with another command (e.g., a filter command). Then you will know
674 which version of the file you want to keep.
676 *backup*
677 If you write to an existing file (but do not append) while the 'backup',
678 'writebackup' or 'patchmode' option is on, a backup of the original file is
679 made. On Unix systems the file is copied, on other systems the file is
680 renamed. After the file has been successfully written and when the
681 'writebackup' option is on and the 'backup' option is off, the backup file is
682 deleted. When the 'patchmode' option is on the backup file may be renamed.
684 *backup-table*
685 'backup' 'writebackup' action ~
686 off off no backup made
687 off on backup current file, deleted afterwards (default)
688 on off delete old backup, backup current file
689 on on delete old backup, backup current file
691 When the 'backup' option is on, an old backup file (with the same name as the
692 new backup file) will be deleted. If 'backup' is not set, but 'writebackup' is
693 set, an existing backup file will not be deleted. The backup file that is made
694 while the file is being written will have a different name.
696 The directories given with the 'backupdir' option is used to put the backup
697 file in. (default: same directory as the written file).
699 On Unix systems:
700 When you write to an existing file, that file is truncated and then filled
701 with the new text. This means that protection bits, owner and symbolic links
702 are unmodified. The backup file however, is a new file, owned by the user who
703 edited the file. The group of the backup is set to the group of the original
704 file. If this fails, the protection bits for the group are made the same as
705 for others.
707 If the creation of a backup file fails, the write is not done. If you want
708 to write anyway add a '!' to the command.
710 *write-readonly*
711 When the 'cpoptions' option contains 'W', Vim will refuse to overwrite a
712 readonly file. When 'W' is not present, ":w!" will overwrite a readonly file,
713 if the system allows it (the directory must be writable).
715 *write-fail*
716 If the writing of the new file fails, you have to be careful not to lose
717 your changes AND the original file. If there is no backup file and writing
718 the new file failed, you have already lost the original file! DON'T EXIT VIM
719 UNTIL YOU WRITE OUT THE FILE! If a backup was made, it is put back in place
720 of the original file (if possible). If you exit Vim, and lose the changes
721 you made, the original file will mostly still be there. If putting back the
722 original file fails, there will be an error message telling you that you
723 lost the original file.
725 *DOS-format-write*
726 If the 'fileformat' is "dos", <CR> <NL> is used for <EOL>. This is default
727 for MS-DOS, Win32 and OS/2. On other systems the message "[dos format]" is
728 shown to remind you that an unusual <EOL> was used.
729 *Unix-format-write*
730 If the 'fileformat' is "unix", <NL> is used for <EOL>. On MS-DOS, Win32 and
731 OS/2 the message "[unix format]" is shown.
732 *Mac-format-write*
733 If the 'fileformat' is "mac", <CR> is used for <EOL>. On non-Mac systems the
734 message "[mac format]" is shown.
736 See also |file-formats| and the 'fileformat' and 'fileformats' options.
738 ==============================================================================
739 6. Editing binary files *edit-binary*
741 Although Vim was made to edit text files, it is possible to edit binary
742 files. The "-b" Vim argument (b for binary) makes Vim do file I/O in binary
743 mode, and sets some options for editing binary files ('binary' on, 'textwidth'
744 to 0, 'modeline' off, 'expandtab' off). Setting the 'binary' option has the
745 same effect. Don't forget to do this before reading the file.
747 There are a few things to remember when editing binary files:
748 - When editing executable files the number of characters must not change.
749 Use only the "R" or "r" command to change text. Do not delete characters
750 with "x" or by backspacing.
751 - Set the 'textwidth' option to 0. Otherwise lines will unexpectedly be
752 split in two.
753 - When there are not many <EOL>s, the lines will become very long. If you
754 want to edit a line that does not fit on the screen reset the 'wrap' option.
755 Horizontal scrolling is used then. If a line becomes too long (more than
756 about 32767 characters on the Amiga, much more on 32-bit systems, see
757 |limits|) you cannot edit that line. The line will be split when reading
758 the file. It is also possible that you get an "out of memory" error when
759 reading the file.
760 - Make sure the 'binary' option is set BEFORE loading the
761 file. Otherwise both <CR> <NL> and <NL> are considered to end a line
762 and when the file is written the <NL> will be replaced with <CR> <NL>.
763 - <Nul> characters are shown on the screen as ^@. You can enter them with
764 "CTRL-V CTRL-@" or "CTRL-V 000" {Vi cannot handle <Nul> characters in the
765 file}
766 - To insert a <NL> character in the file split up a line. When writing the
767 buffer to a file a <NL> will be written for the <EOL>.
768 - Vim normally appends an <EOL> at the end of the file if there is none.
769 Setting the 'binary' option prevents this. If you want to add the final
770 <EOL>, set the 'endofline' option. You can also read the value of this
771 option to see if there was an <EOL> for the last line (you cannot see this
772 in the text).
774 ==============================================================================
775 7. Encryption *encryption*
777 Vim is able to write files encrypted, and read them back. The encrypted text
778 cannot be read without the right key.
780 Note: The swapfile and text in memory are not encrypted. A system
781 administrator will be able to see your text while you are editing it.
783 WARNING: If you make a typo when entering the key and then write the file and
784 exit, the text will be lost!
786 The normal way to work with encryption, is to use the ":X" command, which will
787 ask you to enter a key. A following write command will use that key to
788 encrypt the file. If you later edit the same file, Vim will ask you to enter
789 a key. If you type the same key as that was used for writing, the text will
790 be readable again. If you use a wrong key, it will be a mess.
792 *:X*
793 :X Prompt for an encryption key. The typing is done without showing the
794 actual text, so that someone looking at the display won't see it.
795 The typed key is stored in the 'key' option, which is used to encrypt
796 the file when it is written. See also |-x|.
798 The value of the 'key' options is used when text is written. When the option
799 is not empty, the written file will be encrypted, using the value as the
800 encryption key. A magic number is prepended, so that Vim can recognize that
801 the file is encrypted.
803 To disable the encryption, reset the 'key' option to an empty value:
804 > :set key=
806 When reading a file that has been encrypted and this option is not empty, it
807 will be used for decryption. If the value is empty, you will be prompted to
808 enter the key. If you don't enter a key, the file is edited without being
809 decrypted.
811 If want to start reading a file that uses a different key, set the 'key'
812 option to an empty string, so that Vim will prompt for a new one. Don't use
813 the ":set" command to enter the value, other people can read the command over
814 your shoulder.
816 Since the value of the 'key' option is supposed to be a secret, its value can
817 never be viewed. You should not set this option in a vimrc file.
819 An encrypted file can be recognized by the "file" command, if you add this
820 line to "/etc/magic", "/usr/share/misc/magic" or wherever your system has the
821 "magic" file:
822 > 0 string VimCrypt~ Vim encrypted file
824 Notes:
825 - Text you copy or delete goes to the numbered registers. The registers can
826 be saved in the .viminfo file, where they could be read. Change your
827 'viminfo' option to be safe.
828 - Someone can type commands in Vim when you walk away for a moment, he should
829 not be able to get the key.
830 - If you make a typing mistake when entering the key, you might not be able to
831 get your text back!
832 - If you type the key with a ":set key=value" command, it can be kept in the
833 history, showing the 'key' value in a viminfo file.
834 - There is never 100% safety. The encryption in Vim has not been tested for
835 robustness.
836 - The algorithm used is breakable. A 4 character key in about one hour, a 6
837 character key in one day (on a Pentium 133 PC). This requires that you know
838 some text that must appear in the file. An expert can break it for any key.
839 - Pkzip uses the same encryption, and US Govt has no objection to its export.
840 Pkzip's public file APPNOTE.TXT describes this algorithm in detail.
841 - Vim originates from the Netherlands. That is where the sources come from.
842 Thus the encryption code is not exported from the USA.
844 vim:tw=78:ts=8:sw=8: