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