1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Files, Buffers, Keyboard Macros, Top
9 The operating system stores data permanently in named @dfn{files}, so
10 most of the text you edit with Emacs comes from a file and is ultimately
13 To edit a file, you must tell Emacs to read the file and prepare a
14 buffer containing a copy of the file's text. This is called
15 @dfn{visiting} the file. Editing commands apply directly to text in the
16 buffer; that is, to the copy inside Emacs. Your changes appear in the
17 file itself only when you @dfn{save} the buffer back into the file.
19 In addition to visiting and saving files, Emacs can delete, copy,
20 rename, and append to files, keep multiple versions of them, and operate
24 * File Names:: How to type and edit file-name arguments.
25 * Visiting:: Visiting a file prepares Emacs to edit the file.
26 * Saving:: Saving makes your changes permanent.
27 * Reverting:: Reverting cancels all the changes not saved.
29 * Autorevert:: Auto Reverting non-file buffers.
31 * Auto Save:: Auto Save periodically protects against loss of data.
32 * File Aliases:: Handling multiple names for one file.
33 * Directories:: Creating, deleting, and listing file directories.
34 * Comparing Files:: Finding where two files differ.
35 * Diff Mode:: Mode for editing file differences.
36 * Misc File Ops:: Other things you can do on files.
37 * Compressed Files:: Accessing compressed files.
38 * File Archives:: Operating on tar, zip, jar etc. archive files.
39 * Remote Files:: Accessing files on other sites.
40 * Quoted File Names:: Quoting special characters in file names.
41 * File Name Cache:: Completion against a list of files you often use.
42 * File Conveniences:: Convenience Features for Finding Files.
43 * Filesets:: Handling sets of files.
50 Many Emacs commands that operate on a file require you to specify
51 the file name, using the minibuffer (@pxref{Minibuffer}). You can use
52 @dfn{completion} to specify long file names (@pxref{Completion}).
53 Note that file name completion ignores file names whose extensions
54 appear in the variable @code{completion-ignored-extensions}
55 (@pxref{Completion Options}).
57 For most operations, there is a @dfn{default file name} which is
58 used if you type just @key{RET} to enter an empty argument. Normally,
59 the default file name is the name of the file visited in the current
62 @vindex default-directory
63 @vindex insert-default-directory
64 Each buffer has a @dfn{default directory} which is normally the same
65 as the directory of the file visited in that buffer. For example, if
66 the default file name is @file{/u/rms/gnu/gnu.tasks}, the default
67 directory is normally @file{/u/rms/gnu/}. The default directory is
68 kept in the variable @code{default-directory}, which has a separate
69 value in every buffer. When a command reads a file name using the
70 minibuffer, the default directory usually serves as the initial
71 contents of the minibuffer. To inhibit the insertion of the default
72 directory, set the variable @code{insert-default-directory} to
75 If you enter a file name without a directory, that specifies a file
76 in the default directory. If you specify a directory in a relative
77 fashion, with a name that does not start with a slash, it is
78 interpreted with respect to the default directory. For example,
79 suppose the default directory is @file{/u/rms/gnu/}. Entering just
80 @samp{foo} in the minibuffer, with a directory omitted, specifies the
81 file @file{/u/rms/gnu/foo}; entering @samp{../.login} specifies
82 @file{/u/rms/.login}; and entering @samp{new/foo} specifies
83 @file{/u/rms/gnu/new/foo}.
85 When typing a file name into the minibuffer, you can make use of a
86 couple of shortcuts: a double slash is interpreted as ``ignore
87 everything before the second slash in the pair,'' and @samp{~/} is
88 interpreted as your home directory. @xref{Minibuffer File}, for more
89 information about these shortcuts.
93 The command @kbd{M-x pwd} displays the default directory, and the
94 command @kbd{M-x cd} sets it to a value read using the minibuffer. A
95 buffer's default directory changes only when the @code{cd} command is
96 used. A file-visiting buffer's default directory is initialized to
97 the directory of the file it visits. If you create a buffer with
98 @kbd{C-x b}, its default directory is copied from that of the buffer
99 that was current at the time (@pxref{Select Buffer}).
101 @cindex environment variables in file names
102 @cindex expansion of environment variables
103 @cindex @code{$} in file names
104 @anchor{File Names with $}The character @samp{$} is used to
105 substitute an environment variable into a file name. The name of the
106 environment variable consists of all the alphanumeric characters after
107 the @samp{$}; alternatively, it can be enclosed in braces after the
108 @samp{$}. For example, if you have used the shell command
109 @command{export FOO=rms/hacks} to set up an environment variable named
110 @env{FOO}, then both @file{/u/$FOO/test.c} and
111 @file{/u/$@{FOO@}/test.c} are abbreviations for
112 @file{/u/rms/hacks/test.c}. If the environment variable is not
113 defined, no substitution occurs, so that the character @samp{$} stands
116 Note that environment variables affect Emacs only if they are
117 applied before Emacs is started.
119 To access a file with @samp{$} in its name, if the @samp{$} causes
120 expansion, type @samp{$$}. This pair is converted to a single
121 @samp{$} at the same time that variable substitution is performed for
122 a single @samp{$}. Alternatively, quote the whole file name with
123 @samp{/:} (@pxref{Quoted File Names}). File names which begin with a
124 literal @samp{~} should also be quoted with @samp{/:}.
126 You can include non-@acronym{ASCII} characters in file names if you set the
127 variable @code{file-name-coding-system} to a non-@code{nil} value.
128 @xref{File Name Coding}.
131 @section Visiting Files
132 @cindex visiting files
137 Visit a file (@code{find-file}).
139 Visit a file for viewing, without allowing changes to it
140 (@code{find-file-read-only}).
142 Visit a different file instead of the one visited last
143 (@code{find-alternate-file}).
145 Visit a file, in another window (@code{find-file-other-window}). Don't
146 alter what is displayed in the selected window.
148 Visit a file, in a new frame (@code{find-file-other-frame}). Don't
149 alter what is displayed in the selected frame.
150 @item M-x find-file-literally
151 Visit a file with no conversion of the contents.
154 @cindex files, visiting and saving
156 @dfn{Visiting} a file means reading its contents into an Emacs
157 buffer so you can edit them. Emacs makes a new buffer for each file
160 Emacs normally constructs the buffer name from the file name,
161 omitting the directory name. For example, a file named
162 @file{/usr/rms/emacs.tex} is visited in a buffer named
163 @samp{emacs.tex}. If there is already a buffer with that name, Emacs
164 constructs a unique name; the normal method is to append @samp{<2>},
165 @samp{<3>}, and so on, but you can select other methods.
168 Each window's mode line shows the name of the buffer that is being
169 displayed in that window, so you can always tell what buffer you are
170 editing. @pxref{Mode Line}.
172 The changes you make with editing commands are made in the Emacs
173 buffer. They do not take effect in the file that you visited, or any
174 permanent place, until you @dfn{save} the buffer (@pxref{Saving}).
176 @cindex modified (buffer)
177 If a buffer contains changes that have not been saved, we say the
178 buffer is @dfn{modified}. This implies that some changes will be lost
179 if the buffer is not saved. The mode line displays two stars near the
180 left margin to indicate that the buffer is modified.
184 To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the
185 minibuffer to enter the name of the desired file. The usual
186 defaulting and completion behavior is available in this minibuffer
187 (@pxref{Minibuffer File}). Note, also, that completion ignores
188 certain file names (@pxref{Completion Options}). While in the
189 minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}.
191 Your can tell that @kbd{C-x C-f} has completed successfully by the
192 appearance of new text on the screen and a new buffer name in the mode
193 line. If the specified file does not exist and you could not create
194 it, or exists but you can't read it, an error message is displayed in
197 If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
198 another copy. It selects the existing buffer containing that file.
199 However, before doing so, it checks whether the file itself has changed
200 since you visited or saved it last. If the file has changed, Emacs offers
203 @vindex large-file-warning-threshold
204 @cindex file, warning when size is large
205 @cindex size of file, warning when visiting
206 @cindex maximum buffer size exceeded, error message
207 If you try to visit a file larger than
208 @code{large-file-warning-threshold} (the default is 10000000, which is
209 about 10 megabytes), Emacs asks you for confirmation first. You can
210 answer @kbd{y} to proceed with visiting the file. Note, however, that
211 Emacs cannot visit files that are larger than the maximum Emacs buffer
212 size, which is limited by the amount of memory Emacs can allocate
213 and by the integers that Emacs can represent
214 (@pxref{Buffers}). If you try, Emacs will display an error message
215 saying that the maximum buffer size has been exceeded.
217 @cindex wildcard characters in file names
218 @vindex find-file-wildcards
219 If the file name you specify contains shell-style wildcard
220 characters, Emacs visits all the files that match it. (On
221 case-insensitive filesystems, Emacs matches the wildcards disregarding
222 the letter case.) Wildcards include @samp{?}, @samp{*}, and
223 @samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file
224 name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted
225 File Names}, for information on how to visit a file whose name
226 actually contains wildcard characters. You can disable the wildcard
227 feature by customizing @code{find-file-wildcards}.
229 @cindex file selection dialog
230 On graphical displays, there are two additional methods for visiting
231 files. Firstly, when Emacs is built with a suitable GUI toolkit,
232 commands invoked with the mouse (by clicking on the menu bar or tool
233 bar) use the toolkit's standard ``File Selection'' dialog instead of
234 prompting for the file name in the minibuffer. On GNU/Linux and Unix
235 platforms, Emacs does this when built with GTK, LessTif, and Motif
236 toolkits; on MS-Windows and Mac, the GUI version does that by default.
237 For information on how to customize this, see @ref{Dialog Boxes}.
239 Secondly, Emacs supports ``drag and drop'': dropping a file into an
240 ordinary Emacs window visits the file using that window. As an
241 exception, dropping a file into a window displaying a Dired buffer
242 moves or copies the file into the displayed directory. For details,
243 see @ref{Drag and Drop}, and @ref{Misc Dired Features}.
245 @cindex creating files
246 What if you want to create a new file? Just visit it. Emacs
247 displays @samp{(New file)} in the echo area, but in other respects
248 behaves as if you had visited an existing empty file. If you make
249 changes and save them, the file is created.
251 @cindex minibuffer confirmation
252 @cindex confirming in the minibuffer
253 @vindex confirm-nonexistent-file-or-buffer
254 When @key{TAB} completion results in a nonexistent file name and you
255 type @key{RET} immediately to visit it, Emacs asks for confirmation;
256 this is because it's possible that you expected completion to go
257 further and give you an existing file's name. The string
258 @samp{[Confirm]} appears for a short time after the file name to
259 indicate the need to confirm in this way. Type @key{RET} to confirm
260 and visit the nonexistent file. The variable
261 @code{confirm-nonexistent-file-or-buffer} controls whether Emacs asks
262 for confirmation before visiting a new file. The default value,
263 @code{after-completion}, gives the behavior we have just described.
264 If the value is @code{nil}, Emacs never asks for confirmation; for any
265 other non-@code{nil} value, Emacs always asks for confirmation. This
266 variable also affects the @code{switch-to-buffer} command
267 (@pxref{Select Buffer}). @xref{Completion}, for more information
271 @findex find-alternate-file
272 If you visit a nonexistent file unintentionally (because you typed
273 the wrong file name), type @kbd{C-x C-v} (@code{find-alternate-file})
274 to visit the file you really wanted. @kbd{C-x C-v} is similar to
275 @kbd{C-x C-f}, but it kills the current buffer (after first offering
276 to save it if it is modified). When @kbd{C-x C-v} reads the file name
277 to visit, it inserts the entire default file name in the buffer, with
278 point just after the directory part; this is convenient if you made a
279 slight error in typing the name.
281 @vindex find-file-run-dired
282 If you ``visit'' a file that is actually a directory, Emacs invokes
283 Dired, the Emacs directory browser; this lets you ``edit'' the
284 contents of the directory. @xref{Dired}. You can disable this
285 behavior by setting the variable @code{find-file-run-dired} to
286 @code{nil}; in that case, it is an error to try to visit a directory.
288 Files which are actually collections of other files, or @dfn{file
289 archives}, are visited in special modes which invoke a Dired-like
290 environment to allow operations on archive members. @xref{File
291 Archives}, for more about these features.
293 If you visit a file that the operating system won't let you modify,
294 or that is marked read-only, Emacs makes the buffer read-only too, so
295 that you won't go ahead and make changes that you'll have trouble
296 saving afterward. You can make the buffer writable with @kbd{C-x C-q}
297 (@code{toggle-read-only}). @xref{Misc Buffer}.
300 @findex find-file-read-only
301 If you want to visit a file as read-only in order to protect
302 yourself from entering changes accidentally, visit it with the command
303 @kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}.
306 @findex find-file-other-window
307 @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
308 except that the buffer containing the specified file is selected in another
309 window. The window that was selected before @kbd{C-x 4 f} continues to
310 show the same buffer it was already showing. If this command is used when
311 only one window is being displayed, that window is split in two, with one
312 window showing the same buffer as before, and the other one showing the
313 newly requested file. @xref{Windows}.
316 @findex find-file-other-frame
317 @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
318 new frame, or makes visible any existing frame showing the file you
319 seek. This feature is available only when you are using a window
320 system. @xref{Frames}.
322 Emacs recognizes from the contents of a file which end-of-line
323 convention it uses to separate lines---newline (used on GNU/Linux and
324 on Unix), carriage-return linefeed (used on Microsoft systems), or
325 just carriage-return (used on the Macintosh)---and automatically
326 converts the contents to the normal Emacs convention, which is that
327 the newline character separates lines. This is a part of the general
328 feature of coding system conversion (@pxref{Coding Systems}), and
329 makes it possible to edit files imported from different operating
330 systems with equal convenience. If you change the text and save the
331 file, Emacs performs the inverse conversion, changing newlines back
332 into carriage-return linefeed or just carriage-return if appropriate.
334 @findex find-file-literally
335 If you wish to edit a file as a sequence of @acronym{ASCII}
336 characters with no special encoding or conversion, use the @kbd{M-x
337 find-file-literally} command. This visits a file, like @kbd{C-x C-f},
338 but does not do format conversion (@pxref{Formatted Text}), character
339 code conversion (@pxref{Coding Systems}), or automatic uncompression
340 (@pxref{Compressed Files}), and does not add a final newline because
341 of @code{require-final-newline} (@pxref{Customize Save}). If you have
342 already visited the same file in the usual (non-literal) manner, this
343 command asks you whether to visit it literally instead.
345 @vindex find-file-hook
346 @vindex find-file-not-found-functions
347 Two special hook variables allow extensions to modify the operation of
348 visiting files. Visiting a file that does not exist runs the functions
349 in the list @code{find-file-not-found-functions}; this variable holds a list
350 of functions, and the functions are called one by one (with no
351 arguments) until one of them returns non-@code{nil}. This is not a
352 normal hook, and the name ends in @samp{-functions} rather than @samp{-hook}
353 to indicate that fact.
355 Successful visiting of any file, whether existing or not, calls the
356 functions in the list @code{find-file-hook}, with no arguments.
357 This variable is a normal hook. In the case of a nonexistent file, the
358 @code{find-file-not-found-functions} are run first. @xref{Hooks}.
360 There are several ways to specify automatically the major mode for
361 editing the file (@pxref{Choosing Modes}), and to specify local
362 variables defined for that file (@pxref{File Variables}).
365 @section Saving Files
367 @dfn{Saving} a buffer in Emacs means writing its contents back into the file
368 that was visited in the buffer.
371 * Save Commands:: Commands for saving files.
372 * Backup:: How Emacs saves the old version of your file.
373 * Customize Save:: Customizing the saving of files.
374 * Interlocking:: How Emacs protects against simultaneous editing
375 of one file by two users.
376 * Shadowing: File Shadowing. Copying files to "shadows" automatically.
377 * Time Stamps:: Emacs can update time stamps on saved files.
381 @subsection Commands for Saving Files
383 These are the commands that relate to saving and writing files.
387 Save the current buffer in its visited file on disk (@code{save-buffer}).
389 Save any or all buffers in their visited files (@code{save-some-buffers}).
391 Forget that the current buffer has been changed (@code{not-modified}).
392 With prefix argument (@kbd{C-u}), mark the current buffer as changed.
394 Save the current buffer with a specified file name (@code{write-file}).
395 @item M-x set-visited-file-name
396 Change the file name under which the current buffer will be saved.
401 When you wish to save the file and make your changes permanent, type
402 @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
403 displays a message like this:
406 Wrote /u/rms/gnu/gnu.tasks
410 If the selected buffer is not modified (no changes have been made in it
411 since the buffer was created or last saved), saving is not really done,
412 because it would have no effect. Instead, @kbd{C-x C-s} displays a message
413 like this in the echo area:
416 (No changes need to be saved)
419 With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer
420 to be backed up when the next save is done. @xref{Backup}.
423 @findex save-some-buffers
424 The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
425 or all modified buffers. It asks you what to do with each buffer. The
426 possible responses are analogous to those of @code{query-replace}:
430 Save this buffer and ask about the rest of the buffers.
432 Don't save this buffer, but ask about the rest of the buffers.
434 Save this buffer and all the rest with no more questions.
435 @c following generates acceptable underfull hbox
437 Terminate @code{save-some-buffers} without any more saving.
439 Save this buffer, then exit @code{save-some-buffers} without even asking
442 View the buffer that you are currently being asked about. When you exit
443 View mode, you get back to @code{save-some-buffers}, which asks the
446 Diff the buffer against its corresponding file, so you can see what
447 changes you would be saving. This calls the command
448 @code{diff-buffer-with-file} (@pxref{Comparing Files}).
450 Display a help message about these options.
453 @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
454 @code{save-some-buffers} and therefore asks the same questions.
458 If you have changed a buffer but do not wish to save the changes,
459 you should take some action to prevent it. Otherwise, each time you
460 use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer
461 by mistake. One thing you can do is type @kbd{M-~}
462 (@code{not-modified}), which clears out the indication that the buffer
463 is modified. If you do this, none of the save commands will believe
464 that the buffer needs to be saved. (@samp{~} is often used as a
465 mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.)
466 Alternatively, you can cancel all the changes made since the file was
467 visited or saved, by reading the text from the file again. This is
468 called @dfn{reverting}. @xref{Reverting}. (You could also undo all
469 the changes by repeating the undo command @kbd{C-x u} until you have
470 undone all the changes; but reverting is easier.)
472 @findex set-visited-file-name
473 @kbd{M-x set-visited-file-name} alters the name of the file that the
474 current buffer is visiting. It reads the new file name using the
475 minibuffer. Then it marks the buffer as visiting that file name, and
476 changes the buffer name correspondingly. @code{set-visited-file-name}
477 does not save the buffer in the newly visited file; it just alters the
478 records inside Emacs in case you do save later. It also marks the
479 buffer as ``modified'' so that @kbd{C-x C-s} in that buffer
484 If you wish to mark the buffer as visiting a different file and save
485 it right away, use @kbd{C-x C-w} (@code{write-file}). This is
486 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s},
487 except that @kbd{C-x C-w} asks for confirmation if the file exists.
488 @kbd{C-x C-s} used on a buffer that is not visiting a file has the
489 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
490 buffer as visiting that file, and saves it there. The default file
491 name in a buffer that is not visiting a file is made by combining the
492 buffer name with the buffer's default directory (@pxref{File Names}).
494 If the new file name implies a major mode, then @kbd{C-x C-w} switches
495 to that major mode, in most cases. The command
496 @code{set-visited-file-name} also does this. @xref{Choosing Modes}.
498 If Emacs is about to save a file and sees that the date of the latest
499 version on disk does not match what Emacs last read or wrote, Emacs
500 notifies you of this fact, because it probably indicates a problem caused
501 by simultaneous editing and requires your immediate attention.
502 @xref{Interlocking,, Simultaneous Editing}.
505 @subsection Backup Files
507 @vindex make-backup-files
508 @vindex vc-make-backup-files
510 On most operating systems, rewriting a file automatically destroys all
511 record of what the file used to contain. Thus, saving a file from Emacs
512 throws away the old contents of the file---or it would, except that
513 Emacs carefully copies the old contents to another file, called the
514 @dfn{backup} file, before actually saving.
516 Emacs makes a backup for a file only the first time the file is
517 saved from a buffer. No matter how many times you subsequently save
518 the file, its backup remains unchanged. However, if you kill the
519 buffer and then visit the file again, a new backup file will be made.
521 For most files, the variable @code{make-backup-files} determines
522 whether to make backup files. On most operating systems, its default
523 value is @code{t}, so that Emacs does write backup files.
525 For files managed by a version control system (@pxref{Version
526 Control}), the variable @code{vc-make-backup-files} determines whether
527 to make backup files. By default it is @code{nil}, since backup files
528 are redundant when you store all the previous versions in a version
531 @xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}.
534 @xref{General VC Options}.
537 At your option, Emacs can keep either a single backup for each file,
538 or make a series of numbered backup files for each file that you edit.
541 @vindex backup-enable-predicate
542 @vindex temporary-file-directory
543 @vindex small-temporary-file-directory
544 The default value of the @code{backup-enable-predicate} variable
545 prevents backup files being written for files in the directories used
546 for temporary files, specified by @code{temporary-file-directory} or
547 @code{small-temporary-file-directory}.
549 You can explicitly tell Emacs to make another backup file from a
550 buffer, even though that buffer has been saved before. If you save
551 the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
552 into a backup file if you save the buffer again. @kbd{C-u C-u C-x
553 C-s} saves the buffer, but first makes the previous file contents into
554 a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it
555 makes a backup from the previous contents, and arranges to make
556 another from the newly saved contents if you save again.
559 * Names: Backup Names. How backup files are named.
560 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
561 * Copying: Backup Copying. Backups can be made by copying or renaming.
565 @subsubsection Single or Numbered Backups
567 When Emacs makes a backup file, its name is normally constructed by
568 appending @samp{~} to the file name being edited; thus, the backup
569 file for @file{eval.c} would be @file{eval.c~}.
571 If access control stops Emacs from writing backup files under the
572 usual names, it writes the backup file as @file{~/.emacs.d/%backup%~}.
573 Only one such file can exist, so only the most recently made such
576 Emacs can also make @dfn{numbered backup files}. Numbered backup
577 file names contain @samp{.~}, the number, and another @samp{~} after
578 the original file name. Thus, the backup files of @file{eval.c} would
579 be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way
580 through names like @file{eval.c.~259~} and beyond.
582 @vindex version-control
583 The variable @code{version-control} determines whether to make
584 single backup files or multiple numbered backup files. Its possible
589 Make numbered backups for files that have numbered backups already.
590 Otherwise, make single backups. This is the default.
592 Make numbered backups.
594 Never make numbered backups; always make single backups.
598 The usual way to set this variable is globally, through your
599 @file{.emacs} file or the customization buffer. However, you can set
600 @code{version-control} locally in an individual buffer to control the
601 making of backups for that buffer's file (@pxref{Locals}). You can
602 have Emacs set @code{version-control} locally whenever you visit a
603 given file (@pxref{File Variables}). Some modes, such as Rmail mode,
606 @cindex @env{VERSION_CONTROL} environment variable
607 If you set the environment variable @env{VERSION_CONTROL}, to tell
608 various GNU utilities what to do with backup files, Emacs also obeys the
609 environment variable by setting the Lisp variable @code{version-control}
610 accordingly at startup. If the environment variable's value is @samp{t}
611 or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
612 value is @samp{nil} or @samp{existing}, then @code{version-control}
613 becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
614 @code{version-control} becomes @code{never}.
616 @vindex backup-directory-alist
617 You can customize the variable @code{backup-directory-alist} to
618 specify that files matching certain patterns should be backed up in
619 specific directories. This variable applies to both single and
620 numbered backups. A typical use is to add an element @code{("."
621 . @var{dir})} to make all backups in the directory with absolute name
622 @var{dir}; Emacs modifies the backup file names to avoid clashes
623 between files with the same names originating in different
624 directories. Alternatively, adding, @code{("." . ".~")} would make
625 backups in the invisible subdirectory @file{.~} of the original file's
626 directory. Emacs creates the directory, if necessary, to make the
629 @vindex make-backup-file-name-function
630 If you define the variable @code{make-backup-file-name-function} to
631 a suitable Lisp function, that overrides the usual way Emacs
632 constructs backup file names.
634 @node Backup Deletion
635 @subsubsection Automatic Deletion of Backups
637 To prevent excessive consumption of disk space, Emacs can delete numbered
638 backup versions automatically. Generally Emacs keeps the first few backups
639 and the latest few backups, deleting any in between. This happens every
640 time a new backup is made.
642 @vindex kept-old-versions
643 @vindex kept-new-versions
644 The two variables @code{kept-old-versions} and
645 @code{kept-new-versions} control this deletion. Their values are,
646 respectively, the number of oldest (lowest-numbered) backups to keep
647 and the number of newest (highest-numbered) ones to keep, each time a
648 new backup is made. The backups in the middle (excluding those oldest
649 and newest) are the excess middle versions---those backups are
650 deleted. These variables' values are used when it is time to delete
651 excess versions, just after a new backup version is made; the newly
652 made backup is included in the count in @code{kept-new-versions}. By
653 default, both variables are 2.
655 @vindex delete-old-versions
656 If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
657 backup files silently. If it is @code{nil}, the default, Emacs asks
658 you whether it should delete the excess backup versions. If it has
659 any other value, then Emacs never automatically deletes backups.
661 Dired's @kbd{.} (Period) command can also be used to delete old versions.
662 @xref{Dired Deletion}.
665 @subsubsection Copying vs.@: Renaming
667 Backup files can be made by copying the old file or by renaming it.
668 This makes a difference when the old file has multiple names (hard
669 links). If the old file is renamed into the backup file, then the
670 alternate names become names for the backup file. If the old file is
671 copied instead, then the alternate names remain names for the file
672 that you are editing, and the contents accessed by those names will be
675 The method of making a backup file may also affect the file's owner
676 and group. If copying is used, these do not change. If renaming is used,
677 you become the file's owner, and the file's group becomes the default
678 (different operating systems have different defaults for the group).
680 Having the owner change is usually a good idea, because then the owner
681 always shows who last edited the file. Also, the owners of the backups
682 show who produced those versions. Occasionally there is a file whose
683 owner should not change; it is a good idea for such files to contain
684 local variable lists to set @code{backup-by-copying-when-mismatch}
685 locally (@pxref{File Variables}).
687 @vindex backup-by-copying
688 @vindex backup-by-copying-when-linked
689 @vindex backup-by-copying-when-mismatch
690 @vindex backup-by-copying-when-privileged-mismatch
691 @cindex file ownership, and backup
692 @cindex backup, and user-id
693 The choice of renaming or copying is controlled by four variables.
694 Renaming is the default choice. If the variable
695 @code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise,
696 if the variable @code{backup-by-copying-when-linked} is non-@code{nil},
697 then copying is used for files that have multiple names, but renaming
698 may still be used when the file being edited has only one name. If the
699 variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then
700 copying is used if renaming would cause the file's owner or group to
701 change. @code{backup-by-copying-when-mismatch} is @code{t} by default
702 if you start Emacs as the superuser. The fourth variable,
703 @code{backup-by-copying-when-privileged-mismatch}, gives the highest
704 numeric user-id for which @code{backup-by-copying-when-mismatch} will be
705 forced on. This is useful when low-numbered user-ids are assigned to
706 special system users, such as @code{root}, @code{bin}, @code{daemon},
707 etc., which must maintain ownership of files.
709 When a file is managed with a version control system (@pxref{Version
710 Control}), Emacs does not normally make backups in the usual way for
711 that file. But check-in and check-out are similar in some ways to
712 making backups. One unfortunate similarity is that these operations
713 typically break hard links, disconnecting the file name you visited from
714 any alternate names for the same file. This has nothing to do with
715 Emacs---the version control system does it.
718 @subsection Customizing Saving of Files
720 @vindex require-final-newline
721 If the value of the variable @code{require-final-newline} is
722 @code{t}, saving or writing a file silently puts a newline at the end
723 if there isn't already one there. If the value is @code{visit}, Emacs
724 adds a newline at the end of any file that doesn't have one, just
725 after it visits the file. (This marks the buffer as modified, and you
726 can undo it.) If the value is @code{visit-save}, that means to add
727 newlines both on visiting and on saving. If the value is @code{nil},
728 Emacs leaves the end of the file unchanged; if it's neither @code{nil}
729 nor @code{t}, Emacs asks you whether to add a newline. The default is
732 @vindex mode-require-final-newline
733 Many major modes are designed for specific kinds of files that are
734 always supposed to end in newlines. These major modes set the
735 variable @code{require-final-newline} according to
736 @code{mode-require-final-newline}. By setting the latter variable,
737 you can control how these modes handle final newlines.
739 @vindex write-region-inhibit-fsync
740 When Emacs saves a file, it invokes the @code{fsync} system call to
741 force the data immediately out to disk. This is important for safety
742 if the system crashes or in case of power outage. However, it can be
743 disruptive on laptops using power saving, because it requires the disk
744 to spin up each time you save a file. Setting
745 @code{write-region-inhibit-fsync} to a non-@code{nil} value disables
746 this synchronization. Be careful---this means increased risk of data
750 @subsection Protection against Simultaneous Editing
753 @cindex simultaneous editing
754 Simultaneous editing occurs when two users visit the same file, both
755 make changes, and then both save them. If nobody were informed that
756 this was happening, whichever user saved first would later find that his
759 On some systems, Emacs notices immediately when the second user starts
760 to change the file, and issues an immediate warning. On all systems,
761 Emacs checks when you save the file, and warns if you are about to
762 overwrite another user's changes. You can prevent loss of the other
763 user's work by taking the proper corrective action instead of saving the
766 @findex ask-user-about-lock
767 @cindex locking files
768 When you make the first modification in an Emacs buffer that is
769 visiting a file, Emacs records that the file is @dfn{locked} by you.
770 (It does this by creating a specially-named symbolic link in the same
771 directory.) Emacs removes the lock when you save the changes. The
772 idea is that the file is locked whenever an Emacs buffer visiting it
776 If you begin to modify the buffer while the visited file is locked by
777 someone else, this constitutes a @dfn{collision}. When Emacs detects a
778 collision, it asks you what to do, by calling the Lisp function
779 @code{ask-user-about-lock}. You can redefine this function for the sake
780 of customization. The standard definition of this function asks you a
781 question and accepts three possible answers:
785 Steal the lock. Whoever was already changing the file loses the lock,
786 and you gain the lock.
788 Proceed. Go ahead and edit the file despite its being locked by someone else.
790 Quit. This causes an error (@code{file-locked}), and the buffer
791 contents remain unchanged---the modification you were trying to make
792 does not actually take place.
795 Note that locking works on the basis of a file name; if a file has
796 multiple names, Emacs does not realize that the two names are the same file
797 and cannot prevent two users from editing it simultaneously under different
798 names. However, basing locking on names means that Emacs can interlock the
799 editing of new files that will not really exist until they are saved.
801 Some systems are not configured to allow Emacs to make locks, and
802 there are cases where lock files cannot be written. In these cases,
803 Emacs cannot detect trouble in advance, but it still can detect the
804 collision when you try to save a file and overwrite someone else's
805 changes. Every time Emacs saves a buffer, it first checks the
806 last-modification date of the existing file on disk to verify that it
807 has not changed since the file was last visited or saved. If the date
808 does not match, it implies that changes were made in the file in some
809 other way, and these changes are about to be lost if Emacs actually
810 does save. To prevent this, Emacs displays a warning message and asks
811 for confirmation before saving. Occasionally you will know why the
812 file was changed and know that it does not matter; then you can answer
813 @kbd{yes} and proceed. Otherwise, you should cancel the save with
814 @kbd{C-g} and investigate the situation.
816 If Emacs or the operating system crashes, this may leave behind lock
817 files which are stale, so you may occasionally get warnings about
818 spurious collisions. When you determine that the collision is spurious,
819 just use @kbd{p} to tell Emacs to go ahead anyway.
821 The first thing you should do when notified that simultaneous editing
822 has already taken place is to list the directory with @kbd{C-u C-x C-d}
823 (@pxref{Directories}). This shows the file's current author. You
824 should attempt to contact him to warn him not to continue editing.
825 Often the next step is to save the contents of your Emacs buffer under a
826 different name, and use @code{diff} to compare the two files.@refill
829 @subsection Shadowing Files
832 @findex shadow-initialize
835 @item M-x shadow-initialize
836 Set up file shadowing.
837 @item M-x shadow-define-literal-group
838 Declare a single file to be shared between sites.
839 @item M-x shadow-define-regexp-group
840 Make all files that match each of a group of files be shared between hosts.
841 @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
842 Define a shadow file cluster @var{name}.
843 @item M-x shadow-copy-files
844 Copy all pending shadow files.
845 @item M-x shadow-cancel
846 Cancel the instruction to shadow some files.
849 You can arrange to keep identical @dfn{shadow} copies of certain files
850 in more than one place---possibly on different machines. To do this,
851 first you must set up a @dfn{shadow file group}, which is a set of
852 identically-named files shared between a list of sites. The file
853 group is permanent and applies to further Emacs sessions as well as
854 the current one. Once the group is set up, every time you exit Emacs,
855 it will copy the file you edited to the other files in its group. You
856 can also do the copying without exiting Emacs, by typing @kbd{M-x
859 To set up a shadow file group, use @kbd{M-x
860 shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}.
861 See their documentation strings for further information.
863 Before copying a file to its shadows, Emacs asks for confirmation.
864 You can answer ``no'' to bypass copying of this file, this time. If
865 you want to cancel the shadowing permanently for a certain file, use
866 @kbd{M-x shadow-cancel} to eliminate or change the shadow file group.
868 A @dfn{shadow cluster} is a group of hosts that share directories, so
869 that copying to or from one of them is sufficient to update the file
870 on all of them. Each shadow cluster has a name, and specifies the
871 network address of a primary host (the one we copy files to), and a
872 regular expression that matches the host names of all the other hosts
873 in the cluster. You can define a shadow cluster with @kbd{M-x
874 shadow-define-cluster}.
877 @subsection Updating Time Stamps Automatically
879 @cindex modification dates
880 @cindex locale, date format
882 You can arrange to put a time stamp in a file, so that it will be updated
883 automatically each time you edit and save the file. The time stamp
884 has to be in the first eight lines of the file, and you should
899 Then add the hook function @code{time-stamp} to the hook
900 @code{before-save-hook}; that hook function will automatically update
901 the time stamp, inserting the current date and time when you save the
902 file. You can also use the command @kbd{M-x time-stamp} to update the
903 time stamp manually. For other customizations, see the Custom group
904 @code{time-stamp}. Note that non-numeric fields in the time stamp are
905 formatted according to your locale setting (@pxref{Environment}).
908 @section Reverting a Buffer
909 @findex revert-buffer
910 @cindex drastic changes
911 @cindex reread a file
913 If you have made extensive changes to a file and then change your mind
914 about them, you can get rid of them by reading in the previous version
915 of the file. To do this, use @kbd{M-x revert-buffer}, which operates on
916 the current buffer. Since reverting a buffer unintentionally could lose
917 a lot of work, you must confirm this command with @kbd{yes}.
919 @code{revert-buffer} tries to position point in such a way that, if
920 the file was edited only slightly, you will be at approximately the
921 same piece of text after reverting as before. However, if you have made
922 drastic changes, point may wind up in a totally different piece of text.
924 Reverting marks the buffer as ``not modified''.
926 Some kinds of buffers that are not associated with files, such as
927 Dired buffers, can also be reverted. For them, reverting means
928 recalculating their contents. Buffers created explicitly with
929 @kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error
932 @vindex revert-without-query
933 When you edit a file that changes automatically and frequently---for
934 example, a log of output from a process that continues to run---it may
935 be useful for Emacs to revert the file without querying you. To
936 request this behavior, set the variable @code{revert-without-query} to
937 a list of regular expressions. When a file name matches one of these
938 regular expressions, @code{find-file} and @code{revert-buffer} will
939 revert it automatically if it has changed---provided the buffer itself
940 is not modified. (If you have edited the text, it would be wrong to
941 discard your changes.)
943 @cindex Global Auto-Revert mode
944 @cindex mode, Global Auto-Revert
945 @cindex Auto-Revert mode
946 @cindex mode, Auto-Revert
947 @findex global-auto-revert-mode
948 @findex auto-revert-mode
949 @findex auto-revert-tail-mode
950 @vindex auto-revert-interval
952 In addition, you can tell Emacs to periodically revert a buffer by
953 typing @kbd{M-x auto-revert-mode}. This turns on Auto-Revert mode, a
954 minor mode that makes Emacs automatically revert the current buffer
955 every five seconds. You can change this interval through the variable
956 @code{auto-revert-interval}. Typing @kbd{M-x global-auto-revert-mode}
957 enables Global Auto-Revert mode, which does the same for all file
958 buffers. Auto-Revert mode and Global Auto-Revert modes do not check
959 or revert remote files, because that is usually too slow.
961 One use of Auto-Revert mode is to ``tail'' a file such as a system
962 log, so that changes made to that file by other programs are
963 continuously displayed. To do this, just move the point to the end of
964 the buffer, and it will stay there as the file contents change.
965 However, if you are sure that the file will only change by growing at
966 the end, use Auto-Revert Tail mode instead
967 (@code{auto-revert-tail-mode}). It is more efficient for this.
968 Auto-Revert Tail mode works also for remote files.
970 @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that
971 visit files under version control.
974 @include arevert-xtra.texi
978 @section Auto-Saving: Protection Against Disasters
979 @cindex Auto Save mode
980 @cindex mode, Auto Save
983 From time to time, Emacs automatically saves each visited file in a
984 separate file, without altering the file you actually use. This is
985 called @dfn{auto-saving}. It prevents you from losing more than a
986 limited amount of work if the system crashes.
988 When Emacs determines that it is time for auto-saving, it considers
989 each buffer, and each is auto-saved if auto-saving is enabled for it
990 and it has been changed since the last time it was auto-saved. The
991 message @samp{Auto-saving...} is displayed in the echo area during
992 auto-saving, if any files are actually auto-saved. Errors occurring
993 during auto-saving are caught so that they do not interfere with the
994 execution of commands you have been typing.
997 * Files: Auto Save Files. The file where auto-saved changes are
998 actually made until you save the file.
999 * Control: Auto Save Control. Controlling when and how often to auto-save.
1000 * Recover:: Recovering text from auto-save files.
1003 @node Auto Save Files
1004 @subsection Auto-Save Files
1006 Auto-saving does not normally save in the files that you visited,
1007 because it can be very undesirable to save a change that you did not
1008 want to make permanent. Instead, auto-saving is done in a different
1009 file called the @dfn{auto-save file}, and the visited file is changed
1010 only when you request saving explicitly (such as with @kbd{C-x C-s}).
1012 Normally, the auto-save file name is made by appending @samp{#} to the
1013 front and rear of the visited file name. Thus, a buffer visiting file
1014 @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that
1015 are not visiting files are auto-saved only if you request it explicitly;
1016 when they are auto-saved, the auto-save file name is made by appending
1017 @samp{#} to the front and rear of buffer name, then
1018 adding digits and letters at the end for uniqueness. For
1019 example, the @samp{*mail*} buffer in which you compose messages to be
1020 sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file
1021 names are made this way unless you reprogram parts of Emacs to do
1022 something different (the functions @code{make-auto-save-file-name} and
1023 @code{auto-save-file-name-p}). The file name to be used for auto-saving
1024 in a buffer is calculated when auto-saving is turned on in that buffer.
1026 @cindex auto-save for remote files
1027 @vindex auto-save-file-name-transforms
1028 The variable @code{auto-save-file-name-transforms} allows a degree
1029 of control over the auto-save file name. It lets you specify a series
1030 of regular expressions and replacements to transform the auto save
1031 file name. The default value puts the auto-save files for remote
1032 files (@pxref{Remote Files}) into the temporary file directory on the
1035 When you delete a substantial part of the text in a large buffer, auto
1036 save turns off temporarily in that buffer. This is because if you
1037 deleted the text unintentionally, you might find the auto-save file more
1038 useful if it contains the deleted text. To reenable auto-saving after
1039 this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
1042 @vindex auto-save-visited-file-name
1043 If you want auto-saving to be done in the visited file rather than
1044 in a separate auto-save file, set the variable
1045 @code{auto-save-visited-file-name} to a non-@code{nil} value. In this
1046 mode, there is no real difference between auto-saving and explicit
1049 @vindex delete-auto-save-files
1050 A buffer's auto-save file is deleted when you save the buffer in its
1051 visited file. (You can inhibit this by setting the variable
1052 @code{delete-auto-save-files} to @code{nil}.) Changing the visited
1053 file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames
1054 any auto-save file to go with the new visited name.
1056 @node Auto Save Control
1057 @subsection Controlling Auto-Saving
1059 @vindex auto-save-default
1060 @findex auto-save-mode
1061 Each time you visit a file, auto-saving is turned on for that file's
1062 buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
1063 in batch mode; @pxref{Entering Emacs}). The default for this variable is
1064 @code{t}, so auto-saving is the usual practice for file-visiting buffers.
1065 Auto-saving can be turned on or off for any existing buffer with the
1066 command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
1067 auto-save-mode} turns auto-saving on with a positive argument, off with a
1068 zero or negative argument; with no argument, it toggles.
1070 @vindex auto-save-interval
1071 Emacs does auto-saving periodically based on counting how many characters
1072 you have typed since the last time auto-saving was done. The variable
1073 @code{auto-save-interval} specifies how many characters there are between
1074 auto-saves. By default, it is 300. Emacs doesn't accept values that are
1075 too small: if you customize @code{auto-save-interval} to a value less
1076 than 20, Emacs will behave as if the value is 20.
1078 @vindex auto-save-timeout
1079 Auto-saving also takes place when you stop typing for a while. The
1080 variable @code{auto-save-timeout} says how many seconds Emacs should
1081 wait before it does an auto save (and perhaps also a garbage
1082 collection). (The actual time period is longer if the current buffer is
1083 long; this is a heuristic which aims to keep out of your way when you
1084 are editing long buffers, in which auto-save takes an appreciable amount
1085 of time.) Auto-saving during idle periods accomplishes two things:
1086 first, it makes sure all your work is saved if you go away from the
1087 terminal for a while; second, it may avoid some auto-saving while you
1088 are actually typing.
1090 Emacs also does auto-saving whenever it gets a fatal error. This
1091 includes killing the Emacs job with a shell command such as @samp{kill
1092 %emacs}, or disconnecting a phone line or network connection.
1094 @findex do-auto-save
1095 You can request an auto-save explicitly with the command @kbd{M-x
1099 @subsection Recovering Data from Auto-Saves
1101 @findex recover-file
1102 You can use the contents of an auto-save file to recover from a loss
1103 of data with the command @kbd{M-x recover-file @key{RET} @var{file}
1104 @key{RET}}. This visits @var{file} and then (after your confirmation)
1105 restores the contents from its auto-save file @file{#@var{file}#}.
1106 You can then save with @kbd{C-x C-s} to put the recovered text into
1107 @var{file} itself. For example, to recover file @file{foo.c} from its
1108 auto-save file @file{#foo.c#}, do:@refill
1111 M-x recover-file @key{RET} foo.c @key{RET}
1116 Before asking for confirmation, @kbd{M-x recover-file} displays a
1117 directory listing describing the specified file and the auto-save file,
1118 so you can compare their sizes and dates. If the auto-save file
1119 is older, @kbd{M-x recover-file} does not offer to read it.
1121 @findex recover-session
1122 If Emacs or the computer crashes, you can recover all the files you
1123 were editing from their auto save files with the command @kbd{M-x
1124 recover-session}. This first shows you a list of recorded interrupted
1125 sessions. Move point to the one you choose, and type @kbd{C-c C-c}.
1127 Then @code{recover-session} asks about each of the files that were
1128 being edited during that session, asking whether to recover that file.
1129 If you answer @kbd{y}, it calls @code{recover-file}, which works in its
1130 normal fashion. It shows the dates of the original file and its
1131 auto-save file, and asks once again whether to recover that file.
1133 When @code{recover-session} is done, the files you've chosen to
1134 recover are present in Emacs buffers. You should then save them. Only
1135 this---saving them---updates the files themselves.
1137 @vindex auto-save-list-file-prefix
1138 Emacs records information about interrupted sessions for later
1139 recovery in files named
1140 @file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. The
1141 directory used, @file{~/.emacs.d/auto-save-list/}, is determined by
1142 the variable @code{auto-save-list-file-prefix}. You can record
1143 sessions in a different place by customizing that variable. If you
1144 set @code{auto-save-list-file-prefix} to @code{nil} in your
1145 @file{.emacs} file, sessions are not recorded for recovery.
1148 @section File Name Aliases
1149 @cindex symbolic links (visiting)
1150 @cindex hard links (visiting)
1152 Symbolic links and hard links both make it possible for several file
1153 names to refer to the same file. Hard links are alternate names that
1154 refer directly to the file; all the names are equally valid, and no one
1155 of them is preferred. By contrast, a symbolic link is a kind of defined
1156 alias: when @file{foo} is a symbolic link to @file{bar}, you can use
1157 either name to refer to the file, but @file{bar} is the real name, while
1158 @file{foo} is just an alias. More complex cases occur when symbolic
1159 links point to directories.
1161 @vindex find-file-existing-other-name
1162 @vindex find-file-suppress-same-file-warnings
1163 Normally, if you visit a file which Emacs is already visiting under
1164 a different name, Emacs displays a message in the echo area and uses
1165 the existing buffer visiting that file. This can happen on systems
1166 that support hard or symbolic links, or if you use a long file name on
1167 a system that truncates long file names, or on a case-insensitive file
1168 system. You can suppress the message by setting the variable
1169 @code{find-file-suppress-same-file-warnings} to a non-@code{nil}
1170 value. You can disable this feature entirely by setting the variable
1171 @code{find-file-existing-other-name} to @code{nil}: then if you visit
1172 the same file under two different names, you get a separate buffer for
1175 @vindex find-file-visit-truename
1176 @cindex truenames of files
1177 @cindex file truenames
1178 If the variable @code{find-file-visit-truename} is non-@code{nil},
1179 then the file name recorded for a buffer is the file's @dfn{truename}
1180 (made by replacing all symbolic links with their target names), rather
1181 than the name you specify. Setting @code{find-file-visit-truename} also
1182 implies the effect of @code{find-file-existing-other-name}.
1184 @cindex directory name abbreviation
1185 @vindex directory-abbrev-alist
1186 Sometimes, a directory is ordinarily accessed through a symbolic
1187 link, and you may want Emacs to preferentially show its ``linked''
1188 name. To do this, customize @code{directory-abbrev-alist}. Each
1189 element in this list should have the form @code{(@var{from}
1190 . @var{to})}, which means to replace @var{from} with @var{to} whenever
1191 @var{from} appears in a directory name. The @var{from} string is a
1192 regular expression (@pxref{Regexps}). It is matched against directory
1193 names anchored at the first character, and should start with @samp{\`}
1194 (to support directory names with embedded newlines, which would defeat
1195 @samp{^}). The @var{to} string should be an ordinary absolute
1196 directory name pointing to the same directory. Do not use @samp{~} to
1197 stand for a home directory in the @var{to} string; Emacs performs
1198 these substitutions separately. Here's an example, from a system on
1199 which @file{/home/fsf} is normally accessed through a symbolic link
1203 (("\\`/home/fsf" . "/fsf"))
1207 @section File Directories
1209 @cindex file directory
1210 @cindex directory listing
1211 The file system groups files into @dfn{directories}. A @dfn{directory
1212 listing} is a list of all the files in a directory. Emacs provides
1213 commands to create and delete directories, and to make directory
1214 listings in brief format (file names only) and verbose format (sizes,
1215 dates, and authors included). Emacs also includes a directory browser
1216 feature called Dired; see @ref{Dired}.
1219 @item C-x C-d @var{dir-or-pattern} @key{RET}
1220 Display a brief directory listing (@code{list-directory}).
1221 @item C-u C-x C-d @var{dir-or-pattern} @key{RET}
1222 Display a verbose directory listing.
1223 @item M-x make-directory @key{RET} @var{dirname} @key{RET}
1224 Create a new directory named @var{dirname}.
1225 @item M-x delete-directory @key{RET} @var{dirname} @key{RET}
1226 Delete the directory named @var{dirname}. If it isn't empty,
1227 you will be asked whether you want to delete it recursively.
1230 @findex list-directory
1232 The command to display a directory listing is @kbd{C-x C-d}
1233 (@code{list-directory}). It reads using the minibuffer a file name
1234 which is either a directory to be listed or a wildcard-containing
1235 pattern for the files to be listed. For example,
1238 C-x C-d /u2/emacs/etc @key{RET}
1242 lists all the files in directory @file{/u2/emacs/etc}. Here is an
1243 example of specifying a file name pattern:
1246 C-x C-d /u2/emacs/src/*.c @key{RET}
1249 Normally, @kbd{C-x C-d} displays a brief directory listing containing
1250 just file names. A numeric argument (regardless of value) tells it to
1251 make a verbose listing including sizes, dates, and owners (like
1254 @vindex list-directory-brief-switches
1255 @vindex list-directory-verbose-switches
1256 The text of a directory listing is mostly obtained by running
1257 @code{ls} in an inferior process. Two Emacs variables control the
1258 switches passed to @code{ls}: @code{list-directory-brief-switches} is
1259 a string giving the switches to use in brief listings (@code{"-CF"} by
1260 default), and @code{list-directory-verbose-switches} is a string
1261 giving the switches to use in a verbose listing (@code{"-l"} by
1264 @vindex directory-free-space-program
1265 @vindex directory-free-space-args
1266 In verbose directory listings, Emacs adds information about the
1267 amount of free space on the disk that contains the directory. To do
1268 this, it runs the program specified by
1269 @code{directory-free-space-program} with arguments
1270 @code{directory-free-space-args}.
1272 The command @kbd{M-x delete-directory} prompts for a directory name
1273 using the minibuffer, and deletes the directory if it is empty. If
1274 the directory is not empty, you will be asked whether you want to
1275 delete it recursively. On systems that have a ``Trash'' or ``Recycle
1276 Bin'' feature, you can make this command move the specified directory
1277 to the Trash or Recycle Bin, instead of deleting it outright, by
1278 changing the variable @code{delete-by-moving-to-trash} to @code{t}.
1279 @xref{Misc File Ops}, for more information about using the Trash.
1281 @node Comparing Files
1282 @section Comparing Files
1283 @cindex comparing files
1286 @vindex diff-switches
1287 The command @kbd{M-x diff} prompts for two file names, using the
1288 minibuffer, and displays the differences between the two files in a
1289 buffer named @samp{*diff*}. This works by running the @command{diff}
1290 program, using options taken from the variable @code{diff-switches}.
1291 The value of @code{diff-switches} should be a string; the default is
1292 @code{"-c"} to specify a context diff. @xref{Top,, Diff, diff,
1293 Comparing and Merging Files}, for more information about
1294 @command{diff} output formats.
1296 The output of the @code{diff} command is shown using a major mode
1297 called Diff mode. @xref{Diff Mode}.
1300 The command @kbd{M-x diff-backup} compares a specified file with its
1301 most recent backup. If you specify the name of a backup file,
1302 @code{diff-backup} compares it with the source file that it is a
1303 backup of. In all other respects, this behaves like @kbd{M-x diff}.
1305 @findex diff-buffer-with-file
1306 The command @kbd{M-x diff-buffer-with-file} compares a specified
1307 buffer with its corresponding file. This shows you what changes you
1308 would make to the file if you save the buffer.
1310 @findex compare-windows
1311 The command @kbd{M-x compare-windows} compares the text in the
1312 current window with that in the next window. (For more information
1313 about windows in Emacs, @ref{Windows}.) Comparison starts at point in
1314 each window, after pushing each initial point value on the mark ring
1315 in its respective buffer. Then it moves point forward in each window,
1316 one character at a time, until it reaches characters that don't match.
1317 Then the command exits.
1319 If point in the two windows is followed by non-matching text when
1320 the command starts, @kbd{M-x compare-windows} tries heuristically to
1321 advance up to matching text in the two windows, and then exits. So if
1322 you use @kbd{M-x compare-windows} repeatedly, each time it either
1323 skips one matching range or finds the start of another.
1325 @vindex compare-ignore-case
1326 @vindex compare-ignore-whitespace
1327 With a numeric argument, @code{compare-windows} ignores changes in
1328 whitespace. If the variable @code{compare-ignore-case} is
1329 non-@code{nil}, the comparison ignores differences in case as well.
1330 If the variable @code{compare-ignore-whitespace} is non-@code{nil},
1331 @code{compare-windows} normally ignores changes in whitespace, and a
1332 prefix argument turns that off.
1336 @cindex failed merges
1337 @cindex merges, failed
1338 @cindex comparing 3 files (@code{diff3})
1339 You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor
1340 mode for editing output from the @command{diff3} program. This is
1341 typically the result of a failed merge from a version control system
1342 ``update'' outside VC, due to conflicting changes to a file. Smerge
1343 mode provides commands to resolve conflicts by selecting specific
1347 @xref{Emerge,,, emacs-xtra, Specialized Emacs Features},
1352 for the Emerge facility, which provides a powerful interface for
1359 @cindex patches, editing
1361 Diff mode is a major mode used for the output of @kbd{M-x diff} and
1362 other similar commands, as well as the output of the @command{diff}
1363 program. This kind of output is called a @dfn{patch}, because it can
1364 be passed to the @command{patch} command to automatically apply the
1365 specified changes. To select Diff mode manually, type @kbd{M-x
1369 The changes specified in a patch are grouped into @dfn{hunks}, which
1370 are contiguous chunks of text that contain one or more changed lines.
1371 Hunks can also include unchanged lines to provide context for the
1372 changes. Each hunk is preceded by a @dfn{hunk header}, which
1373 specifies the old and new line numbers at which the hunk occurs. Diff
1374 mode highlights each hunk header, to distinguish it from the actual
1375 contents of the hunk.
1377 @vindex diff-update-on-the-fly
1378 You can edit a Diff mode buffer like any other buffer. (If it is
1379 read-only, you need to make it writable first. @xref{Misc Buffer}.)
1380 Whenever you change a hunk, Diff mode attempts to automatically
1381 correct the line numbers in the hunk headers, to ensure that the diff
1382 remains ``correct''. To disable automatic line number correction,
1383 change the variable @code{diff-update-on-the-fly} to @code{nil}.
1385 Diff mode treats each hunk as an ``error message,'' similar to
1386 Compilation mode. Thus, you can use commands such as @kbd{C-x '} to
1387 visit the corresponding source locations. @xref{Compilation Mode}.
1389 In addition, Diff mode provides the following commands to navigate,
1390 manipulate and apply parts of patches:
1394 @findex diff-hunk-next
1395 Move to the next hunk-start (@code{diff-hunk-next}).
1398 @findex diff-hunk-prev
1399 Move to the previous hunk-start (@code{diff-hunk-prev}).
1402 @findex diff-file-next
1403 Move to the next file-start, in a multi-file patch
1404 (@code{diff-file-next}).
1407 @findex diff-file-prev
1408 Move to the previous file-start, in a multi-file patch
1409 (@code{diff-file-prev}).
1412 @findex diff-hunk-kill
1413 Kill the hunk at point (@code{diff-hunk-kill}).
1416 @findex diff-file-kill
1417 In a multi-file patch, kill the current file part.
1418 (@code{diff-file-kill}).
1421 @findex diff-apply-hunk
1422 Apply this hunk to its target file (@code{diff-apply-hunk}). With a
1423 prefix argument of @kbd{C-u}, revert this hunk.
1426 @findex diff-refine-hunk
1427 Highlight the changes of the hunk at point with a finer granularity
1428 (@code{diff-refine-hunk}). This allows you to see exactly which parts
1429 of each changed line were actually changed.
1432 @findex diff-goto-source
1433 Go to the source file and line corresponding to this hunk
1434 (@code{diff-goto-source}).
1437 @findex diff-ediff-patch
1438 Start an Ediff session with the patch (@code{diff-ediff-patch}).
1439 @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
1442 @findex diff-restrict-view
1443 Restrict the view to the current hunk (@code{diff-restrict-view}).
1444 @xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the
1445 view to the current file of a multiple-file patch. To widen again,
1446 use @kbd{C-x n w} (@code{widen}).
1449 @findex diff-reverse-direction
1450 Reverse the direction of comparison for the entire buffer
1451 (@code{diff-reverse-direction}).
1454 @findex diff-split-hunk
1455 Split the hunk at point (@code{diff-split-hunk}). This is for
1456 manually editing patches, and only works with the @dfn{unified diff
1457 format} produced by the @option{-u} or @option{--unified} options to
1458 the @command{diff} program. If you need to split a hunk in the
1459 @dfn{context diff format} produced by the @option{-c} or
1460 @option{--context} options to @command{diff}, first convert the buffer
1461 to the unified diff format with @kbd{C-c C-u}.
1464 @findex diff-unified->context
1465 Convert the entire buffer to the @dfn{context diff format}
1466 (@code{diff-unified->context}). With a prefix argument, convert only
1467 the text within the region.
1470 @findex diff-context->unified
1471 Convert the entire buffer to unified diff format
1472 (@code{diff-context->unified}). With a prefix argument, convert
1473 unified format to context format. When the mark is active, convert
1474 only the text within the region.
1477 @findex diff-refine-hunk
1478 Refine the current hunk so that it disregards changes in whitespace
1479 (@code{diff-refine-hunk}).
1482 @findex diff-add-change-log-entries-other-window
1483 @findex add-change-log-entry-other-window@r{, in Diff mode}
1484 Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change
1485 Log}), for each one of the hunks
1486 (@code{diff-add-change-log-entries-other-window}). This creates a
1487 skeleton of the log of changes that you can later fill with the actual
1488 descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode
1489 operates on behalf of the current hunk's file, but gets the function
1490 name from the patch itself. This is useful for making log entries for
1491 functions that are deleted by the patch.
1493 @item M-x diff-show-trailing-whitespaces RET
1494 @findex diff-show-trailing-whitespaces
1495 Highlight trailing whitespace characters, except for those used by the
1496 patch syntax (@pxref{Useless Whitespace}).
1501 @section Miscellaneous File Operations
1503 Emacs has commands for performing many other operations on files.
1504 All operate on one file; they do not accept wildcard file names.
1510 @kbd{M-x view-file} allows you to scan or read a file by sequential
1511 screenfuls. It reads a file name argument using the minibuffer. After
1512 reading the file into an Emacs buffer, @code{view-file} displays the
1513 beginning. You can then type @key{SPC} to scroll forward one windowful,
1514 or @key{DEL} to scroll backward. Various other commands are provided
1515 for moving around in the file, but none for changing it; type @kbd{?}
1516 while viewing for a list of them. They are mostly the same as normal
1517 Emacs cursor motion commands. To exit from viewing, type @kbd{q}.
1518 The commands for viewing are defined by a special minor mode called View
1521 A related command, @kbd{M-x view-buffer}, views a buffer already present
1522 in Emacs. @xref{Misc Buffer}.
1526 @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
1527 contents of the specified file into the current buffer at point,
1528 leaving point unchanged before the contents. The position after the
1529 inserted contents is added to the mark ring, without activating the
1530 mark (@pxref{Mark Ring}).
1532 @findex insert-file-literally
1533 @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
1534 except the file is inserted ``literally'': it is treated as a sequence
1535 of @acronym{ASCII} characters with no special encoding or conversion,
1536 similar to the @kbd{M-x find-file-literally} command
1539 @findex write-region
1540 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
1541 copies the contents of the region into the specified file. @kbd{M-x
1542 append-to-file} adds the text of the region to the end of the
1543 specified file. @xref{Accumulating Text}. The variable
1544 @code{write-region-inhibit-fsync} applies to these commands, as well
1545 as saving files; see @ref{Customize Save}.
1548 @cindex deletion (of files)
1549 @vindex delete-by-moving-to-trash
1550 @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
1551 command in the shell. If you are deleting many files in one
1552 directory, it may be more convenient to use Dired rather than
1553 @code{delete-file}. @xref{Dired}.
1557 On some systems, there is a facility called the ``Trash'' (or
1558 ``Recycle Bin''); ``deleting'' a file normally means moving it into
1559 the Trash, and you can bring the file back from the Trash if you later
1560 change your mind. By default, Emacs does @emph{not} use the Trash for
1561 file deletion---when Emacs deletes a file, it is gone forever. You
1562 can tell Emacs to use the Trash by changing the variable
1563 @code{delete-by-moving-to-trash} to @code{t}. This applies to file
1564 deletion via @kbd{M-x delete-file}, as well as @kbd{M-x
1565 delete-directory} (@pxref{Directories}) and file deletion in Dired
1566 (@pxref{Dired Deletion}). In addition, you can explicitly move a file
1567 into the Trash with the command @kbd{M-x move-file-to-trash}.
1570 @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
1571 the minibuffer, then renames file @var{old} as @var{new}. If the file name
1572 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
1573 done; this is because renaming causes the old meaning of the name @var{new}
1574 to be lost. If @var{old} and @var{new} are on different file systems, the
1575 file @var{old} is copied and deleted.
1577 If the argument @var{new} is just a directory name, the real new
1578 name is in that directory, with the same non-directory component as
1579 @var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET}
1580 renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all
1581 the remaining commands in this section. All of them ask for
1582 confirmation when the new file name already exists, too.
1584 @findex add-name-to-file
1585 @cindex hard links (creation)
1586 The similar command @kbd{M-x add-name-to-file} is used to add an
1587 additional name to an existing file without removing its old name.
1588 The new name is created as a ``hard link'' to the existing file.
1589 The new name must belong on the same file system that the file is on.
1590 On MS-Windows, this command works only if the file resides in an NTFS
1591 file system. On MS-DOS, it works by copying the file.
1594 @findex copy-directory
1595 @cindex copying files
1596 @kbd{M-x copy-file} reads the file @var{old} and writes a new file
1597 named @var{new} with the same contents. @kbd{M-x copy-directory} does
1598 the same for directories, by recursive copying all files and
1601 @findex make-symbolic-link
1602 @cindex symbolic links (creation)
1603 @kbd{M-x make-symbolic-link} reads two file names @var{target} and
1604 @var{linkname}, then creates a symbolic link named @var{linkname},
1605 which points at @var{target}. The effect is that future attempts to
1606 open file @var{linkname} will refer to whatever file is named
1607 @var{target} at the time the opening is done, or will get an error if
1608 the name @var{target} is nonexistent at that time. This command does
1609 not expand the argument @var{target}, so that it allows you to specify
1610 a relative name as the target of the link.
1612 Not all systems support symbolic links; on systems that don't
1613 support them, this command is not defined.
1615 @findex set-file-modes
1617 @cindex file permissions
1618 @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file
1619 mode}, and applies that file mode to the specified file. File modes,
1620 also called @dfn{file permissions}, determine whether a file can be
1621 read, written to, or executed, and by whom. This command reads file
1622 modes using the same symbolic or octal format accepted by the
1623 @command{chmod} command; for instance, @samp{u+x} means to add
1624 execution permission for the user who owns the file. It has no effect
1625 on operating systems that do not support file modes. @code{chmod} is a
1626 convenience alias for this function.
1628 @node Compressed Files
1629 @section Accessing Compressed Files
1631 @cindex uncompression
1632 @cindex Auto Compression mode
1633 @cindex mode, Auto Compression
1636 Emacs automatically uncompresses compressed files when you visit
1637 them, and automatically recompresses them if you alter them and save
1638 them. Emacs recognizes compressed files by their file names. File
1639 names ending in @samp{.gz} indicate a file compressed with
1640 @code{gzip}. Other endings indicate other compression programs.
1642 Automatic uncompression and compression apply to all the operations in
1643 which Emacs uses the contents of a file. This includes visiting it,
1644 saving it, inserting its contents into a buffer, loading it, and byte
1647 @findex auto-compression-mode
1648 @vindex auto-compression-mode
1649 To disable this feature, type the command @kbd{M-x
1650 auto-compression-mode}. You can disable it permanently by
1651 customizing the variable @code{auto-compression-mode}.
1654 @section File Archives
1657 @cindex file archives
1659 A file whose name ends in @samp{.tar} is normally an @dfn{archive}
1660 made by the @code{tar} program. Emacs views these files in a special
1661 mode called Tar mode which provides a Dired-like list of the contents
1662 (@pxref{Dired}). You can move around through the list just as you
1663 would in Dired, and visit the subfiles contained in the archive.
1664 However, not all Dired commands are available in Tar mode.
1666 If Auto Compression mode is enabled (@pxref{Compressed Files}), then
1667 Tar mode is used also for compressed archives---files with extensions
1668 @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}.
1670 The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file
1671 into its own buffer. You can edit it there, and if you save the
1672 buffer, the edited version will replace the version in the Tar buffer.
1673 @kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts
1674 the file and displays it in another window, so you could edit the file
1675 and operate on the archive simultaneously. @kbd{d} marks a file for
1676 deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in
1677 Dired. @kbd{C} copies a file from the archive to disk and @kbd{R}
1678 renames a file within the archive. @kbd{g} reverts the buffer from
1679 the archive on disk.
1681 The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission
1682 bits, group, and owner, respectively.
1684 If your display supports colors and the mouse, moving the mouse
1685 pointer across a file name highlights that file name, indicating that
1686 you can click on it. Clicking @kbd{Mouse-2} on the highlighted file
1687 name extracts the file into a buffer and displays that buffer.
1689 Saving the Tar buffer writes a new version of the archive to disk with
1690 the changes you made to the components.
1692 You don't need the @code{tar} program to use Tar mode---Emacs reads
1693 the archives directly. However, accessing compressed archives
1694 requires the appropriate uncompression program.
1696 @cindex Archive mode
1697 @cindex mode, archive
1710 @cindex Java class archives
1711 @cindex unzip archives
1712 A separate but similar Archive mode is used for archives produced by
1713 the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip},
1714 @code{rar}, and @code{zoo}, which have extensions corresponding to the
1715 program names. Archive mode also works for those @code{exe} files
1716 that are self-extracting executables.
1718 The key bindings of Archive mode are similar to those in Tar mode,
1719 with the addition of the @kbd{m} key which marks a file for subsequent
1720 operations, and @kbd{M-@key{DEL}} which unmarks all the marked files.
1721 Also, the @kbd{a} key toggles the display of detailed file
1722 information, for those archive types where it won't fit in a single
1723 line. Operations such as renaming a subfile, or changing its mode or
1724 owner, are supported only for some of the archive formats.
1726 Unlike Tar mode, Archive mode runs the archiving program to unpack
1727 and repack archives. Details of the program names and their options
1728 can be set in the @samp{Archive} Customize group. However, you don't
1729 need these programs to look at the archive table of contents, only to
1730 extract or manipulate the subfiles in the archive.
1733 @section Remote Files
1737 @cindex remote file access
1738 You can refer to files on other machines using a special file name
1743 /@var{host}:@var{filename}
1744 /@var{user}@@@var{host}:@var{filename}
1745 /@var{user}@@@var{host}#@var{port}:@var{filename}
1746 /@var{method}:@var{user}@@@var{host}:@var{filename}
1747 /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
1752 To carry out this request, Emacs uses a remote-login program such as
1753 @command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}.
1754 You can always specify in the file name which method to use---for
1755 example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP,
1756 whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses
1757 @command{ssh}. When you don't specify a method in the file name,
1758 Emacs chooses the method as follows:
1762 If the host name starts with @samp{ftp.} (with dot), then Emacs uses
1765 If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses
1768 If the variable @code{tramp-default-method} is set to @samp{ftp},
1769 then Emacs uses FTP.
1771 If @command{ssh-agent} is running, then Emacs uses @command{scp}.
1773 Otherwise, Emacs uses @command{ssh}.
1776 @cindex disabling remote files
1778 You can entirely turn off the remote file name feature by setting the
1779 variable @code{tramp-mode} to @code{nil}. You can turn off the
1780 feature in individual cases by quoting the file name with @samp{/:}
1781 (@pxref{Quoted File Names}).
1783 Remote file access through FTP is handled by the Ange-FTP package, which
1784 is documented in the following. Remote file access through the other
1785 methods is handled by the Tramp package, which has its own manual.
1786 @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}.
1788 When the Ange-FTP package is used, Emacs logs in through FTP using
1789 your user name or the name @var{user}. It may ask you for a password
1790 from time to time (@pxref{Passwords}); this is used for logging in on
1791 @var{host}. The form using @var{port} allows you to access servers
1792 running on a non-default TCP port.
1794 @cindex backups for remote files
1795 @vindex ange-ftp-make-backup-files
1796 If you want to disable backups for remote files, set the variable
1797 @code{ange-ftp-make-backup-files} to @code{nil}.
1799 By default, the auto-save files (@pxref{Auto Save Files}) for remote
1800 files are made in the temporary file directory on the local machine.
1801 This is achieved using the variable @code{auto-save-file-name-transforms}.
1804 @vindex ange-ftp-default-user
1805 @cindex user name for remote file access
1806 Normally, if you do not specify a user name in a remote file name,
1807 that means to use your own user name. But if you set the variable
1808 @code{ange-ftp-default-user} to a string, that string is used instead.
1810 @cindex anonymous FTP
1811 @vindex ange-ftp-generate-anonymous-password
1812 To visit files accessible by anonymous FTP, you use special user
1813 names @samp{anonymous} or @samp{ftp}. Passwords for these user names
1814 are handled specially. The variable
1815 @code{ange-ftp-generate-anonymous-password} controls what happens: if
1816 the value of this variable is a string, then that string is used as
1817 the password; if non-@code{nil} (the default), then the value of
1818 @code{user-mail-address} is used; if @code{nil}, then Emacs prompts
1819 you for a password as usual (@pxref{Passwords}).
1821 @cindex firewall, and accessing remote files
1822 @cindex gateway, and remote file access with @code{ange-ftp}
1823 @vindex ange-ftp-smart-gateway
1824 @vindex ange-ftp-gateway-host
1825 Sometimes you may be unable to access files on a remote machine
1826 because a @dfn{firewall} in between blocks the connection for security
1827 reasons. If you can log in on a @dfn{gateway} machine from which the
1828 target files @emph{are} accessible, and whose FTP server supports
1829 gatewaying features, you can still use remote file names; all you have
1830 to do is specify the name of the gateway machine by setting the
1831 variable @code{ange-ftp-gateway-host}, and set
1832 @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able
1833 to make remote file names work, but the procedure is complex. You can
1834 read the instructions by typing @kbd{M-x finder-commentary @key{RET}
1835 ange-ftp @key{RET}}.
1837 @node Quoted File Names
1838 @section Quoted File Names
1840 @cindex quoting file names
1841 @cindex file names, quote special characters
1842 You can @dfn{quote} an absolute file name to prevent special
1843 characters and syntax in it from having their special effects.
1844 The way to do this is to add @samp{/:} at the beginning.
1846 For example, you can quote a local file name which appears remote, to
1847 prevent it from being treated as a remote file name. Thus, if you have
1848 a directory named @file{/foo:} and a file named @file{bar} in it, you
1849 can refer to that file in Emacs as @samp{/:/foo:/bar}.
1851 @samp{/:} can also prevent @samp{~} from being treated as a special
1852 character for a user's home directory. For example, @file{/:/tmp/~hack}
1853 refers to a file whose name is @file{~hack} in directory @file{/tmp}.
1855 Quoting with @samp{/:} is also a way to enter in the minibuffer a
1856 file name that contains @samp{$}. In order for this to work, the
1857 @samp{/:} must be at the beginning of the minibuffer contents. (You
1858 can also double each @samp{$}; see @ref{File Names with $}.)
1860 You can also quote wildcard characters with @samp{/:}, for visiting.
1861 For example, @file{/:/tmp/foo*bar} visits the file
1862 @file{/tmp/foo*bar}.
1864 Another method of getting the same result is to enter
1865 @file{/tmp/foo[*]bar}, which is a wildcard specification that matches
1866 only @file{/tmp/foo*bar}. However, in many cases there is no need to
1867 quote the wildcard characters because even unquoted they give the
1868 right result. For example, if the only file name in @file{/tmp} that
1869 starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar},
1870 then specifying @file{/tmp/foo*bar} will visit only
1871 @file{/tmp/foo*bar}.
1873 @node File Name Cache
1874 @section File Name Cache
1876 @cindex file name caching
1877 @cindex cache of file names
1880 @findex file-cache-minibuffer-complete
1881 You can use the @dfn{file name cache} to make it easy to locate a
1882 file by name, without having to remember exactly where it is located.
1883 When typing a file name in the minibuffer, @kbd{C-@key{tab}}
1884 (@code{file-cache-minibuffer-complete}) completes it using the file
1885 name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the
1886 possible completions of what you had originally typed. (However, note
1887 that the @kbd{C-@key{tab}} character cannot be typed on most text-only
1890 The file name cache does not fill up automatically. Instead, you
1891 load file names into the cache using these commands:
1893 @findex file-cache-add-directory
1895 @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET}
1896 Add each file name in @var{directory} to the file name cache.
1897 @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET}
1898 Add each file name in @var{directory} and all of its nested
1899 subdirectories to the file name cache.
1900 @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET}
1901 Add each file name in @var{directory} and all of its nested
1902 subdirectories to the file name cache, using @command{locate} to find
1904 @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET}
1905 Add each file name in each directory listed in @var{variable}
1906 to the file name cache. @var{variable} should be a Lisp variable
1907 such as @code{load-path} or @code{exec-path}, whose value is a list
1909 @item M-x file-cache-clear-cache @key{RET}
1910 Clear the cache; that is, remove all file names from it.
1913 The file name cache is not persistent: it is kept and maintained
1914 only for the duration of the Emacs session. You can view the contents
1915 of the cache with the @code{file-cache-display} command.
1917 @node File Conveniences
1918 @section Convenience Features for Finding Files
1920 In this section, we introduce some convenient facilities for finding
1921 recently-opened files, reading file names from a buffer, and viewing
1924 @findex recentf-mode
1925 @vindex recentf-mode
1926 @findex recentf-save-list
1927 @findex recentf-edit-list
1928 If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
1929 @samp{File} menu includes a submenu containing a list of recently
1930 opened files. @kbd{M-x recentf-save-list} saves the current
1931 @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list}
1934 The @kbd{M-x ffap} command generalizes @code{find-file} with more
1935 powerful heuristic defaults (@pxref{FFAP}), often based on the text at
1936 point. Partial Completion mode offers other features extending
1937 @code{find-file}, which can be used with @code{ffap}.
1938 @xref{Completion Options}.
1941 @findex image-toggle-display
1942 @cindex images, viewing
1943 Visiting image files automatically selects Image mode. This major
1944 mode allows you to toggle between displaying the file as an image in
1945 the Emacs buffer, and displaying its underlying text representation,
1946 using the command @kbd{C-c C-c} (@code{image-toggle-display}). This
1947 works only when Emacs can display the specific image type. If the
1948 displayed image is wider or taller than the frame, the usual point
1949 motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts
1950 of the image to be displayed.
1953 @findex mode, thumbs
1954 See also the Image-Dired package (@pxref{Image-Dired}) for viewing
1955 images as thumbnails.
1961 @findex filesets-init
1962 If you regularly edit a certain group of files, you can define them
1963 as a @dfn{fileset}. This lets you perform certain operations, such as
1964 visiting, @code{query-replace}, and shell commands on all the files
1965 at once. To make use of filesets, you must first add the expression
1966 @code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}).
1967 This adds a @samp{Filesets} menu to the menu bar.
1969 @findex filesets-add-buffer
1970 @findex filesets-remove-buffer
1971 The simplest way to define a fileset is by adding files to it one
1972 at a time. To add a file to fileset @var{name}, visit the file and
1973 type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If
1974 there is no fileset @var{name}, this creates a new one, which
1975 initially creates only the current file. The command @kbd{M-x
1976 filesets-remove-buffer} removes the current file from a fileset.
1978 You can also edit the list of filesets directly, with @kbd{M-x
1979 filesets-edit} (or by choosing @samp{Edit Filesets} from the
1980 @samp{Filesets} menu). The editing is performed in a Customize buffer
1981 (@pxref{Easy Customization}). Filesets need not be a simple list of
1982 files---you can also define filesets using regular expression matching
1983 file names. Some examples of these more complicated filesets are
1984 shown in the Customize buffer. Remember to select @samp{Save for
1985 future sessions} if you want to use the same filesets in future Emacs
1988 You can use the command @kbd{M-x filesets-open} to visit all the
1989 files in a fileset, and @kbd{M-x filesets-close} to close them. Use
1990 @kbd{M-x filesets-run-cmd} to run a shell command on all the files in
1991 a fileset. These commands are also available from the @samp{Filesets}
1992 menu, where each existing fileset is represented by a submenu.
1994 Emacs uses the concept of a fileset elsewhere @pxref{Version
1995 Control} to describe sets of files to be treated as a group for
1996 purposes of version control operations. Those filesets are unnamed
1997 and do not persist across Emacs sessions.