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