]> code.delx.au - gnu-emacs/blob - doc/emacs/files.texi
Move doc of backup-directory-alist to the Backup node
[gnu-emacs] / doc / emacs / files.texi
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2016 Free Software
3 @c Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Files
6 @chapter File Handling
7 @cindex files
8
9 The operating system stores data permanently in named @dfn{files}, so
10 most of the text you edit with Emacs comes from a file and is ultimately
11 stored in a file.
12
13 To edit a file, you must tell Emacs to read the file and prepare a
14 buffer containing a copy of the file's text. This is called
15 @dfn{visiting} the file. Editing commands apply directly to text in the
16 buffer; that is, to the copy inside Emacs. Your changes appear in the
17 file itself only when you @dfn{save} the buffer back into the file.
18
19 In addition to visiting and saving files, Emacs can delete, copy,
20 rename, and append to files, keep multiple versions of them, and operate
21 on file directories.
22
23 @menu
24 * File Names:: How to type and edit file-name arguments.
25 * Visiting:: Visiting a file prepares Emacs to edit the file.
26 * Saving:: Saving makes your changes permanent.
27 * Reverting:: Reverting cancels all the changes not saved.
28 @ifnottex
29 * Autorevert:: Auto Reverting non-file buffers.
30 @end ifnottex
31 * Auto Save:: Auto Save periodically protects against loss of data.
32 * File Aliases:: Handling multiple names for one file.
33 * Directories:: Creating, deleting, and listing file directories.
34 * Comparing Files:: Finding where two files differ.
35 * Diff Mode:: Mode for editing file differences.
36 * Misc File Ops:: Other things you can do on files.
37 * Compressed Files:: Accessing compressed files.
38 * File Archives:: Operating on tar, zip, jar etc. archive files.
39 * Remote Files:: Accessing files on other machines.
40 * Quoted File Names:: Quoting special characters in file names.
41 * File Name Cache:: Completion against a list of files you often use.
42 * File Conveniences:: Convenience Features for Finding Files.
43 * Filesets:: Handling sets of files.
44 @end menu
45
46 @node File Names
47 @section File Names
48 @cindex file names
49
50 @cindex default file name
51 Many Emacs commands that operate on a file require you to specify
52 the file name, using the minibuffer (@pxref{Minibuffer File}).
53
54 While in the minibuffer, you can use the usual completion and
55 history commands (@pxref{Minibuffer}). Note that file name completion
56 ignores file names whose extensions appear in the variable
57 @code{completion-ignored-extensions} (@pxref{Completion Options}).
58 Note also that most commands use permissive completion with
59 confirmation for reading file names: you are allowed to submit a
60 nonexistent file name, but if you type @key{RET} immediately after
61 completing up to a nonexistent file name, Emacs prints
62 @samp{[Confirm]} and you must type a second @key{RET} to confirm.
63 @xref{Completion Exit}, for details.
64
65 @cindex default directory
66 @vindex default-directory
67 @vindex insert-default-directory
68 Each buffer has a @dfn{default directory}, stored in the
69 buffer-local variable @code{default-directory}. Whenever Emacs reads
70 a file name using the minibuffer, it usually inserts the default
71 directory into the minibuffer as the initial contents. You can
72 inhibit this insertion by changing the variable
73 @code{insert-default-directory} to @code{nil} (@pxref{Minibuffer
74 File}). Regardless, Emacs always assumes that any relative file name
75 is relative to the default directory, e.g., entering a file name
76 without a directory specifies a file in the default directory.
77
78 @findex cd
79 @findex pwd
80 When you visit a file, Emacs sets @code{default-directory} in the
81 visiting buffer to the directory of its file. When you create a new
82 buffer that is not visiting a file, via a command like @kbd{C-x b},
83 its default directory is usually copied from the buffer that was
84 current at the time (@pxref{Select Buffer}). You can use the command
85 @kbd{M-x pwd} to see the value of @code{default-directory} in the
86 current buffer. The command @kbd{M-x cd} prompts for a directory
87 name, and sets the buffer's @code{default-directory} to that directory
88 (doing this does not change the buffer's file name, if any).
89
90 As an example, when you visit the file @file{/u/rms/gnu/gnu.tasks},
91 the default directory is set to @file{/u/rms/gnu/}. If you invoke a
92 command that reads a file name, entering just @samp{foo} in the
93 minibuffer, with a directory omitted, specifies the file
94 @file{/u/rms/gnu/foo}; entering @samp{../.login} specifies
95 @file{/u/rms/.login}; and entering @samp{new/foo} specifies
96 @file{/u/rms/gnu/new/foo}.
97
98 When typing a file name into the minibuffer, you can make use of a
99 couple of shortcuts: a double slash ignores everything before the
100 second slash in the pair, and @samp{~/} is your home directory.
101 @xref{Minibuffer File}.
102
103 @cindex environment variables in file names
104 @cindex expansion of environment variables
105 @cindex @code{$} in file names
106 @anchor{File Names with $}The character @samp{$} is used to
107 substitute an environment variable into a file name. The name of the
108 environment variable consists of all the alphanumeric characters after
109 the @samp{$}; alternatively, it can be enclosed in braces after the
110 @samp{$}. For example, if you have used the shell command
111 @command{export FOO=rms/hacks} to set up an environment variable named
112 @env{FOO}, then both @file{/u/$FOO/test.c} and
113 @file{/u/$@{FOO@}/test.c} are abbreviations for
114 @file{/u/rms/hacks/test.c}. If the environment variable is not
115 defined, no substitution occurs, so that the character @samp{$} stands
116 for itself. Note that environment variables affect Emacs only if they
117 are applied before Emacs is started.
118
119 To access a file with @samp{$} in its name, if the @samp{$} causes
120 expansion, type @samp{$$}. This pair is converted to a single
121 @samp{$} at the same time that variable substitution is performed for
122 a single @samp{$}. Alternatively, quote the whole file name with
123 @samp{/:} (@pxref{Quoted File Names}). File names which begin with a
124 literal @samp{~} should also be quoted with @samp{/:}.
125
126 You can include non-@acronym{ASCII} characters in file names.
127 @xref{File Name Coding}.
128
129 @node Visiting
130 @section Visiting Files
131 @cindex visiting files
132 @cindex open file
133
134 @table @kbd
135 @item C-x C-f
136 Visit a file (@code{find-file}).
137 @item C-x C-r
138 Visit a file for viewing, without allowing changes to it
139 (@code{find-file-read-only}).
140 @item C-x C-v
141 Visit a different file instead of the one visited last
142 (@code{find-alternate-file}).
143 @item C-x 4 f
144 Visit a file, in another window (@code{find-file-other-window}). Don't
145 alter what is displayed in the selected window.
146 @item C-x 5 f
147 Visit a file, in a new frame (@code{find-file-other-frame}). Don't
148 alter what is displayed in the selected frame.
149 @item M-x find-file-literally
150 Visit a file with no conversion of the contents.
151 @end table
152
153 @cindex files, visiting and saving
154 @cindex saving files
155 @dfn{Visiting} a file means reading its contents into an Emacs
156 buffer so you can edit them. Emacs makes a new buffer for each file
157 that you visit.
158
159 @kindex C-x C-f
160 @findex find-file
161 To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the
162 minibuffer to enter the name of the desired file. While in the
163 minibuffer, you can abort the command by typing @kbd{C-g}. @xref{File
164 Names}, for details about entering file names into minibuffers.
165
166 If the specified file exists but the system does not allow you to
167 read it, an error message is displayed in the echo area. Otherwise,
168 you can tell that @kbd{C-x C-f} has completed successfully by the
169 appearance of new text on the screen, and by the buffer name shown in
170 the mode line (@pxref{Mode Line}). Emacs normally constructs the
171 buffer name from the file name, omitting the directory name. For
172 example, a file named @file{/usr/rms/emacs.tex} is visited in a buffer
173 named @samp{emacs.tex}. If there is already a buffer with that name,
174 Emacs constructs a unique name; the normal method is to add a suffix
175 based on the directory name (e.g., @samp{<rms>}, @samp{<tmp>},
176 and so on), but you can select other methods. @xref{Uniquify}.
177
178 @cindex creating files
179 To create a new file, just visit it using the same command, @kbd{C-x
180 C-f}. Emacs displays @samp{(New file)} in the echo area, but in other
181 respects behaves as if you had visited an existing empty file.
182
183 @cindex modified (buffer)
184 After visiting a file, the changes you make with editing commands are
185 made in the Emacs buffer. They do not take effect in the visited
186 file, until you @dfn{save} the buffer (@pxref{Saving}). If a buffer
187 contains changes that have not been saved, we say the buffer is
188 @dfn{modified}. This implies that some changes will be lost if the
189 buffer is not saved. The mode line displays two stars near the left
190 margin to indicate that the buffer is modified.
191
192 If you visit a file that is already in Emacs, @kbd{C-x C-f} switches
193 to the existing buffer instead of making another copy. Before doing
194 so, it checks whether the file has changed since you last visited or
195 saved it. If the file has changed, Emacs offers to reread it.
196
197 @vindex large-file-warning-threshold
198 @cindex file, warning when size is large
199 @cindex size of file, warning when visiting
200 @cindex maximum buffer size exceeded, error message
201 If you try to visit a file larger than
202 @code{large-file-warning-threshold} (the default is 10000000, which is
203 about 10 megabytes), Emacs asks you for confirmation first. You can
204 answer @kbd{y} to proceed with visiting the file. Note, however, that
205 Emacs cannot visit files that are larger than the maximum Emacs buffer
206 size, which is limited by the amount of memory Emacs can allocate and
207 by the integers that Emacs can represent (@pxref{Buffers}). If you
208 try, Emacs displays an error message saying that the maximum buffer
209 size has been exceeded.
210
211 @cindex wildcard characters in file names
212 @vindex find-file-wildcards
213 If the file name you specify contains shell-style wildcard
214 characters, Emacs visits all the files that match it. (On
215 case-insensitive filesystems, Emacs matches the wildcards disregarding
216 the letter case.) Wildcards include @samp{?}, @samp{*}, and
217 @samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file
218 name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted
219 File Names}, for information on how to visit a file whose name
220 actually contains wildcard characters. You can disable the wildcard
221 feature by customizing @code{find-file-wildcards}.
222
223 @kindex C-x C-v
224 @findex find-alternate-file
225 If you visit the wrong file unintentionally by typing its name
226 incorrectly, type @kbd{C-x C-v} (@code{find-alternate-file}) to visit
227 the file you really wanted. @kbd{C-x C-v} is similar to @kbd{C-x
228 C-f}, but it kills the current buffer (after first offering to save it
229 if it is modified). When @kbd{C-x C-v} reads the file name to visit,
230 it inserts the entire default file name in the buffer, with point just
231 after the directory part; this is convenient if you made a slight
232 error in typing the name.
233
234 @vindex find-file-run-dired
235 If you visit a file that is actually a directory, Emacs invokes
236 Dired, the Emacs directory browser. @xref{Dired}. You can disable
237 this behavior by setting the variable @code{find-file-run-dired} to
238 @code{nil}; in that case, it is an error to try to visit a directory.
239
240 Files which are actually collections of other files, or @dfn{file
241 archives}, are visited in special modes which invoke a Dired-like
242 environment to allow operations on archive members. @xref{File
243 Archives}, for more about these features.
244
245 If you visit a file that the operating system won't let you modify,
246 or that is marked read-only, Emacs makes the buffer read-only too, so
247 that you won't go ahead and make changes that you'll have trouble
248 saving afterward. You can make the buffer writable with @kbd{C-x C-q}
249 (@code{read-only-mode}). @xref{Misc Buffer}.
250
251 @kindex C-x C-r
252 @findex find-file-read-only
253 If you want to visit a file as read-only in order to protect
254 yourself from entering changes accidentally, visit it with the command
255 @kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}.
256
257 @kindex C-x 4 f
258 @findex find-file-other-window
259 @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
260 except that the buffer containing the specified file is selected in another
261 window. The window that was selected before @kbd{C-x 4 f} continues to
262 show the same buffer it was already showing. If this command is used when
263 only one window is being displayed, that window is split in two, with one
264 window showing the same buffer as before, and the other one showing the
265 newly requested file. @xref{Windows}.
266
267 @kindex C-x 5 f
268 @findex find-file-other-frame
269 @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
270 new frame, or selects any existing frame showing the specified file.
271 @xref{Frames}.
272
273 @cindex file selection dialog
274 On graphical displays, there are two additional methods for visiting
275 files. Firstly, when Emacs is built with a suitable GUI toolkit,
276 commands invoked with the mouse (by clicking on the menu bar or tool
277 bar) use the toolkit's standard file selection dialog instead of
278 prompting for the file name in the minibuffer. On GNU/Linux and Unix
279 platforms, Emacs does this when built with GTK, LessTif, and Motif
280 toolkits; on MS-Windows and Mac, the GUI version does that by default.
281 For information on how to customize this, see @ref{Dialog Boxes}.
282
283 Secondly, Emacs supports drag and drop: dropping a file into an
284 ordinary Emacs window visits the file using that window. As an
285 exception, dropping a file into a window displaying a Dired buffer
286 moves or copies the file into the displayed directory. For details,
287 see @ref{Drag and Drop}, and @ref{Misc Dired Features}.
288
289 On text-mode terminals and on graphical displays when Emacs was
290 built without a GUI toolkit, you can visit files via the menu-bar
291 @samp{File} menu, which has a @samp{Visit New File} item.
292
293 Each time you visit a file, Emacs automatically scans its contents
294 to detect what character encoding and end-of-line convention it uses,
295 and converts these to Emacs's internal encoding and end-of-line
296 convention within the buffer. When you save the buffer, Emacs
297 performs the inverse conversion, writing the file to disk with its
298 original encoding and end-of-line convention. @xref{Coding Systems}.
299
300 @findex find-file-literally
301 If you wish to edit a file as a sequence of @acronym{ASCII}
302 characters with no special encoding or conversion, use the @kbd{M-x
303 find-file-literally} command. This visits a file, like @kbd{C-x C-f},
304 but does not do format conversion (@pxref{Format Conversion,, Format
305 Conversion, elisp, the Emacs Lisp Reference Manual}), character code
306 conversion (@pxref{Coding Systems}), or automatic uncompression
307 (@pxref{Compressed Files}), and does not add a final newline because
308 of @code{require-final-newline} (@pxref{Customize Save}). If you have
309 already visited the same file in the usual (non-literal) manner, this
310 command asks you whether to visit it literally instead.
311
312 @vindex find-file-hook
313 @vindex find-file-not-found-functions
314 Two special hook variables allow extensions to modify the operation
315 of visiting files. Visiting a file that does not exist runs the
316 functions in @code{find-file-not-found-functions}; this variable holds
317 a list of functions, which are called one by one (with no arguments)
318 until one of them returns non-@code{nil}. This is not a normal hook,
319 and the name ends in @samp{-functions} rather than @samp{-hook} to
320 indicate that fact.
321
322 Successful visiting of any file, whether existing or not, calls the
323 functions in @code{find-file-hook}, with no arguments. This variable
324 is a normal hook. In the case of a nonexistent file, the
325 @code{find-file-not-found-functions} are run first. @xref{Hooks}.
326
327 There are several ways to specify automatically the major mode for
328 editing the file (@pxref{Choosing Modes}), and to specify local
329 variables defined for that file (@pxref{File Variables}).
330
331 @node Saving
332 @section Saving Files
333
334 @dfn{Saving} a buffer in Emacs means writing its contents back into the file
335 that was visited in the buffer.
336
337 @menu
338 * Save Commands:: Commands for saving files.
339 * Backup:: How Emacs saves the old version of your file.
340 * Customize Save:: Customizing the saving of files.
341 * Interlocking:: How Emacs protects against simultaneous editing
342 of one file by two users.
343 * Shadowing: File Shadowing. Copying files to ``shadows'' automatically.
344 * Time Stamps:: Emacs can update time stamps on saved files.
345 @end menu
346
347 @node Save Commands
348 @subsection Commands for Saving Files
349
350 These are the commands that relate to saving and writing files.
351
352 @table @kbd
353 @item C-x C-s
354 Save the current buffer to its file (@code{save-buffer}).
355 @item C-x s
356 Save any or all buffers to their files (@code{save-some-buffers}).
357 @item M-~
358 Forget that the current buffer has been changed (@code{not-modified}).
359 With prefix argument (@kbd{C-u}), mark the current buffer as changed.
360 @item C-x C-w
361 Save the current buffer with a specified file name (@code{write-file}).
362 @item M-x set-visited-file-name
363 Change the file name under which the current buffer will be saved.
364 @end table
365
366 @kindex C-x C-s
367 @findex save-buffer
368 When you wish to save the file and make your changes permanent, type
369 @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
370 displays a message like this:
371
372 @example
373 Wrote /u/rms/gnu/gnu.tasks
374 @end example
375
376 @noindent
377 If the current buffer is not modified (no changes have been made in it
378 since the buffer was created or last saved), saving is not really
379 done, because it would have no effect. Instead, @kbd{C-x C-s}
380 displays a message like this in the echo area:
381
382 @example
383 (No changes need to be saved)
384 @end example
385
386 With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer
387 to be backed up when the next save is done. @xref{Backup}.
388
389 @kindex C-x s
390 @findex save-some-buffers
391 The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
392 or all modified buffers. It asks you what to do with each buffer. The
393 possible responses are analogous to those of @code{query-replace}:
394
395 @table @kbd
396 @item y
397 Save this buffer and ask about the rest of the buffers.
398 @item n
399 Don't save this buffer, but ask about the rest of the buffers.
400 @item !
401 Save this buffer and all the rest with no more questions.
402 @c following generates acceptable underfull hbox
403 @item @key{RET}
404 Terminate @code{save-some-buffers} without any more saving.
405 @item .
406 Save this buffer, then exit @code{save-some-buffers} without even asking
407 about other buffers.
408 @item C-r
409 View the buffer that you are currently being asked about. When you exit
410 View mode, you get back to @code{save-some-buffers}, which asks the
411 question again.
412 @item d
413 Diff the buffer against its corresponding file, so you can see what
414 changes you would be saving. This calls the command
415 @code{diff-buffer-with-file} (@pxref{Comparing Files}).
416 @item C-h
417 Display a help message about these options.
418 @end table
419
420 @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
421 @code{save-some-buffers} and therefore asks the same questions.
422
423 @kindex M-~
424 @findex not-modified
425 If you have changed a buffer but do not wish to save the changes,
426 you should take some action to prevent it. Otherwise, each time you
427 use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer
428 by mistake. One thing you can do is type @kbd{M-~}
429 (@code{not-modified}), which clears out the indication that the buffer
430 is modified. If you do this, none of the save commands will believe
431 that the buffer needs to be saved. (@samp{~} is often used as a
432 mathematical symbol for ``not''; thus @kbd{M-~} is ``not'', metafied.)
433 Alternatively, you can cancel all the changes made since the file was
434 visited or saved, by reading the text from the file again. This is
435 called @dfn{reverting}. @xref{Reverting}. (You could also undo all
436 the changes by repeating the undo command @kbd{C-x u} until you have
437 undone all the changes; but reverting is easier.)
438
439 @findex set-visited-file-name
440 @kbd{M-x set-visited-file-name} alters the name of the file that the
441 current buffer is visiting. It reads the new file name using the
442 minibuffer. Then it marks the buffer as visiting that file name, and
443 changes the buffer name correspondingly. @code{set-visited-file-name}
444 does not save the buffer in the newly visited file; it just alters the
445 records inside Emacs in case you do save later. It also marks the
446 buffer as modified so that @kbd{C-x C-s} in that buffer
447 @emph{will} save.
448
449 @kindex C-x C-w
450 @findex write-file
451 If you wish to mark the buffer as visiting a different file and save
452 it right away, use @kbd{C-x C-w} (@code{write-file}). This is
453 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s},
454 except that @kbd{C-x C-w} asks for confirmation if the file exists.
455 @kbd{C-x C-s} used on a buffer that is not visiting a file has the
456 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
457 buffer as visiting that file, and saves it there. The default file
458 name in a buffer that is not visiting a file is made by combining the
459 buffer name with the buffer's default directory (@pxref{File Names}).
460
461 If the new file name implies a major mode, then @kbd{C-x C-w} switches
462 to that major mode, in most cases. The command
463 @code{set-visited-file-name} also does this. @xref{Choosing Modes}.
464
465 If Emacs is about to save a file and sees that the date of the latest
466 version on disk does not match what Emacs last read or wrote, Emacs
467 notifies you of this fact, because it probably indicates a problem caused
468 by simultaneous editing and requires your immediate attention.
469 @xref{Interlocking,, Simultaneous Editing}.
470
471 @node Backup
472 @subsection Backup Files
473 @cindex backup file
474 @vindex make-backup-files
475 @vindex vc-make-backup-files
476
477 On most operating systems, rewriting a file automatically destroys all
478 record of what the file used to contain. Thus, saving a file from Emacs
479 throws away the old contents of the file---or it would, except that
480 Emacs carefully copies the old contents to another file, called the
481 @dfn{backup} file, before actually saving.
482
483 Emacs makes a backup for a file only the first time the file is
484 saved from a buffer. No matter how many times you subsequently save
485 the file, its backup remains unchanged. However, if you kill the
486 buffer and then visit the file again, a new backup file will be made.
487
488 For most files, the variable @code{make-backup-files} determines
489 whether to make backup files. On most operating systems, its default
490 value is @code{t}, so that Emacs does write backup files.
491
492 For files managed by a version control system (@pxref{Version
493 Control}), the variable @code{vc-make-backup-files} determines whether
494 to make backup files. By default it is @code{nil}, since backup files
495 are redundant when you store all the previous versions in a version
496 control system.
497 @iftex
498 @xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}.
499 @end iftex
500 @ifnottex
501 @xref{General VC Options}.
502 @end ifnottex
503
504 At your option, Emacs can keep either a single backup for each file,
505 or make a series of numbered backup files for each file that you edit.
506 @xref{Backup Names}.
507
508 @vindex backup-enable-predicate
509 @vindex temporary-file-directory
510 @vindex small-temporary-file-directory
511 The default value of the @code{backup-enable-predicate} variable
512 prevents backup files being written for files in the directories used
513 for temporary files, specified by @code{temporary-file-directory} or
514 @code{small-temporary-file-directory}.
515
516 You can explicitly tell Emacs to make another backup file from a
517 buffer, even though that buffer has been saved before. If you save
518 the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
519 into a backup file if you save the buffer again. @kbd{C-u C-u C-x
520 C-s} saves the buffer, but first makes the previous file contents into
521 a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it
522 makes a backup from the previous contents, and arranges to make
523 another from the newly saved contents if you save again.
524
525 @vindex backup-directory-alist
526 You can customize the variable @code{backup-directory-alist} to
527 specify that files matching certain patterns should be backed up in
528 specific directories. A typical use is to add an element @code{("."
529 . @var{dir})} to make all backups in the directory with absolute name
530 @var{dir}. Emacs modifies the backup file names to avoid clashes
531 between files with the same names originating in different
532 directories. Alternatively, adding, @code{("." . ".~")} would make
533 backups in the invisible subdirectory @file{.~} of the original file's
534 directory. Emacs creates the directory, if necessary, to make the
535 backup.
536
537 @menu
538 * Names: Backup Names. How backup files are named.
539 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
540 * Copying: Backup Copying. Backups can be made by copying or renaming.
541 @end menu
542
543 @node Backup Names
544 @subsubsection Single or Numbered Backups
545 @cindex backup file names
546 @cindex names of backup files
547
548 @cindex @file{~}, in names of backup files
549 @cindex tilde (@file{~}) at end of backup file name
550 When Emacs makes a backup file, its name is normally constructed by
551 appending @samp{~} to the file name being edited; thus, the backup
552 file for @file{eval.c} would be @file{eval.c~}.
553
554 @cindex @file{~/.emacs.d/%backup%~}
555 If access control stops Emacs from writing backup files under the
556 usual names, it writes the backup file as @file{~/.emacs.d/%backup%~}.
557 Only one such file can exist, so only the most recently made such
558 backup is available.
559
560 Emacs can also make @dfn{numbered backup files}. Numbered backup
561 file names contain @samp{.~}, the number, and another @samp{~} after
562 the original file name. Thus, the backup files of @file{eval.c} would
563 be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way
564 through names like @file{eval.c.~259~} and beyond.
565
566 @vindex version-control
567 The variable @code{version-control} determines whether to make
568 single backup files or multiple numbered backup files. Its possible
569 values are:
570
571 @table @code
572 @item nil
573 Make numbered backups for files that have numbered backups already.
574 Otherwise, make single backups. This is the default.
575 @item t
576 Make numbered backups.
577 @item never
578 Never make numbered backups; always make single backups.
579 @end table
580
581 @noindent
582 The usual way to set this variable is globally, through your init file
583 or the customization buffer. However, you can set
584 @code{version-control} locally in an individual buffer to control the
585 making of backups for that buffer's file (@pxref{Locals}). You can
586 have Emacs set @code{version-control} locally whenever you visit a
587 given file (@pxref{File Variables}). Some modes, such as Rmail mode,
588 set this variable.
589
590 @cindex @env{VERSION_CONTROL} environment variable
591 If you set the environment variable @env{VERSION_CONTROL}, to tell
592 various GNU utilities what to do with backup files, Emacs also obeys the
593 environment variable by setting the Lisp variable @code{version-control}
594 accordingly at startup. If the environment variable's value is @samp{t}
595 or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
596 value is @samp{nil} or @samp{existing}, then @code{version-control}
597 becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
598 @code{version-control} becomes @code{never}.
599
600 @vindex make-backup-file-name-function
601 If you set the variable @code{make-backup-file-name-function} to
602 a suitable Lisp function, you can override the usual way Emacs
603 constructs backup file names.
604
605 @node Backup Deletion
606 @subsubsection Automatic Deletion of Backups
607
608 To prevent excessive consumption of disk space, Emacs can delete numbered
609 backup versions automatically. Generally Emacs keeps the first few backups
610 and the latest few backups, deleting any in between. This happens every
611 time a new backup is made.
612
613 @vindex kept-old-versions
614 @vindex kept-new-versions
615 The two variables @code{kept-old-versions} and
616 @code{kept-new-versions} control this deletion. Their values are,
617 respectively, the number of oldest (lowest-numbered) backups to keep
618 and the number of newest (highest-numbered) ones to keep, each time a
619 new backup is made. The backups in the middle (excluding those oldest
620 and newest) are the excess middle versions---those backups are
621 deleted. These variables' values are used when it is time to delete
622 excess versions, just after a new backup version is made; the newly
623 made backup is included in the count in @code{kept-new-versions}. By
624 default, both variables are 2.
625
626 @vindex delete-old-versions
627 If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
628 backup files silently. If it is @code{nil}, the default, Emacs asks
629 you whether it should delete the excess backup versions. If it has
630 any other value, then Emacs never automatically deletes backups.
631
632 Dired's @kbd{.} (Period) command can also be used to delete old versions.
633 @xref{Dired Deletion}.
634
635 @node Backup Copying
636 @subsubsection Copying vs.@: Renaming
637
638 Backup files can be made by copying the old file or by renaming it.
639 This makes a difference when the old file has multiple names (hard
640 links). If the old file is renamed into the backup file, then the
641 alternate names become names for the backup file. If the old file is
642 copied instead, then the alternate names remain names for the file
643 that you are editing, and the contents accessed by those names will be
644 the new contents.
645
646 The method of making a backup file may also affect the file's owner
647 and group. If copying is used, these do not change. If renaming is used,
648 you become the file's owner, and the file's group becomes the default
649 (different operating systems have different defaults for the group).
650
651 @vindex backup-by-copying
652 @vindex backup-by-copying-when-linked
653 @vindex backup-by-copying-when-mismatch
654 @vindex backup-by-copying-when-privileged-mismatch
655 @cindex file ownership, and backup
656 @cindex backup, and user-id
657 The choice of renaming or copying is made as follows:
658
659 @itemize
660 @item
661 If the variable @code{backup-by-copying} is non-@code{nil} (the
662 default is @code{nil}), use copying.
663
664 @item
665 Otherwise, if the variable @code{backup-by-copying-when-linked} is
666 non-@code{nil} (the default is @code{nil}), and the file has multiple
667 names, use copying.
668
669 @item
670 Otherwise, if the variable @code{backup-by-copying-when-mismatch} is
671 non-@code{nil} (the default is @code{t}), and renaming would change
672 the file's owner or group, use copying.
673
674 If you change @code{backup-by-copying-when-mismatch} to @code{nil},
675 Emacs checks the numeric user-id of the file's owner. If this is
676 higher than @code{backup-by-copying-when-privileged-mismatch}, then it
677 behaves as though @code{backup-by-copying-when-mismatch} is
678 non-@code{nil} anyway.
679
680 @item
681 Otherwise, renaming is the default choice.
682 @end itemize
683
684 When a file is managed with a version control system (@pxref{Version
685 Control}), Emacs does not normally make backups in the usual way for
686 that file. But check-in and check-out are similar in some ways to
687 making backups. One unfortunate similarity is that these operations
688 typically break hard links, disconnecting the file name you visited from
689 any alternate names for the same file. This has nothing to do with
690 Emacs---the version control system does it.
691
692 @node Customize Save
693 @subsection Customizing Saving of Files
694
695 @vindex require-final-newline
696 If the value of the variable @code{require-final-newline} is
697 @code{t}, saving or writing a file silently puts a newline at the end
698 if there isn't already one there. If the value is @code{visit}, Emacs
699 adds a newline at the end of any file that doesn't have one, just
700 after it visits the file. (This marks the buffer as modified, and you
701 can undo it.) If the value is @code{visit-save}, Emacs adds such
702 newlines both on visiting and on saving. If the value is @code{nil},
703 Emacs leaves the end of the file unchanged; any other non-@code{nil}
704 value means to asks you whether to add a newline. The default is
705 @code{nil}.
706
707 @vindex mode-require-final-newline
708 Some major modes are designed for specific kinds of files that are
709 always supposed to end in newlines. Such major modes set the variable
710 @code{require-final-newline} to the value of
711 @code{mode-require-final-newline}, which defaults to @code{t}. By
712 setting the latter variable, you can control how these modes handle
713 final newlines.
714
715 @vindex write-region-inhibit-fsync
716 Normally, when a program writes a file, the operating system briefly
717 caches the file's data in main memory before committing the data to
718 disk. This can greatly improve performance; for example, when running
719 on laptops, it can avoid a disk spin-up each time a file is written.
720 However, it risks data loss if the operating system crashes before
721 committing the cache to disk.
722
723 To lessen this risk, Emacs can invoke the @code{fsync} system call
724 after saving a file. Using @code{fsync} does not eliminate the risk
725 of data loss, partly because many systems do not implement
726 @code{fsync} properly, and partly because Emacs's file-saving
727 procedure typically relies also on directory updates that might not
728 survive a crash even if @code{fsync} works properly.
729
730 The @code{write-region-inhibit-fsync} variable controls whether
731 Emacs invokes @code{fsync} after saving a file. The variable's
732 default value is @code{nil} when Emacs is interactive, and @code{t}
733 when Emacs runs in batch mode.
734
735 Emacs never uses @code{fsync} when writing auto-save files, as these
736 files might lose data anyway.
737
738 @node Interlocking
739 @subsection Protection against Simultaneous Editing
740
741 @cindex file dates
742 @cindex simultaneous editing
743 Simultaneous editing occurs when two users visit the same file, both
744 make changes, and then both save them. If nobody is informed that
745 this is happening, whichever user saves first would later find that
746 his changes were lost.
747
748 On some systems, Emacs notices immediately when the second user starts
749 to change the file, and issues an immediate warning. On all systems,
750 Emacs checks when you save the file, and warns if you are about to
751 overwrite another user's changes. You can prevent loss of the other
752 user's work by taking the proper corrective action instead of saving the
753 file.
754
755 @findex ask-user-about-lock
756 @cindex locking files
757 When you make the first modification in an Emacs buffer that is
758 visiting a file, Emacs records that the file is @dfn{locked} by you.
759 (It does this by creating a specially-named symbolic link@footnote{If
760 your file system does not support symbolic links, a regular file is
761 used.} with special contents in the same directory.) Emacs removes the lock
762 when you save the changes. The idea is that the file is locked
763 whenever an Emacs buffer visiting it has unsaved changes.
764
765 @vindex create-lockfiles
766 You can prevent the creation of lock files by setting the variable
767 @code{create-lockfiles} to @code{nil}. @strong{Caution:} by
768 doing so you will lose the benefits that this feature provides.
769
770 @cindex collision
771 If you begin to modify the buffer while the visited file is locked by
772 someone else, this constitutes a @dfn{collision}. When Emacs detects a
773 collision, it asks you what to do, by calling the Lisp function
774 @code{ask-user-about-lock}. You can redefine this function for the sake
775 of customization. The standard definition of this function asks you a
776 question and accepts three possible answers:
777
778 @table @kbd
779 @item s
780 Steal the lock. Whoever was already changing the file loses the lock,
781 and you gain the lock.
782 @item p
783 Proceed. Go ahead and edit the file despite its being locked by someone else.
784 @item q
785 Quit. This causes an error (@code{file-locked}), and the buffer
786 contents remain unchanged---the modification you were trying to make
787 does not actually take place.
788 @end table
789
790 If Emacs or the operating system crashes, this may leave behind lock
791 files which are stale, so you may occasionally get warnings about
792 spurious collisions. When you determine that the collision is
793 spurious, just use @kbd{p} to tell Emacs to go ahead anyway.
794
795 Note that locking works on the basis of a file name; if a file has
796 multiple names, Emacs does not prevent two users from editing it
797 simultaneously under different names.
798
799 A lock file cannot be written in some circumstances, e.g., if Emacs
800 lacks the system permissions or cannot create lock files for some
801 other reason. In these cases, Emacs can still detect the collision
802 when you try to save a file, by checking the file's last-modification
803 date. If the file has changed since the last time Emacs visited or
804 saved it, that implies that changes have been made in some other way,
805 and will be lost if Emacs proceeds with saving. Emacs then displays a
806 warning message and asks for confirmation before saving; answer
807 @kbd{yes} to save, and @kbd{no} or @kbd{C-g} cancel the save.
808
809 If you are notified that simultaneous editing has already taken
810 place, one way to compare the buffer to its file is the @kbd{M-x
811 diff-buffer-with-file} command. @xref{Comparing Files}.
812
813 @node File Shadowing
814 @subsection Shadowing Files
815 @cindex shadow files
816 @cindex file shadows
817 @findex shadow-initialize
818
819 @table @kbd
820 @item M-x shadow-initialize
821 Set up file shadowing.
822 @item M-x shadow-define-literal-group
823 Declare a single file to be shared between sites.
824 @item M-x shadow-define-regexp-group
825 Make all files that match each of a group of files be shared between hosts.
826 @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
827 Define a shadow file cluster @var{name}.
828 @item M-x shadow-copy-files
829 Copy all pending shadow files.
830 @item M-x shadow-cancel
831 Cancel the instruction to shadow some files.
832 @end table
833
834 You can arrange to keep identical @dfn{shadow} copies of certain files
835 in more than one place---possibly on different machines. To do this,
836 first you must set up a @dfn{shadow file group}, which is a set of
837 identically-named files shared between a list of sites. The file
838 group is permanent and applies to further Emacs sessions as well as
839 the current one. Once the group is set up, every time you exit Emacs,
840 it will copy the file you edited to the other files in its group. You
841 can also do the copying without exiting Emacs, by typing @kbd{M-x
842 shadow-copy-files}.
843
844 To set up a shadow file group, use @kbd{M-x
845 shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}.
846 See their documentation strings for further information.
847
848 Before copying a file to its shadows, Emacs asks for confirmation.
849 You can answer ``no'' to bypass copying of this file, this time. If
850 you want to cancel the shadowing permanently for a certain file, use
851 @kbd{M-x shadow-cancel} to eliminate or change the shadow file group.
852
853 A @dfn{shadow cluster} is a group of hosts that share directories, so
854 that copying to or from one of them is sufficient to update the file
855 on all of them. Each shadow cluster has a name, and specifies the
856 network address of a primary host (the one we copy files to), and a
857 regular expression that matches the host names of all the other hosts
858 in the cluster. You can define a shadow cluster with @kbd{M-x
859 shadow-define-cluster}.
860
861 @node Time Stamps
862 @subsection Updating Time Stamps Automatically
863 @cindex time stamps
864 @cindex modification dates
865 @cindex locale, date format
866
867 You can arrange to put a time stamp in a file, so that it is updated
868 automatically each time you edit and save the file. The time stamp
869 must be in the first eight lines of the file, and you should insert it
870 like this:
871
872 @example
873 Time-stamp: <>
874 @end example
875
876 @noindent
877 or like this:
878
879 @example
880 Time-stamp: " "
881 @end example
882
883 @findex time-stamp
884 Then add the function @code{time-stamp} to the hook
885 @code{before-save-hook} (@pxref{Hooks}). When you save the file, this
886 function then automatically updates the time stamp with the current
887 date and time. You can also use the command @kbd{M-x time-stamp} to
888 update the time stamp manually. By default the time stamp is
889 formatted according to your locale setting (@pxref{Environment}) and
890 time zone (@pxref{Time of Day,,, elisp, The Emacs Lisp Reference
891 Manual}). For customizations, see the Custom group @code{time-stamp}.
892
893 @node Reverting
894 @section Reverting a Buffer
895 @findex revert-buffer
896 @cindex drastic changes
897 @cindex reread a file
898
899 If you have made extensive changes to a file-visiting buffer and
900 then change your mind, you can @dfn{revert} the changes and go back to
901 the saved version of the file. To do this, type @kbd{M-x
902 revert-buffer}. Since reverting unintentionally could lose a lot of
903 work, Emacs asks for confirmation first.
904
905 The @code{revert-buffer} command tries to position point in such a
906 way that, if the file was edited only slightly, you will be at
907 approximately the same part of the text as before. But if you have
908 made major changes, point may end up in a totally different location.
909
910 Reverting marks the buffer as not modified. It also clears the
911 buffer's undo history (@pxref{Undo}). Thus, the reversion cannot be
912 undone---if you change your mind yet again, you can't use the undo
913 commands to bring the reverted changes back.
914
915 Some kinds of buffers that are not associated with files, such as
916 Dired buffers, can also be reverted. For them, reverting means
917 recalculating their contents. Buffers created explicitly with
918 @kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error
919 if you try.
920
921 @vindex revert-without-query
922 When you edit a file that changes automatically and frequently---for
923 example, a log of output from a process that continues to run---it may
924 be useful for Emacs to revert the file without querying you. To
925 request this behavior, set the variable @code{revert-without-query} to
926 a list of regular expressions. When a file name matches one of these
927 regular expressions, @code{find-file} and @code{revert-buffer} will
928 revert it automatically if it has changed---provided the buffer itself
929 is not modified. (If you have edited the text, it would be wrong to
930 discard your changes.)
931
932 @cindex Global Auto-Revert mode
933 @cindex mode, Global Auto-Revert
934 @cindex Auto-Revert mode
935 @cindex mode, Auto-Revert
936 @findex global-auto-revert-mode
937 @findex auto-revert-mode
938 @findex auto-revert-tail-mode
939 @vindex auto-revert-interval
940 You can also tell Emacs to revert buffers periodically. To do this
941 for a specific buffer, enable the minor mode Auto-Revert mode by
942 typing @kbd{M-x auto-revert-mode}. This automatically reverts the
943 current buffer every five seconds; you can change the interval through
944 the variable @code{auto-revert-interval}. To do the same for all file
945 buffers, type @kbd{M-x global-auto-revert-mode} to enable Global
946 Auto-Revert mode. These minor modes do not check or revert remote
947 files, because that is usually too slow.
948
949 One use of Auto-Revert mode is to ``tail'' a file such as a system
950 log, so that changes made to that file by other programs are
951 continuously displayed. To do this, just move the point to the end of
952 the buffer, and it will stay there as the file contents change.
953 However, if you are sure that the file will only change by growing at
954 the end, use Auto-Revert Tail mode instead
955 (@code{auto-revert-tail-mode}). It is more efficient for this.
956 Auto-Revert Tail mode works also for remote files.
957
958 @xref{VC Undo}, for commands to revert to earlier versions of files
959 under version control. @xref{VC Mode Line}, for Auto Revert
960 peculiarities when visiting files under version control.
961
962 @ifnottex
963 @include arevert-xtra.texi
964 @end ifnottex
965
966 @node Auto Save
967 @section Auto-Saving: Protection Against Disasters
968 @cindex Auto Save mode
969 @cindex mode, Auto Save
970 @cindex crashes
971
972 From time to time, Emacs automatically saves each visited file in a
973 separate file, without altering the file you actually use. This is
974 called @dfn{auto-saving}. It prevents you from losing more than a
975 limited amount of work if the system crashes.
976
977 When Emacs determines that it is time for auto-saving, it considers
978 each buffer, and each is auto-saved if auto-saving is enabled for it
979 and it has been changed since the last time it was auto-saved. The
980 message @samp{Auto-saving...} is displayed in the echo area during
981 auto-saving, if any files are actually auto-saved. Errors occurring
982 during auto-saving are caught so that they do not interfere with the
983 execution of commands you have been typing.
984
985 @menu
986 * Files: Auto Save Files. The file where auto-saved changes are
987 actually made until you save the file.
988 * Control: Auto Save Control. Controlling when and how often to auto-save.
989 * Recover:: Recovering text from auto-save files.
990 @end menu
991
992 @node Auto Save Files
993 @subsection Auto-Save Files
994
995 Auto-saving does not normally save in the files that you visited,
996 because it can be very undesirable to save a change that you did not
997 want to make permanent. Instead, auto-saving is done in a different
998 file called the @dfn{auto-save file}, and the visited file is changed
999 only when you request saving explicitly (such as with @kbd{C-x C-s}).
1000
1001 Normally, the auto-save file name is made by appending @samp{#} to the
1002 front and rear of the visited file name. Thus, a buffer visiting file
1003 @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that
1004 are not visiting files are auto-saved only if you request it explicitly;
1005 when they are auto-saved, the auto-save file name is made by appending
1006 @samp{#} to the front and rear of buffer name, then
1007 adding digits and letters at the end for uniqueness. For
1008 example, the @file{*mail*} buffer in which you compose messages to be
1009 sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file
1010 names are made this way unless you reprogram parts of Emacs to do
1011 something different (the functions @code{make-auto-save-file-name} and
1012 @code{auto-save-file-name-p}). The file name to be used for auto-saving
1013 in a buffer is calculated when auto-saving is turned on in that buffer.
1014
1015 @cindex auto-save for remote files
1016 @vindex auto-save-file-name-transforms
1017 The variable @code{auto-save-file-name-transforms} allows a degree
1018 of control over the auto-save file name. It lets you specify a series
1019 of regular expressions and replacements to transform the auto save
1020 file name. The default value puts the auto-save files for remote
1021 files (@pxref{Remote Files}) into the temporary file directory on the
1022 local machine.
1023
1024 When you delete a substantial part of the text in a large buffer, auto
1025 save turns off temporarily in that buffer. This is because if you
1026 deleted the text unintentionally, you might find the auto-save file more
1027 useful if it contains the deleted text. To reenable auto-saving after
1028 this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
1029 auto-save-mode}.
1030
1031 @vindex auto-save-visited-file-name
1032 If you want auto-saving to be done in the visited file rather than
1033 in a separate auto-save file, set the variable
1034 @code{auto-save-visited-file-name} to a non-@code{nil} value. In this
1035 mode, there is no real difference between auto-saving and explicit
1036 saving.
1037
1038 @vindex delete-auto-save-files
1039 A buffer's auto-save file is deleted when you save the buffer in its
1040 visited file. (You can inhibit this by setting the variable
1041 @code{delete-auto-save-files} to @code{nil}.) Changing the visited
1042 file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames
1043 any auto-save file to go with the new visited name.
1044
1045 @node Auto Save Control
1046 @subsection Controlling Auto-Saving
1047
1048 @vindex auto-save-default
1049 @findex auto-save-mode
1050 Each time you visit a file, auto-saving is turned on for that file's
1051 buffer if the variable @code{auto-save-default} is non-@code{nil} (but
1052 not in batch mode; @pxref{Initial Options}). The default for this
1053 variable is @code{t}, so auto-saving is the usual practice for
1054 file-visiting buffers. To toggle auto-saving in the current buffer,
1055 type @kbd{M-x auto-save-mode}. Auto Save mode acts as a buffer-local
1056 minor mode (@pxref{Minor Modes}).
1057
1058 @vindex auto-save-interval
1059 Emacs auto-saves periodically based on how many characters you have
1060 typed since the last auto-save. The variable
1061 @code{auto-save-interval} specifies how many characters there are
1062 between auto-saves. By default, it is 300. Emacs doesn't accept
1063 values that are too small: if you customize @code{auto-save-interval}
1064 to a value less than 20, Emacs will behave as if the value is 20.
1065
1066 @vindex auto-save-timeout
1067 Auto-saving also takes place when you stop typing for a while. By
1068 default, it does this after 30 seconds of idleness (at this time,
1069 Emacs may also perform garbage collection; @pxref{Garbage
1070 Collection,,, elisp, The Emacs Lisp Reference Manual}). To change
1071 this interval, customize the variable @code{auto-save-timeout}. The
1072 actual time period is longer if the current buffer is long; this is a
1073 heuristic which aims to keep out of your way when you are editing long
1074 buffers, in which auto-save takes an appreciable amount of time.
1075 Auto-saving during idle periods accomplishes two things: first, it
1076 makes sure all your work is saved if you go away from the terminal for
1077 a while; second, it may avoid some auto-saving while you are actually
1078 typing.
1079
1080 Emacs also does auto-saving whenever it gets a fatal error. This
1081 includes killing the Emacs job with a shell command such as @samp{kill
1082 %emacs}, or disconnecting a phone line or network connection.
1083
1084 @findex do-auto-save
1085 You can perform an auto-save explicitly with the command @kbd{M-x
1086 do-auto-save}.
1087
1088 @node Recover
1089 @subsection Recovering Data from Auto-Saves
1090
1091 @findex recover-file
1092 You can use the contents of an auto-save file to recover from a loss
1093 of data with the command @kbd{M-x recover-file @key{RET} @var{file}
1094 @key{RET}}. This visits @var{file} and then (after your confirmation)
1095 restores the contents from its auto-save file @file{#@var{file}#}.
1096 You can then save with @kbd{C-x C-s} to put the recovered text into
1097 @var{file} itself. For example, to recover file @file{foo.c} from its
1098 auto-save file @file{#foo.c#}, do:
1099
1100 @example
1101 M-x recover-file @key{RET} foo.c @key{RET}
1102 yes @key{RET}
1103 C-x C-s
1104 @end example
1105
1106 Before asking for confirmation, @kbd{M-x recover-file} displays a
1107 directory listing describing the specified file and the auto-save file,
1108 so you can compare their sizes and dates. If the auto-save file
1109 is older, @kbd{M-x recover-file} does not offer to read it.
1110
1111 @findex recover-session
1112 If Emacs or the computer crashes, you can recover all the files you
1113 were editing from their auto save files with the command @kbd{M-x
1114 recover-session}. This first shows you a list of recorded interrupted
1115 sessions. Move point to the one you choose, and type @kbd{C-c C-c}.
1116
1117 Then @code{recover-session} asks about each of the files that were
1118 being edited during that session, asking whether to recover that file.
1119 If you answer @kbd{y}, it calls @code{recover-file}, which works in its
1120 normal fashion. It shows the dates of the original file and its
1121 auto-save file, and asks once again whether to recover that file.
1122
1123 When @code{recover-session} is done, the files you've chosen to
1124 recover are present in Emacs buffers. You should then save them. Only
1125 this---saving them---updates the files themselves.
1126
1127 @vindex auto-save-list-file-prefix
1128 Emacs records information about interrupted sessions in files named
1129 @file{.saves-@var{pid}-@var{hostname}} in the directory
1130 @file{~/.emacs.d/auto-save-list/}. This directory is determined by
1131 the variable @code{auto-save-list-file-prefix}. If you set
1132 @code{auto-save-list-file-prefix} to @code{nil}, sessions are not
1133 recorded for recovery.
1134
1135 @node File Aliases
1136 @section File Name Aliases
1137 @cindex symbolic links (visiting)
1138 @cindex hard links (visiting)
1139
1140 Symbolic links and hard links both make it possible for several file
1141 names to refer to the same file. Hard links are alternate names that
1142 refer directly to the file; all the names are equally valid, and no one
1143 of them is preferred. By contrast, a symbolic link is a kind of defined
1144 alias: when @file{foo} is a symbolic link to @file{bar}, you can use
1145 either name to refer to the file, but @file{bar} is the real name, while
1146 @file{foo} is just an alias. More complex cases occur when symbolic
1147 links point to directories.
1148
1149 @vindex find-file-existing-other-name
1150 @vindex find-file-suppress-same-file-warnings
1151 Normally, if you visit a file which Emacs is already visiting under
1152 a different name, Emacs displays a message in the echo area and uses
1153 the existing buffer visiting that file. This can happen on systems
1154 that support hard or symbolic links, or if you use a long file name on
1155 a system that truncates long file names, or on a case-insensitive file
1156 system. You can suppress the message by setting the variable
1157 @code{find-file-suppress-same-file-warnings} to a non-@code{nil}
1158 value. You can disable this feature entirely by setting the variable
1159 @code{find-file-existing-other-name} to @code{nil}: then if you visit
1160 the same file under two different names, you get a separate buffer for
1161 each file name.
1162
1163 @vindex find-file-visit-truename
1164 @cindex truenames of files
1165 @cindex file truenames
1166 If the variable @code{find-file-visit-truename} is non-@code{nil},
1167 then the file name recorded for a buffer is the file's @dfn{truename}
1168 (made by replacing all symbolic links with their target names), rather
1169 than the name you specify. Setting @code{find-file-visit-truename} also
1170 implies the effect of @code{find-file-existing-other-name}.
1171
1172 @cindex directory name abbreviation
1173 @vindex directory-abbrev-alist
1174 Sometimes, a directory is ordinarily accessed through a symbolic
1175 link, and you may want Emacs to preferentially show its linked
1176 name. To do this, customize @code{directory-abbrev-alist}. Each
1177 element in this list should have the form @code{(@var{from}
1178 . @var{to})}, which means to replace @var{from} with @var{to} whenever
1179 @var{from} appears in a directory name. The @var{from} string is a
1180 regular expression (@pxref{Regexps}). It is matched against directory
1181 names anchored at the first character, and should start with @samp{\`}
1182 (to support directory names with embedded newlines, which would defeat
1183 @samp{^}). The @var{to} string should be an ordinary absolute
1184 directory name pointing to the same directory. Do not use @samp{~} to
1185 stand for a home directory in the @var{to} string; Emacs performs
1186 these substitutions separately. Here's an example, from a system on
1187 which @file{/home/fsf} is normally accessed through a symbolic link
1188 named @file{/fsf}:
1189
1190 @example
1191 (("\\`/home/fsf" . "/fsf"))
1192 @end example
1193
1194 @node Directories
1195 @section File Directories
1196
1197 @cindex file directory
1198 @cindex directory listing
1199 The file system groups files into @dfn{directories}. A @dfn{directory
1200 listing} is a list of all the files in a directory. Emacs provides
1201 commands to create and delete directories, and to make directory
1202 listings in brief format (file names only) and verbose format (sizes,
1203 dates, and authors included). Emacs also includes a directory browser
1204 feature called Dired; see @ref{Dired}.
1205
1206 @table @kbd
1207 @item C-x C-d @var{dir-or-pattern} @key{RET}
1208 Display a brief directory listing (@code{list-directory}).
1209 @item C-u C-x C-d @var{dir-or-pattern} @key{RET}
1210 Display a verbose directory listing.
1211 @item M-x make-directory @key{RET} @var{dirname} @key{RET}
1212 Create a new directory named @var{dirname}.
1213 @item M-x delete-directory @key{RET} @var{dirname} @key{RET}
1214 Delete the directory named @var{dirname}. If it isn't empty,
1215 you will be asked whether you want to delete it recursively.
1216 @end table
1217
1218 @findex list-directory
1219 @kindex C-x C-d
1220 The command to display a directory listing is @kbd{C-x C-d}
1221 (@code{list-directory}). It reads using the minibuffer a file name
1222 which is either a directory to be listed or a wildcard-containing
1223 pattern for the files to be listed. For example,
1224
1225 @example
1226 C-x C-d /u2/emacs/etc @key{RET}
1227 @end example
1228
1229 @noindent
1230 lists all the files in directory @file{/u2/emacs/etc}. Here is an
1231 example of specifying a file name pattern:
1232
1233 @example
1234 C-x C-d /u2/emacs/src/*.c @key{RET}
1235 @end example
1236
1237 Normally, @kbd{C-x C-d} displays a brief directory listing containing
1238 just file names. A numeric argument (regardless of value) tells it to
1239 make a verbose listing including sizes, dates, and owners (like
1240 @samp{ls -l}).
1241
1242 @vindex list-directory-brief-switches
1243 @vindex list-directory-verbose-switches
1244 The text of a directory listing is mostly obtained by running
1245 @code{ls} in an inferior process. Two Emacs variables control the
1246 switches passed to @code{ls}: @code{list-directory-brief-switches} is
1247 a string giving the switches to use in brief listings (@code{"-CF"} by
1248 default), and @code{list-directory-verbose-switches} is a string
1249 giving the switches to use in a verbose listing (@code{"-l"} by
1250 default).
1251
1252 @vindex directory-free-space-program
1253 @vindex directory-free-space-args
1254 In verbose directory listings, Emacs adds information about the
1255 amount of free space on the disk that contains the directory. To do
1256 this, it runs the program specified by
1257 @code{directory-free-space-program} with arguments
1258 @code{directory-free-space-args}.
1259
1260 The command @kbd{M-x delete-directory} prompts for a directory name
1261 using the minibuffer, and deletes the directory if it is empty. If
1262 the directory is not empty, you will be asked whether you want to
1263 delete it recursively. On systems that have a ``Trash'' (or ``Recycle
1264 Bin'') feature, you can make this command move the specified directory
1265 to the Trash instead of deleting it outright, by changing the variable
1266 @code{delete-by-moving-to-trash} to @code{t}. @xref{Misc File Ops},
1267 for more information about using the Trash.
1268
1269 @node Comparing Files
1270 @section Comparing Files
1271 @cindex comparing files
1272
1273 @findex diff
1274 @vindex diff-switches
1275 The command @kbd{M-x diff} prompts for two file names, using the
1276 minibuffer, and displays the differences between the two files in a
1277 buffer named @file{*diff*}. This works by running the @command{diff}
1278 program, using options taken from the variable @code{diff-switches}.
1279 The value of @code{diff-switches} should be a string; the default is
1280 @code{"-u"} to specify a unified context diff.
1281 @c Note that the actual name of the info file is diffutils.info,
1282 @c but it adds a dir entry for diff too.
1283 @c On older systems, only "info diff" works, not "info diffutils".
1284 @xref{Top,, Diff, diff, Comparing and Merging Files}, for more
1285 information about the @command{diff} program.
1286
1287 The output of the @code{diff} command is shown using a major mode
1288 called Diff mode. @xref{Diff Mode}.
1289
1290 @findex diff-backup
1291 The command @kbd{M-x diff-backup} compares a specified file with its
1292 most recent backup. If you specify the name of a backup file,
1293 @code{diff-backup} compares it with the source file that it is a
1294 backup of. In all other respects, this behaves like @kbd{M-x diff}.
1295
1296 @findex diff-buffer-with-file
1297 The command @kbd{M-x diff-buffer-with-file} compares a specified
1298 buffer with its corresponding file. This shows you what changes you
1299 would make to the file if you save the buffer.
1300
1301 @findex compare-windows
1302 The command @kbd{M-x compare-windows} compares the text in the
1303 current window with that in the window that was the selected window
1304 before you selected the current one. (For more information about
1305 windows in Emacs, @ref{Windows}.) Comparison starts at point in each
1306 window, after pushing each initial point value on the mark ring in its
1307 respective buffer. Then it moves point forward in each window, one
1308 character at a time, until it reaches characters that don't match.
1309 Then the command exits.
1310
1311 If point in the two windows is followed by non-matching text when
1312 the command starts, @kbd{M-x compare-windows} tries heuristically to
1313 advance up to matching text in the two windows, and then exits. So if
1314 you use @kbd{M-x compare-windows} repeatedly, each time it either
1315 skips one matching range or finds the start of another.
1316
1317 @vindex compare-ignore-case
1318 @vindex compare-ignore-whitespace
1319 With a numeric argument, @code{compare-windows} ignores changes in
1320 whitespace. If the variable @code{compare-ignore-case} is
1321 non-@code{nil}, the comparison ignores differences in case as well.
1322 If the variable @code{compare-ignore-whitespace} is non-@code{nil},
1323 @code{compare-windows} normally ignores changes in whitespace, and a
1324 prefix argument turns that off.
1325
1326 @cindex Smerge mode
1327 @findex smerge-mode
1328 @cindex failed merges
1329 @cindex merges, failed
1330 @cindex comparing 3 files (@code{diff3})
1331 You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor
1332 mode for editing output from the @command{diff3} program. This is
1333 typically the result of a failed merge from a version control system
1334 update outside VC, due to conflicting changes to a file. Smerge
1335 mode provides commands to resolve conflicts by selecting specific
1336 changes.
1337
1338 @iftex
1339 @xref{Emerge,,, emacs-xtra, Specialized Emacs Features},
1340 @end iftex
1341 @ifnottex
1342 @xref{Emerge},
1343 @end ifnottex
1344 for the Emerge facility, which provides a powerful interface for
1345 merging files.
1346
1347 @node Diff Mode
1348 @section Diff Mode
1349 @cindex Diff mode
1350 @findex diff-mode
1351 @cindex patches, editing
1352
1353 Diff mode is a major mode used for the output of @kbd{M-x diff} and
1354 other similar commands. This kind of output is called a @dfn{patch},
1355 because it can be passed to the @command{patch} command to
1356 automatically apply the specified changes. To select Diff mode
1357 manually, type @kbd{M-x diff-mode}.
1358
1359 @cindex hunk, diff
1360 The changes specified in a patch are grouped into @dfn{hunks}, which
1361 are contiguous chunks of text that contain one or more changed lines.
1362 Hunks can also include unchanged lines to provide context for the
1363 changes. Each hunk is preceded by a @dfn{hunk header}, which
1364 specifies the old and new line numbers at which the hunk occurs. Diff
1365 mode highlights each hunk header, to distinguish it from the actual
1366 contents of the hunk.
1367
1368 @vindex diff-update-on-the-fly
1369 You can edit a Diff mode buffer like any other buffer. (If it is
1370 read-only, you need to make it writable first. @xref{Misc Buffer}.)
1371 Whenever you change a hunk, Diff mode attempts to automatically
1372 correct the line numbers in the hunk headers, to ensure that the patch
1373 remains correct. To disable automatic line number correction,
1374 change the variable @code{diff-update-on-the-fly} to @code{nil}.
1375
1376 Diff mode treats each hunk as an error message, similar to
1377 Compilation mode. Thus, you can use commands such as @kbd{C-x `} to
1378 visit the corresponding source locations. @xref{Compilation Mode}.
1379
1380 In addition, Diff mode provides the following commands to navigate,
1381 manipulate and apply parts of patches:
1382
1383 @table @kbd
1384 @item M-n
1385 @findex diff-hunk-next
1386 Move to the next hunk-start (@code{diff-hunk-next}).
1387
1388 @findex diff-auto-refine-mode
1389 @cindex mode, Diff Auto-Refine
1390 @cindex Diff Auto-Refine mode
1391 This command has a side effect: it @dfn{refines} the hunk you move to,
1392 highlighting its changes with better granularity. To disable this
1393 feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor
1394 mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by
1395 default, add this to your init file (@pxref{Hooks}):
1396
1397 @example
1398 (add-hook 'diff-mode-hook
1399 (lambda () (diff-auto-refine-mode -1)))
1400 @end example
1401
1402 @item M-p
1403 @findex diff-hunk-prev
1404 Move to the previous hunk-start (@code{diff-hunk-prev}). Like
1405 @kbd{M-n}, this has the side-effect of refining the hunk you move to,
1406 unless you disable Diff Auto-Refine mode.
1407
1408 @item M-@}
1409 @findex diff-file-next
1410 Move to the next file-start, in a multi-file patch
1411 (@code{diff-file-next}).
1412
1413 @item M-@{
1414 @findex diff-file-prev
1415 Move to the previous file-start, in a multi-file patch
1416 (@code{diff-file-prev}).
1417
1418 @item M-k
1419 @findex diff-hunk-kill
1420 Kill the hunk at point (@code{diff-hunk-kill}).
1421
1422 @item M-K
1423 @findex diff-file-kill
1424 In a multi-file patch, kill the current file part.
1425 (@code{diff-file-kill}).
1426
1427 @item C-c C-a
1428 @findex diff-apply-hunk
1429 @cindex patches, applying
1430 Apply this hunk to its target file (@code{diff-apply-hunk}). With a
1431 prefix argument of @kbd{C-u}, revert this hunk.
1432
1433 @item C-c C-b
1434 @findex diff-refine-hunk
1435 Highlight the changes of the hunk at point with a finer granularity
1436 (@code{diff-refine-hunk}). This allows you to see exactly which parts
1437 of each changed line were actually changed.
1438
1439 @item C-c C-c
1440 @findex diff-goto-source
1441 Go to the source file and line corresponding to this hunk
1442 (@code{diff-goto-source}).
1443
1444 @item C-c C-e
1445 @findex diff-ediff-patch
1446 Start an Ediff session with the patch (@code{diff-ediff-patch}).
1447 @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
1448
1449 @item C-c C-n
1450 @findex diff-restrict-view
1451 Restrict the view to the current hunk (@code{diff-restrict-view}).
1452 @xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the
1453 view to the current file of a multiple-file patch. To widen again,
1454 use @kbd{C-x n w} (@code{widen}).
1455
1456 @item C-c C-r
1457 @findex diff-reverse-direction
1458 Reverse the direction of comparison for the entire buffer
1459 (@code{diff-reverse-direction}).
1460
1461 @item C-c C-s
1462 @findex diff-split-hunk
1463 Split the hunk at point (@code{diff-split-hunk}). This is for
1464 manually editing patches, and only works with the @dfn{unified diff
1465 format} produced by the @option{-u} or @option{--unified} options to
1466 the @command{diff} program. If you need to split a hunk in the
1467 @dfn{context diff format} produced by the @option{-c} or
1468 @option{--context} options to @command{diff}, first convert the buffer
1469 to the unified diff format with @kbd{C-c C-u}.
1470
1471 @item C-c C-d
1472 @findex diff-unified->context
1473 Convert the entire buffer to the @dfn{context diff format}
1474 (@code{diff-unified->context}). With a prefix argument, convert only
1475 the text within the region.
1476
1477 @item C-c C-u
1478 @findex diff-context->unified
1479 Convert the entire buffer to unified diff format
1480 (@code{diff-context->unified}). With a prefix argument, convert
1481 unified format to context format. When the mark is active, convert
1482 only the text within the region.
1483
1484 @item C-c C-w
1485 @findex diff-ignore-whitespace-hunk
1486 Re-diff the current hunk, disregarding changes in whitespace
1487 (@code{diff-ignore-whitespace-hunk}).
1488
1489 @item C-x 4 A
1490 @findex diff-add-change-log-entries-other-window
1491 @findex add-change-log-entry-other-window@r{, in Diff mode}
1492 Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change
1493 Log}), for each one of the hunks
1494 (@code{diff-add-change-log-entries-other-window}). This creates a
1495 skeleton of the log of changes that you can later fill with the actual
1496 descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode
1497 operates on behalf of the current hunk's file, but gets the function
1498 name from the patch itself. This is useful for making log entries for
1499 functions that are deleted by the patch.
1500 @end table
1501
1502 @c Trailing whitespace is NOT shown by default.
1503 @c Emacs's dir-locals file enables this (for some reason).
1504 @cindex trailing whitespace, in patches
1505 @findex diff-delete-trailing-whitespace
1506 Patches sometimes include trailing whitespace on modified lines, as
1507 an unintentional and undesired change. There are two ways to deal
1508 with this problem. Firstly, if you enable Whitespace mode in a Diff
1509 buffer (@pxref{Useless Whitespace}), it automatically highlights
1510 trailing whitespace in modified lines. Secondly, you can use the
1511 command @kbd{M-x diff-delete-trailing-whitespace}, which searches for
1512 trailing whitespace in the lines modified by the patch, and removes
1513 that whitespace in both the patch and the patched source file(s).
1514 This command does not save the modifications that it makes, so you can
1515 decide whether to save the changes (the list of modified files is
1516 displayed in the echo area). With a prefix argument, it tries to
1517 modify the original source files rather than the patched source files.
1518
1519 @node Misc File Ops
1520 @section Miscellaneous File Operations
1521
1522 Emacs has commands for performing many other operations on files.
1523 All operate on one file; they do not accept wildcard file names.
1524
1525 @findex delete-file
1526 @cindex deletion (of files)
1527 @kbd{M-x delete-file} prompts for a file and deletes it. If you are
1528 deleting many files in one directory, it may be more convenient to use
1529 Dired rather than @code{delete-file}. @xref{Dired Deletion}.
1530
1531 @cindex trash
1532 @cindex recycle bin
1533 @kbd{M-x move-file-to-trash} moves a file into the system
1534 @dfn{Trash} (or @dfn{Recycle Bin}). This is a facility available on
1535 most operating systems; files that are moved into the Trash can be
1536 brought back later if you change your mind.
1537
1538 @vindex delete-by-moving-to-trash
1539 By default, Emacs deletion commands do @emph{not} use the Trash. To
1540 use the Trash (when it is available) for common deletion commands,
1541 change the variable @code{delete-by-moving-to-trash} to @code{t}.
1542 This affects the commands @kbd{M-x delete-file} and @kbd{M-x
1543 delete-directory} (@pxref{Directories}), as well as the deletion
1544 commands in Dired (@pxref{Dired Deletion}). Supplying a prefix
1545 argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes
1546 them delete outright, instead of using the Trash, regardless of
1547 @code{delete-by-moving-to-trash}.
1548
1549 @ifnottex
1550 If a file is under version control (@pxref{Version Control}), you
1551 should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x
1552 delete-file}. @xref{VC Delete/Rename}.
1553 @end ifnottex
1554
1555 @findex copy-file
1556 @cindex copying files
1557 @kbd{M-x copy-file} reads the file @var{old} and writes a new file
1558 named @var{new} with the same contents.
1559
1560 @findex copy-directory
1561 @kbd{M-x copy-directory} copies directories, similar to the
1562 @command{cp -r} shell command. It prompts for a directory @var{old}
1563 and a destination @var{new}. If @var{new} is an existing directory,
1564 it creates a copy of the @var{old} directory and puts it in @var{new}.
1565 If @var{new} is not an existing directory, it copies all the contents
1566 of @var{old} into a new directory named @var{new}.
1567
1568 @cindex renaming files
1569 @findex rename-file
1570 @kbd{M-x rename-file} reads two file names @var{old} and @var{new}
1571 using the minibuffer, then renames file @var{old} as @var{new}. If
1572 the file name @var{new} already exists, you must confirm with
1573 @kbd{yes} or renaming is not done; this is because renaming causes the
1574 old meaning of the name @var{new} to be lost. If @var{old} and
1575 @var{new} are on different file systems, the file @var{old} is copied
1576 and deleted. If the argument @var{new} is just a directory name, the
1577 real new name is in that directory, with the same non-directory
1578 component as @var{old}. For example, @kbd{M-x rename-file @key{RET}
1579 ~/foo @key{RET} /tmp @key{RET}} renames @file{~/foo} to
1580 @file{/tmp/foo}. The same rule applies to all the remaining commands
1581 in this section. All of them ask for confirmation when the new file
1582 name already exists, too.
1583
1584 @ifnottex
1585 If a file is under version control (@pxref{Version Control}), you
1586 should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x
1587 rename-file}. @xref{VC Delete/Rename}.
1588 @end ifnottex
1589
1590 @findex add-name-to-file
1591 @cindex hard links (creation)
1592 @kbd{M-x add-name-to-file} adds an additional name to an existing
1593 file without removing its old name. The new name is created as a
1594 hard link to the existing file. The new name must belong on the
1595 same file system that the file is on. On MS-Windows, this command
1596 works only if the file resides in an NTFS file system. On MS-DOS, it
1597 works by copying the file.
1598
1599 @findex make-symbolic-link
1600 @cindex symbolic links (creation)
1601 @kbd{M-x make-symbolic-link} reads two file names @var{target} and
1602 @var{linkname}, then creates a symbolic link named @var{linkname},
1603 which points at @var{target}. The effect is that future attempts to
1604 open file @var{linkname} will refer to whatever file is named
1605 @var{target} at the time the opening is done, or will get an error if
1606 the name @var{target} is nonexistent at that time. This command does
1607 not expand the argument @var{target}, so that it allows you to specify
1608 a relative name as the target of the link. On MS-Windows, this
1609 command works only on MS Windows Vista and later.
1610
1611 @kindex C-x i
1612 @findex insert-file
1613 @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
1614 contents of the specified file into the current buffer at point,
1615 leaving point unchanged before the contents. The position after the
1616 inserted contents is added to the mark ring, without activating the
1617 mark (@pxref{Mark Ring}).
1618
1619 @findex insert-file-literally
1620 @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
1621 except the file is inserted literally: it is treated as a sequence
1622 of @acronym{ASCII} characters with no special encoding or conversion,
1623 similar to the @kbd{M-x find-file-literally} command
1624 (@pxref{Visiting}).
1625
1626 @findex write-region
1627 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
1628 copies the contents of the region into the specified file. @kbd{M-x
1629 append-to-file} adds the text of the region to the end of the
1630 specified file. @xref{Accumulating Text}. The variable
1631 @code{write-region-inhibit-fsync} applies to these commands, as well
1632 as saving files; see @ref{Customize Save}.
1633
1634 @findex set-file-modes
1635 @cindex file modes
1636 @cindex file permissions
1637 @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file
1638 mode}, and applies that file mode to the specified file. File modes,
1639 also called @dfn{file permissions}, determine whether a file can be
1640 read, written to, or executed, and by whom. This command reads file
1641 modes using the same symbolic or octal format accepted by the
1642 @command{chmod} command; for instance, @samp{u+x} means to add
1643 execution permission for the user who owns the file. It has no effect
1644 on operating systems that do not support file modes. @code{chmod} is a
1645 convenience alias for this function.
1646
1647 @node Compressed Files
1648 @section Accessing Compressed Files
1649 @cindex compression
1650 @cindex uncompression
1651 @cindex Auto Compression mode
1652 @cindex mode, Auto Compression
1653 @pindex gzip
1654
1655 Emacs automatically uncompresses compressed files when you visit
1656 them, and automatically recompresses them if you alter them and save
1657 them. Emacs recognizes compressed files by their file names. File
1658 names ending in @samp{.gz} indicate a file compressed with
1659 @code{gzip}. Other endings indicate other compression programs.
1660
1661 Automatic uncompression and compression apply to all the operations in
1662 which Emacs uses the contents of a file. This includes visiting it,
1663 saving it, inserting its contents into a buffer, loading it, and byte
1664 compiling it.
1665
1666 @findex auto-compression-mode
1667 @vindex auto-compression-mode
1668 To disable this feature, type the command @kbd{M-x
1669 auto-compression-mode}. You can disable it permanently by
1670 customizing the variable @code{auto-compression-mode}.
1671
1672 @node File Archives
1673 @section File Archives
1674 @cindex mode, tar
1675 @cindex Tar mode
1676 @cindex file archives
1677
1678 A file whose name ends in @samp{.tar} is normally an @dfn{archive}
1679 made by the @code{tar} program. Emacs views these files in a special
1680 mode called Tar mode which provides a Dired-like list of the contents
1681 (@pxref{Dired}). You can move around through the list just as you
1682 would in Dired, and visit the subfiles contained in the archive.
1683 However, not all Dired commands are available in Tar mode.
1684
1685 If Auto Compression mode is enabled (@pxref{Compressed Files}), then
1686 Tar mode is used also for compressed archives---files with extensions
1687 @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}.
1688
1689 The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file
1690 into its own buffer. You can edit it there, and if you save the
1691 buffer, the edited version will replace the version in the Tar buffer.
1692 Clicking with the mouse on the file name in the Tar buffer does
1693 likewise. @kbd{v} extracts a file into a buffer in View mode
1694 (@pxref{View Mode}). @kbd{o} extracts the file and displays it in
1695 another window, so you could edit the file and operate on the archive
1696 simultaneously.
1697
1698 The @kbd{I} key adds a new (regular) file to the archive. The file
1699 is initially empty, but can readily be edited using the commands
1700 above. The command inserts the new file before the current one, so
1701 that using it on the topmost line of the Tar buffer makes the new file
1702 the first one in the archive, and using it at the end of the buffer
1703 makes it the last one.
1704
1705 @kbd{d} marks a file for deletion when you later use @kbd{x}, and
1706 @kbd{u} unmarks a file, as in Dired. @kbd{C} copies a file from the
1707 archive to disk and @kbd{R} renames a file within the archive.
1708 @kbd{g} reverts the buffer from the archive on disk. The keys
1709 @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission bits,
1710 group, and owner, respectively.
1711
1712 Saving the Tar buffer writes a new version of the archive to disk with
1713 the changes you made to the components.
1714
1715 You don't need the @code{tar} program to use Tar mode---Emacs reads
1716 the archives directly. However, accessing compressed archives
1717 requires the appropriate uncompression program.
1718
1719 @cindex Archive mode
1720 @cindex mode, archive
1721 @cindex @code{arc}
1722 @cindex @code{jar}
1723 @cindex @code{rar}
1724 @cindex @code{zip}
1725 @cindex @code{lzh}
1726 @cindex @code{zoo}
1727 @cindex @code{7z}
1728 @pindex arc
1729 @pindex jar
1730 @pindex zip
1731 @pindex rar
1732 @pindex lzh
1733 @pindex zoo
1734 @pindex 7z
1735 @cindex Java class archives
1736 @cindex unzip archives
1737 A separate but similar Archive mode is used for @code{arc},
1738 @code{jar}, @code{lzh}, @code{zip}, @code{rar}, @code{7z}, and
1739 @code{zoo} archives, as well as @code{exe} files that are
1740 self-extracting executables.
1741
1742 The key bindings of Archive mode are similar to those in Tar mode,
1743 with the addition of the @kbd{m} key which marks a file for subsequent
1744 operations, and @kbd{M-@key{DEL}} which unmarks all the marked files.
1745 Also, the @kbd{a} key toggles the display of detailed file
1746 information, for those archive types where it won't fit in a single
1747 line. Operations such as renaming a subfile, or changing its mode or
1748 owner, are supported only for some of the archive formats.
1749
1750 Unlike Tar mode, Archive mode runs the archiving programs to unpack
1751 and repack archives. However, you don't need these programs to look
1752 at the archive table of contents, only to extract or manipulate the
1753 subfiles in the archive. Details of the program names and their
1754 options can be set in the @samp{Archive} Customize group
1755 (@pxref{Customization Groups}).
1756
1757 @node Remote Files
1758 @section Remote Files
1759
1760 @cindex Tramp
1761 @cindex FTP
1762 @cindex remote file access
1763 You can refer to files on other machines using a special file name
1764 syntax:
1765
1766 @example
1767 @group
1768 /@var{host}:@var{filename}
1769 /@var{user}@@@var{host}:@var{filename}
1770 /@var{user}@@@var{host}#@var{port}:@var{filename}
1771 /@var{method}:@var{user}@@@var{host}:@var{filename}
1772 /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
1773 @end group
1774 @end example
1775
1776 @noindent
1777 To carry out this request, Emacs uses a remote-login program such as
1778 @command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}.
1779 You can always specify in the file name which method to use---for
1780 example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP,
1781 whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses
1782 @command{ssh}. When you don't specify a method in the file name,
1783 Emacs chooses the method as follows:
1784
1785 @enumerate
1786 @item
1787 If the host name starts with @samp{ftp.} (with dot), Emacs uses FTP.
1788 @item
1789 If the user name is @samp{ftp} or @samp{anonymous}, Emacs uses FTP.
1790 @item
1791 If the variable @code{tramp-default-method} is set to @samp{ftp},
1792 Emacs uses FTP.
1793 @item
1794 If @command{ssh-agent} is running, Emacs uses @command{scp}.
1795 @item
1796 Otherwise, Emacs uses @command{ssh}.
1797 @end enumerate
1798
1799 @cindex disabling remote files
1800 @noindent
1801 You can entirely turn off the remote file name feature by setting the
1802 variable @code{tramp-mode} to @code{nil}. You can turn off the
1803 feature in individual cases by quoting the file name with @samp{/:}
1804 (@pxref{Quoted File Names}).
1805
1806 @cindex ange-ftp
1807 Remote file access through FTP is handled by the Ange-FTP package, which
1808 is documented in the following. Remote file access through the other
1809 methods is handled by the Tramp package, which has its own manual.
1810 @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}.
1811
1812 @vindex ange-ftp-default-user
1813 @cindex user name for remote file access
1814 When the Ange-FTP package is used, Emacs logs in through FTP using
1815 the name @var{user}, if that is specified in the remote file name. If
1816 @var{user} is unspecified, Emacs logs in using your user name on the
1817 local system; but if you set the variable @code{ange-ftp-default-user}
1818 to a string, that string is used instead. When logging in, Emacs may
1819 also ask for a password.
1820
1821 @cindex backups for remote files
1822 @vindex ange-ftp-make-backup-files
1823 For performance reasons, Emacs does not make backup files for files
1824 accessed via FTP by default. To make it do so, change the variable
1825 @code{ange-ftp-make-backup-files} to a non-@code{nil} value.
1826
1827 By default, auto-save files for remote files are made in the
1828 temporary file directory on the local machine, as specified by the
1829 variable @code{auto-save-file-name-transforms}. @xref{Auto Save
1830 Files}.
1831
1832 @cindex anonymous FTP
1833 @vindex ange-ftp-generate-anonymous-password
1834 To visit files accessible by anonymous FTP, you use special user
1835 names @samp{anonymous} or @samp{ftp}. Passwords for these user names
1836 are handled specially. The variable
1837 @code{ange-ftp-generate-anonymous-password} controls what happens: if
1838 the value of this variable is a string, then that string is used as
1839 the password; if non-@code{nil} (the default), then the value of
1840 @code{user-mail-address} is used; if @code{nil}, then Emacs prompts
1841 you for a password as usual (@pxref{Passwords}).
1842
1843 @cindex firewall, and accessing remote files
1844 @cindex gateway, and remote file access with @code{ange-ftp}
1845 @vindex ange-ftp-smart-gateway
1846 @vindex ange-ftp-gateway-host
1847 Sometimes you may be unable to access files on a remote machine
1848 because a @dfn{firewall} in between blocks the connection for security
1849 reasons. If you can log in on a @dfn{gateway} machine from which the
1850 target files @emph{are} accessible, and whose FTP server supports
1851 gatewaying features, you can still use remote file names; all you have
1852 to do is specify the name of the gateway machine by setting the
1853 variable @code{ange-ftp-gateway-host}, and set
1854 @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able
1855 to make remote file names work, but the procedure is complex. You can
1856 read the instructions by typing @kbd{M-x finder-commentary @key{RET}
1857 ange-ftp @key{RET}}.
1858
1859 @node Quoted File Names
1860 @section Quoted File Names
1861
1862 @cindex quoting file names
1863 @cindex file names, quote special characters
1864 You can @dfn{quote} an absolute file name to prevent special
1865 characters and syntax in it from having their special effects.
1866 The way to do this is to add @samp{/:} at the beginning.
1867
1868 For example, you can quote a local file name which appears remote, to
1869 prevent it from being treated as a remote file name. Thus, if you have
1870 a directory named @file{/foo:} and a file named @file{bar} in it, you
1871 can refer to that file in Emacs as @samp{/:/foo:/bar}.
1872
1873 @samp{/:} can also prevent @samp{~} from being treated as a special
1874 character for a user's home directory. For example, @file{/:/tmp/~hack}
1875 refers to a file whose name is @file{~hack} in directory @file{/tmp}.
1876
1877 Quoting with @samp{/:} is also a way to enter in the minibuffer a
1878 file name that contains @samp{$}. In order for this to work, the
1879 @samp{/:} must be at the beginning of the minibuffer contents. (You
1880 can also double each @samp{$}; see @ref{File Names with $}.)
1881
1882 You can also quote wildcard characters with @samp{/:}, for visiting.
1883 For example, @file{/:/tmp/foo*bar} visits the file
1884 @file{/tmp/foo*bar}.
1885
1886 Another method of getting the same result is to enter
1887 @file{/tmp/foo[*]bar}, which is a wildcard specification that matches
1888 only @file{/tmp/foo*bar}. However, in many cases there is no need to
1889 quote the wildcard characters because even unquoted they give the
1890 right result. For example, if the only file name in @file{/tmp} that
1891 starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar},
1892 then specifying @file{/tmp/foo*bar} will visit only
1893 @file{/tmp/foo*bar}.
1894
1895 @node File Name Cache
1896 @section File Name Cache
1897
1898 @cindex file name caching
1899 @cindex cache of file names
1900 @pindex find
1901 @kindex C-TAB
1902 @findex file-cache-minibuffer-complete
1903 You can use the @dfn{file name cache} to make it easy to locate a
1904 file by name, without having to remember exactly where it is located.
1905 When typing a file name in the minibuffer, @kbd{C-@key{TAB}}
1906 (@code{file-cache-minibuffer-complete}) completes it using the file
1907 name cache. If you repeat @kbd{C-@key{TAB}}, that cycles through the
1908 possible completions of what you had originally typed. (However, note
1909 that the @kbd{C-@key{TAB}} character cannot be typed on most text
1910 terminals.)
1911
1912 The file name cache does not fill up automatically. Instead, you
1913 load file names into the cache using these commands:
1914
1915 @findex file-cache-add-directory
1916 @table @kbd
1917 @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET}
1918 Add each file name in @var{directory} to the file name cache.
1919 @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET}
1920 Add each file name in @var{directory} and all of its nested
1921 subdirectories to the file name cache.
1922 @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET}
1923 Add each file name in @var{directory} and all of its nested
1924 subdirectories to the file name cache, using @command{locate} to find
1925 them all.
1926 @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET}
1927 Add each file name in each directory listed in @var{variable} to the
1928 file name cache. @var{variable} should be a Lisp variable whose value
1929 is a list of directory names, like @code{load-path}.
1930 @item M-x file-cache-clear-cache @key{RET}
1931 Clear the cache; that is, remove all file names from it.
1932 @end table
1933
1934 The file name cache is not persistent: it is kept and maintained
1935 only for the duration of the Emacs session. You can view the contents
1936 of the cache with the @code{file-cache-display} command.
1937
1938 @node File Conveniences
1939 @section Convenience Features for Finding Files
1940
1941 In this section, we introduce some convenient facilities for finding
1942 recently-opened files, reading file names from a buffer, and viewing
1943 image files.
1944
1945 @findex recentf-mode
1946 @vindex recentf-mode
1947 @findex recentf-save-list
1948 @findex recentf-edit-list
1949 If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
1950 @samp{File} menu includes a submenu containing a list of recently
1951 opened files. @kbd{M-x recentf-save-list} saves the current
1952 @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list}
1953 edits it.
1954
1955 @c FIXME partial-completion-mode (complete.el) is obsolete.
1956 The @kbd{M-x ffap} command generalizes @code{find-file} with more
1957 powerful heuristic defaults (@pxref{FFAP}), often based on the text at
1958 point. Partial Completion mode offers other features extending
1959 @code{find-file}, which can be used with @code{ffap}.
1960 @xref{Completion Options}.
1961
1962 @findex image-mode
1963 @findex image-toggle-display
1964 @findex image-next-file
1965 @findex image-previous-file
1966 @cindex images, viewing
1967 Visiting image files automatically selects Image mode. In this
1968 major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display})
1969 to toggle between displaying the file as an image in the Emacs buffer,
1970 and displaying its underlying text (or raw byte) representation.
1971 Additionally you can type @kbd{C-c C-x} (@code{image-toggle-hex-display})
1972 to toggle between displaying the file as an image in the Emacs buffer,
1973 and displaying it in hex representation.
1974 Displaying the file as an image works only if Emacs is compiled with
1975 support for displaying such images. If the displayed image is wider
1976 or taller than the frame, the usual point motion keys (@kbd{C-f},
1977 @kbd{C-p}, and so forth) cause different parts of the image to be
1978 displayed. You can press @kbd{n} (@code{image-next-file}) and @kbd{p}
1979 (@code{image-previous-file}) to visit the next image file and the
1980 previous image file in the same directory, respectively.
1981
1982 @findex image-toggle-animation
1983 @findex image-next-frame
1984 @findex image-previous-frame
1985 @findex image-goto-frame
1986 @findex image-increase-speed
1987 @findex image-decrease-speed
1988 @findex image-reset-speed
1989 @findex image-reverse-speed
1990 @vindex image-animate-loop
1991 @cindex image animation
1992 @cindex animated images
1993 If the image can be animated, the command @key{RET}
1994 (@code{image-toggle-animation}) starts or stops the animation.
1995 Animation plays once, unless the option @code{image-animate-loop} is
1996 non-@code{nil}. With @kbd{f} (@code{image-next-frame}) and @kbd{b}
1997 (@code{image-previous-frame}) you can step through the individual
1998 frames. Both commands accept a numeric prefix to step through several
1999 frames at once. You can go to a specific frame with @kbd{F}
2000 (@code{image-goto-frame}). Frames are indexed from 1. Typing @kbd{a
2001 +} (@code{image-increase-speed}) increases the speed of the animation,
2002 @kbd{a -} (@code{image-decrease-speed}) decreases it, and @kbd{a r}
2003 (@code{image-reverse-speed}) reverses it. The command @kbd{a 0}
2004 (@code{image-reset-speed}) resets the speed to the original value.
2005
2006 @cindex ImageMagick support
2007 @vindex imagemagick-enabled-types
2008 @vindex imagemagick-types-inhibit
2009 If Emacs was compiled with support for the ImageMagick library, it
2010 can use ImageMagick to render a wide variety of images. The variable
2011 @code{imagemagick-enabled-types} lists the image types that Emacs may
2012 render using ImageMagick; each element in the list should be an
2013 internal ImageMagick name for an image type, as a symbol or an
2014 equivalent string (e.g., @code{BMP} for @file{.bmp} images). To
2015 enable ImageMagick for all possible image types, change
2016 @code{imagemagick-enabled-types} to @code{t}. The variable
2017 @code{imagemagick-types-inhibit} lists the image types which should
2018 never be rendered using ImageMagick, regardless of the value of
2019 @code{imagemagick-enabled-types} (the default list includes types like
2020 @code{C} and @code{HTML}, which ImageMagick can render as an image
2021 but Emacs should not). To disable ImageMagick entirely, change
2022 @code{imagemagick-types-inhibit} to @code{t}.
2023
2024 @findex thumbs-mode
2025 @findex mode, thumbs
2026 The Image-Dired package can also be used to view images as
2027 thumbnails. @xref{Image-Dired}.
2028
2029 @node Filesets
2030 @section Filesets
2031 @cindex filesets
2032 @cindex sets of files
2033
2034 @findex filesets-init
2035 If you regularly edit a certain group of files, you can define them
2036 as a @dfn{fileset}. This lets you perform certain operations, such as
2037 visiting, @code{query-replace}, and shell commands on all the files at
2038 once. To make use of filesets, you must first add the expression
2039 @code{(filesets-init)} to your init file (@pxref{Init File}). This
2040 adds a @samp{Filesets} menu to the menu bar.
2041
2042 @findex filesets-add-buffer
2043 @findex filesets-remove-buffer
2044 The simplest way to define a fileset is by adding files to it one at
2045 a time. To add a file to fileset @var{name}, visit the file and type
2046 @kbd{M-x filesets-add-buffer @key{RET} @var{name} @key{RET}}. If
2047 there is no fileset @var{name}, this creates a new one, which
2048 initially contains only the current file. The command @kbd{M-x
2049 filesets-remove-buffer} removes the current file from a fileset.
2050
2051 You can also edit the list of filesets directly, with @kbd{M-x
2052 filesets-edit} (or by choosing @samp{Edit Filesets} from the
2053 @samp{Filesets} menu). The editing is performed in a Customize buffer
2054 (@pxref{Easy Customization}). Normally, a fileset is a simple list of
2055 files, but you can also define a fileset as a regular expression
2056 matching file names. Some examples of these more complicated filesets
2057 are shown in the Customize buffer. Remember to select @samp{Save for
2058 future sessions} if you want to use the same filesets in future Emacs
2059 sessions.
2060
2061 You can use the command @kbd{M-x filesets-open} to visit all the
2062 files in a fileset, and @kbd{M-x filesets-close} to close them. Use
2063 @kbd{M-x filesets-run-cmd} to run a shell command on all the files in
2064 a fileset. These commands are also available from the @samp{Filesets}
2065 menu, where each existing fileset is represented by a submenu.
2066
2067 @xref{Version Control}, for a different concept of filesets:
2068 groups of files bundled together for version control operations.
2069 Filesets of that type are unnamed, and do not persist across Emacs
2070 sessions.