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 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 maximum buffer size exceeded, error message
205 If you try to visit a file larger than
206 @code{large-file-warning-threshold} (the default is 10000000, which is
207 about 10 megabytes), Emacs asks you for confirmation first. You can
208 answer @kbd{y} to proceed with visiting the file. Note, however, that
209 Emacs cannot visit files that are larger than the maximum Emacs buffer
210 size, which is around 256 megabytes on 32-bit machines
211 (@pxref{Buffers}). If you try, Emacs will display an error message
212 saying that the maximum buffer size has been exceeded.
214 @cindex wildcard characters in file names
215 @vindex find-file-wildcards
216 If the file name you specify contains shell-style wildcard
217 characters, Emacs visits all the files that match it. (On
218 case-insensitive filesystems, Emacs matches the wildcards disregarding
219 the letter case.) Wildcards include @samp{?}, @samp{*}, and
220 @samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file
221 name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted
222 File Names}, for information on how to visit a file whose name
223 actually contains wildcard characters. You can disable the wildcard
224 feature by customizing @code{find-file-wildcards}.
226 @cindex file selection dialog
227 On graphical displays, there are two additional methods for visiting
228 files. Firstly, when Emacs is built with a suitable GUI toolkit,
229 commands invoked with the mouse (by clicking on the menu bar or tool
230 bar) use the toolkit's standard ``File Selection'' dialog instead of
231 prompting for the file name in the minibuffer. On GNU/Linux and Unix
232 platforms, Emacs does this when built with GTK, LessTif, and Motif
233 toolkits; on MS-Windows and Mac, the GUI version does that by default.
234 For information on how to customize this, see @ref{Dialog Boxes}.
236 Secondly, Emacs supports ``drag and drop'': dropping a file into an
237 ordinary Emacs window visits the file using that window. As an
238 exception, dropping a file into a window displaying a Dired buffer
239 moves or copies the file into the displayed directory. For details,
240 see @ref{Drag and Drop}, and @ref{Misc Dired Features}.
242 @cindex creating files
243 @vindex find-file-confirm-nonexistent-file
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. If you change the
248 variable @code{find-file-confirm-nonexistent-file} to @code{t}, then
249 Emacs prompts you for confirmation before visiting a non-existent
253 @findex find-alternate-file
254 If you visit a nonexistent file unintentionally (because you typed
255 the wrong file name), type @kbd{C-x C-v} (@code{find-alternate-file})
256 to visit the file you really wanted. @kbd{C-x C-v} is similar to
257 @kbd{C-x C-f}, but it kills the current buffer (after first offering
258 to save it if it is modified). When @kbd{C-x C-v} reads the file name
259 to visit, it inserts the entire default file name in the buffer, with
260 point just after the directory part; this is convenient if you made a
261 slight error in typing the name.
263 @vindex find-file-run-dired
264 If you ``visit'' a file that is actually a directory, Emacs invokes
265 Dired, the Emacs directory browser; this lets you you ``edit'' the
266 contents of the directory. @xref{Dired}. You can disable this
267 behavior by setting the variable @code{find-file-run-dired} to
268 @code{nil}; in that case, it is an error to try to visit a directory.
270 Files which are actually collections of other files, or @dfn{file
271 archives}, are visited in special modes which invoke a Dired-like
272 environment to allow operations on archive members. @xref{File
273 Archives}, for more about these features.
275 If you visit a file that the operating system won't let you modify,
276 or that is marked read-only, Emacs makes the buffer read-only too, so
277 that you won't go ahead and make changes that you'll have trouble
278 saving afterward. You can make the buffer writable with @kbd{C-x C-q}
279 (@code{toggle-read-only}). @xref{Misc Buffer}.
282 @findex find-file-read-only
283 If you want to visit a file as read-only in order to protect
284 yourself from entering changes accidentally, visit it with the command
285 @kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}.
288 @findex find-file-other-window
289 @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
290 except that the buffer containing the specified file is selected in another
291 window. The window that was selected before @kbd{C-x 4 f} continues to
292 show the same buffer it was already showing. If this command is used when
293 only one window is being displayed, that window is split in two, with one
294 window showing the same buffer as before, and the other one showing the
295 newly requested file. @xref{Windows}.
298 @findex find-file-other-frame
299 @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
300 new frame, or makes visible any existing frame showing the file you
301 seek. This feature is available only when you are using a window
302 system. @xref{Frames}.
304 Emacs recognizes from the contents of a file which end-of-line
305 convention it uses to separate lines---newline (used on GNU/Linux and
306 on Unix), carriage-return linefeed (used on Microsoft systems), or
307 just carriage-return (used on the Macintosh)---and automatically
308 converts the contents to the normal Emacs convention, which is that
309 the newline character separates lines. This is a part of the general
310 feature of coding system conversion (@pxref{Coding Systems}), and
311 makes it possible to edit files imported from different operating
312 systems with equal convenience. If you change the text and save the
313 file, Emacs performs the inverse conversion, changing newlines back
314 into carriage-return linefeed or just carriage-return if appropriate.
316 @findex find-file-literally
317 If you wish to edit a file as a sequence of @acronym{ASCII}
318 characters with no special encoding or conversion, use the @kbd{M-x
319 find-file-literally} command. This visits a file, like @kbd{C-x C-f},
320 but does not do format conversion (@pxref{Formatted Text}), character
321 code conversion (@pxref{Coding Systems}), or automatic uncompression
322 (@pxref{Compressed Files}), and does not add a final newline because
323 of @code{require-final-newline} (@pxref{Customize Save}). If you have
324 already visited the same file in the usual (non-literal) manner, this
325 command asks you whether to visit it literally instead.
327 @vindex find-file-hook
328 @vindex find-file-not-found-functions
329 Two special hook variables allow extensions to modify the operation of
330 visiting files. Visiting a file that does not exist runs the functions
331 in the list @code{find-file-not-found-functions}; this variable holds a list
332 of functions, and the functions are called one by one (with no
333 arguments) until one of them returns non-@code{nil}. This is not a
334 normal hook, and the name ends in @samp{-functions} rather than @samp{-hook}
335 to indicate that fact.
337 Successful visiting of any file, whether existing or not, calls the
338 functions in the list @code{find-file-hook}, with no arguments.
339 This variable is a normal hook. In the case of a nonexistent file, the
340 @code{find-file-not-found-functions} are run first. @xref{Hooks}.
342 There are several ways to specify automatically the major mode for
343 editing the file (@pxref{Choosing Modes}), and to specify local
344 variables defined for that file (@pxref{File Variables}).
347 @section Saving Files
349 @dfn{Saving} a buffer in Emacs means writing its contents back into the file
350 that was visited in the buffer.
353 * Save Commands:: Commands for saving files.
354 * Backup:: How Emacs saves the old version of your file.
355 * Customize Save:: Customizing the saving of files.
356 * Interlocking:: How Emacs protects against simultaneous editing
357 of one file by two users.
358 * Shadowing: File Shadowing. Copying files to "shadows" automatically.
359 * Time Stamps:: Emacs can update time stamps on saved files.
363 @subsection Commands for Saving Files
365 These are the commands that relate to saving and writing files.
369 Save the current buffer in its visited file on disk (@code{save-buffer}).
371 Save any or all buffers in their visited files (@code{save-some-buffers}).
373 Forget that the current buffer has been changed (@code{not-modified}).
374 With prefix argument (@kbd{C-u}), mark the current buffer as changed.
376 Save the current buffer with a specified file name (@code{write-file}).
377 @item M-x set-visited-file-name
378 Change the file name under which the current buffer will be saved.
383 When you wish to save the file and make your changes permanent, type
384 @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
385 displays a message like this:
388 Wrote /u/rms/gnu/gnu.tasks
392 If the selected buffer is not modified (no changes have been made in it
393 since the buffer was created or last saved), saving is not really done,
394 because it would have no effect. Instead, @kbd{C-x C-s} displays a message
395 like this in the echo area:
398 (No changes need to be saved)
401 With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer
402 to be backed up when the next save is done. @xref{Backup}.
405 @findex save-some-buffers
406 The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
407 or all modified buffers. It asks you what to do with each buffer. The
408 possible responses are analogous to those of @code{query-replace}:
412 Save this buffer and ask about the rest of the buffers.
414 Don't save this buffer, but ask about the rest of the buffers.
416 Save this buffer and all the rest with no more questions.
417 @c following generates acceptable underfull hbox
419 Terminate @code{save-some-buffers} without any more saving.
421 Save this buffer, then exit @code{save-some-buffers} without even asking
424 View the buffer that you are currently being asked about. When you exit
425 View mode, you get back to @code{save-some-buffers}, which asks the
428 Diff the buffer against its corresponding file, so you can see
429 what changes you would be saving.
431 Display a help message about these options.
434 @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
435 @code{save-some-buffers} and therefore asks the same questions.
439 If you have changed a buffer but do not wish to save the changes,
440 you should take some action to prevent it. Otherwise, each time you
441 use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer
442 by mistake. One thing you can do is type @kbd{M-~}
443 (@code{not-modified}), which clears out the indication that the buffer
444 is modified. If you do this, none of the save commands will believe
445 that the buffer needs to be saved. (@samp{~} is often used as a
446 mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.)
447 Alternatively, you can cancel all the changes made since the file was
448 visited or saved, by reading the text from the file again. This is
449 called @dfn{reverting}. @xref{Reverting}. (You could also undo all
450 the changes by repeating the undo command @kbd{C-x u} until you have
451 undone all the changes; but reverting is easier.)
453 @findex set-visited-file-name
454 @kbd{M-x set-visited-file-name} alters the name of the file that the
455 current buffer is visiting. It reads the new file name using the
456 minibuffer. Then it marks the buffer as visiting that file name, and
457 changes the buffer name correspondingly. @code{set-visited-file-name}
458 does not save the buffer in the newly visited file; it just alters the
459 records inside Emacs in case you do save later. It also marks the
460 buffer as ``modified'' so that @kbd{C-x C-s} in that buffer
465 If you wish to mark the buffer as visiting a different file and save
466 it right away, use @kbd{C-x C-w} (@code{write-file}). This is
467 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s},
468 except that @kbd{C-x C-w} asks for confirmation if the file exists.
469 @kbd{C-x C-s} used on a buffer that is not visiting a file has the
470 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
471 buffer as visiting that file, and saves it there. The default file
472 name in a buffer that is not visiting a file is made by combining the
473 buffer name with the buffer's default directory (@pxref{File Names}).
475 If the new file name implies a major mode, then @kbd{C-x C-w} switches
476 to that major mode, in most cases. The command
477 @code{set-visited-file-name} also does this. @xref{Choosing Modes}.
479 If Emacs is about to save a file and sees that the date of the latest
480 version on disk does not match what Emacs last read or wrote, Emacs
481 notifies you of this fact, because it probably indicates a problem caused
482 by simultaneous editing and requires your immediate attention.
483 @xref{Interlocking,, Simultaneous Editing}.
486 @subsection Backup Files
488 @vindex make-backup-files
489 @vindex vc-make-backup-files
491 On most operating systems, rewriting a file automatically destroys all
492 record of what the file used to contain. Thus, saving a file from Emacs
493 throws away the old contents of the file---or it would, except that
494 Emacs carefully copies the old contents to another file, called the
495 @dfn{backup} file, before actually saving.
497 Emacs makes a backup for a file only the first time the file is
498 saved from a buffer. No matter how many times you subsequently save
499 the file, its backup remains unchanged. However, if you kill the
500 buffer and then visit the file again, a new backup file will be made.
502 For most files, the variable @code{make-backup-files} determines
503 whether to make backup files. On most operating systems, its default
504 value is @code{t}, so that Emacs does write backup files.
506 For files managed by a version control system (@pxref{Version
507 Control}), the variable @code{vc-make-backup-files} determines whether
508 to make backup files. By default it is @code{nil}, since backup files
509 are redundant when you store all the previous versions in a version
512 @xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}.
515 @xref{General VC Options}.
518 At your option, Emacs can keep either a single backup for each file,
519 or make a series of numbered backup files for each file that you edit.
522 @vindex backup-enable-predicate
523 @vindex temporary-file-directory
524 @vindex small-temporary-file-directory
525 The default value of the @code{backup-enable-predicate} variable
526 prevents backup files being written for files in the directories used
527 for temporary files, specified by @code{temporary-file-directory} or
528 @code{small-temporary-file-directory}.
530 You can explicitly tell Emacs to make another backup file from a
531 buffer, even though that buffer has been saved before. If you save
532 the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
533 into a backup file if you save the buffer again. @kbd{C-u C-u C-x
534 C-s} saves the buffer, but first makes the previous file contents into
535 a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it
536 makes a backup from the previous contents, and arranges to make
537 another from the newly saved contents if you save again.
540 * Names: Backup Names. How backup files are named.
541 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
542 * Copying: Backup Copying. Backups can be made by copying or renaming.
546 @subsubsection Single or Numbered Backups
548 When Emacs makes a backup file, its name is normally constructed by
549 appending @samp{~} to the file name being edited; thus, the backup
550 file for @file{eval.c} would be @file{eval.c~}.
552 If access control stops Emacs from writing backup files under the usual
553 names, it writes the backup file as @file{%backup%~} in your home
554 directory. Only one such file can exist, so only the most recently
555 made such backup is available.
557 Emacs can also make @dfn{numbered backup files}. Numbered backup
558 file names contain @samp{.~}, the number, and another @samp{~} after
559 the original file name. Thus, the backup files of @file{eval.c} would
560 be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way
561 through names like @file{eval.c.~259~} and beyond.
563 @vindex version-control
564 The variable @code{version-control} determines whether to make
565 single backup files or multiple numbered backup files. Its possible
570 Make numbered backups for files that have numbered backups already.
571 Otherwise, make single backups. This is the default.
573 Make numbered backups.
575 Never make numbered backups; always make single backups.
579 The usual way to set this variable is globally, through your
580 @file{.emacs} file or the customization buffer. However, you can set
581 @code{version-control} locally in an individual buffer to control the
582 making of backups for that buffer's file (@pxref{Locals}). You can
583 have Emacs set @code{version-control} locally whenever you visit a
584 given file (@pxref{File Variables}). Some modes, such as Rmail mode,
587 @cindex @env{VERSION_CONTROL} environment variable
588 If you set the environment variable @env{VERSION_CONTROL}, to tell
589 various GNU utilities what to do with backup files, Emacs also obeys the
590 environment variable by setting the Lisp variable @code{version-control}
591 accordingly at startup. If the environment variable's value is @samp{t}
592 or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
593 value is @samp{nil} or @samp{existing}, then @code{version-control}
594 becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
595 @code{version-control} becomes @code{never}.
597 @vindex backup-directory-alist
598 You can customize the variable @code{backup-directory-alist} to
599 specify that files matching certain patterns should be backed up in
600 specific directories. This variable applies to both single and
601 numbered backups. A typical use is to add an element @code{("."
602 . @var{dir})} to make all backups in the directory with absolute name
603 @var{dir}; Emacs modifies the backup file names to avoid clashes
604 between files with the same names originating in different
605 directories. Alternatively, adding, @code{("." . ".~")} would make
606 backups in the invisible subdirectory @file{.~} of the original file's
607 directory. Emacs creates the directory, if necessary, to make the
610 @vindex make-backup-file-name-function
611 If you define the variable @code{make-backup-file-name-function} to
612 a suitable Lisp function, that overrides the usual way Emacs
613 constructs backup file names.
615 @node Backup Deletion
616 @subsubsection Automatic Deletion of Backups
618 To prevent excessive consumption of disk space, Emacs can delete numbered
619 backup versions automatically. Generally Emacs keeps the first few backups
620 and the latest few backups, deleting any in between. This happens every
621 time a new backup is made.
623 @vindex kept-old-versions
624 @vindex kept-new-versions
625 The two variables @code{kept-old-versions} and
626 @code{kept-new-versions} control this deletion. Their values are,
627 respectively, the number of oldest (lowest-numbered) backups to keep
628 and the number of newest (highest-numbered) ones to keep, each time a
629 new backup is made. The backups in the middle (excluding those oldest
630 and newest) are the excess middle versions---those backups are
631 deleted. These variables' values are used when it is time to delete
632 excess versions, just after a new backup version is made; the newly
633 made backup is included in the count in @code{kept-new-versions}. By
634 default, both variables are 2.
636 @vindex delete-old-versions
637 If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
638 backup files silently. If it is @code{nil}, the default, Emacs asks
639 you whether it should delete the excess backup versions. If it has
640 any other value, then Emacs never automatically deletes backups.
642 Dired's @kbd{.} (Period) command can also be used to delete old versions.
643 @xref{Dired Deletion}.
646 @subsubsection Copying vs.@: Renaming
648 Backup files can be made by copying the old file or by renaming it.
649 This makes a difference when the old file has multiple names (hard
650 links). If the old file is renamed into the backup file, then the
651 alternate names become names for the backup file. If the old file is
652 copied instead, then the alternate names remain names for the file
653 that you are editing, and the contents accessed by those names will be
656 The method of making a backup file may also affect the file's owner
657 and group. If copying is used, these do not change. If renaming is used,
658 you become the file's owner, and the file's group becomes the default
659 (different operating systems have different defaults for the group).
661 Having the owner change is usually a good idea, because then the owner
662 always shows who last edited the file. Also, the owners of the backups
663 show who produced those versions. Occasionally there is a file whose
664 owner should not change; it is a good idea for such files to contain
665 local variable lists to set @code{backup-by-copying-when-mismatch}
666 locally (@pxref{File Variables}).
668 @vindex backup-by-copying
669 @vindex backup-by-copying-when-linked
670 @vindex backup-by-copying-when-mismatch
671 @vindex backup-by-copying-when-privileged-mismatch
672 @cindex file ownership, and backup
673 @cindex backup, and user-id
674 The choice of renaming or copying is controlled by four variables.
675 Renaming is the default choice. If the variable
676 @code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise,
677 if the variable @code{backup-by-copying-when-linked} is non-@code{nil},
678 then copying is used for files that have multiple names, but renaming
679 may still be used when the file being edited has only one name. If the
680 variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then
681 copying is used if renaming would cause the file's owner or group to
682 change. @code{backup-by-copying-when-mismatch} is @code{t} by default
683 if you start Emacs as the superuser. The fourth variable,
684 @code{backup-by-copying-when-privileged-mismatch}, gives the highest
685 numeric user-id for which @code{backup-by-copying-when-mismatch} will be
686 forced on. This is useful when low-numbered user-ids are assigned to
687 special system users, such as @code{root}, @code{bin}, @code{daemon},
688 etc., which must maintain ownership of files.
690 When a file is managed with a version control system (@pxref{Version
691 Control}), Emacs does not normally make backups in the usual way for
692 that file. But check-in and check-out are similar in some ways to
693 making backups. One unfortunate similarity is that these operations
694 typically break hard links, disconnecting the file name you visited from
695 any alternate names for the same file. This has nothing to do with
696 Emacs---the version control system does it.
699 @subsection Customizing Saving of Files
701 @vindex require-final-newline
702 If the value of the variable @code{require-final-newline} is
703 @code{t}, saving or writing a file silently puts a newline at the end
704 if there isn't already one there. If the value is @code{visit}, Emacs
705 adds a newline at the end of any file that doesn't have one, just
706 after it visits the file. (This marks the buffer as modified, and you
707 can undo it.) If the value is @code{visit-save}, that means to add
708 newlines both on visiting and on saving. If the value is @code{nil},
709 Emacs leaves the end of the file unchanged; if it's neither @code{nil}
710 nor @code{t}, Emacs asks you whether to add a newline. The default is
713 @vindex mode-require-final-newline
714 Many major modes are designed for specific kinds of files that are
715 always supposed to end in newlines. These major modes set the
716 variable @code{require-final-newline} according to
717 @code{mode-require-final-newline}. By setting the latter variable,
718 you can control how these modes handle final newlines.
720 @vindex write-region-inhibit-fsync
721 When Emacs saves a file, it invokes the @code{fsync} system call to
722 force the data immediately out to disk. This is important for safety
723 if the system crashes or in case of power outage. However, it can be
724 disruptive on laptops using power saving, because it requires the disk
725 to spin up each time you save a file. Setting
726 @code{write-region-inhibit-fsync} to a non-@code{nil} value disables
727 this synchronization. Be careful---this means increased risk of data
731 @subsection Protection against Simultaneous Editing
734 @cindex simultaneous editing
735 Simultaneous editing occurs when two users visit the same file, both
736 make changes, and then both save them. If nobody were informed that
737 this was happening, whichever user saved first would later find that his
740 On some systems, Emacs notices immediately when the second user starts
741 to change the file, and issues an immediate warning. On all systems,
742 Emacs checks when you save the file, and warns if you are about to
743 overwrite another user's changes. You can prevent loss of the other
744 user's work by taking the proper corrective action instead of saving the
747 @findex ask-user-about-lock
748 @cindex locking files
749 When you make the first modification in an Emacs buffer that is
750 visiting a file, Emacs records that the file is @dfn{locked} by you.
751 (It does this by creating a specially-named symbolic link in the same
752 directory.) Emacs removes the lock when you save the changes. The
753 idea is that the file is locked whenever an Emacs buffer visiting it
757 If you begin to modify the buffer while the visited file is locked by
758 someone else, this constitutes a @dfn{collision}. When Emacs detects a
759 collision, it asks you what to do, by calling the Lisp function
760 @code{ask-user-about-lock}. You can redefine this function for the sake
761 of customization. The standard definition of this function asks you a
762 question and accepts three possible answers:
766 Steal the lock. Whoever was already changing the file loses the lock,
767 and you gain the lock.
769 Proceed. Go ahead and edit the file despite its being locked by someone else.
771 Quit. This causes an error (@code{file-locked}), and the buffer
772 contents remain unchanged---the modification you were trying to make
773 does not actually take place.
776 Note that locking works on the basis of a file name; if a file has
777 multiple names, Emacs does not realize that the two names are the same file
778 and cannot prevent two users from editing it simultaneously under different
779 names. However, basing locking on names means that Emacs can interlock the
780 editing of new files that will not really exist until they are saved.
782 Some systems are not configured to allow Emacs to make locks, and
783 there are cases where lock files cannot be written. In these cases,
784 Emacs cannot detect trouble in advance, but it still can detect the
785 collision when you try to save a file and overwrite someone else's
786 changes. Every time Emacs saves a buffer, it first checks the
787 last-modification date of the existing file on disk to verify that it
788 has not changed since the file was last visited or saved. If the date
789 does not match, it implies that changes were made in the file in some
790 other way, and these changes are about to be lost if Emacs actually
791 does save. To prevent this, Emacs displays a warning message and asks
792 for confirmation before saving. Occasionally you will know why the
793 file was changed and know that it does not matter; then you can answer
794 @kbd{yes} and proceed. Otherwise, you should cancel the save with
795 @kbd{C-g} and investigate the situation.
797 If Emacs or the operating system crashes, this may leave behind lock
798 files which are stale, so you may occasionally get warnings about
799 spurious collisions. When you determine that the collision is spurious,
800 just use @kbd{p} to tell Emacs to go ahead anyway.
802 The first thing you should do when notified that simultaneous editing
803 has already taken place is to list the directory with @kbd{C-u C-x C-d}
804 (@pxref{Directories}). This shows the file's current author. You
805 should attempt to contact him to warn him not to continue editing.
806 Often the next step is to save the contents of your Emacs buffer under a
807 different name, and use @code{diff} to compare the two files.@refill
810 @subsection Shadowing Files
813 @findex shadow-initialize
816 @item M-x shadow-initialize
817 Set up file shadowing.
818 @item M-x shadow-define-literal-group
819 Declare a single file to be shared between sites.
820 @item M-x shadow-define-regexp-group
821 Make all files that match each of a group of files be shared between hosts.
822 @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
823 Define a shadow file cluster @var{name}.
824 @item M-x shadow-copy-files
825 Copy all pending shadow files.
826 @item M-x shadow-cancel
827 Cancel the instruction to shadow some files.
830 You can arrange to keep identical @dfn{shadow} copies of certain files
831 in more than one place---possibly on different machines. To do this,
832 first you must set up a @dfn{shadow file group}, which is a set of
833 identically-named files shared between a list of sites. The file
834 group is permanent and applies to further Emacs sessions as well as
835 the current one. Once the group is set up, every time you exit Emacs,
836 it will copy the file you edited to the other files in its group. You
837 can also do the copying without exiting Emacs, by typing @kbd{M-x
840 To set up a shadow file group, use @kbd{M-x
841 shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}.
842 See their documentation strings for further information.
844 Before copying a file to its shadows, Emacs asks for confirmation.
845 You can answer ``no'' to bypass copying of this file, this time. If
846 you want to cancel the shadowing permanently for a certain file, use
847 @kbd{M-x shadow-cancel} to eliminate or change the shadow file group.
849 A @dfn{shadow cluster} is a group of hosts that share directories, so
850 that copying to or from one of them is sufficient to update the file
851 on all of them. Each shadow cluster has a name, and specifies the
852 network address of a primary host (the one we copy files to), and a
853 regular expression that matches the host names of all the other hosts
854 in the cluster. You can define a shadow cluster with @kbd{M-x
855 shadow-define-cluster}.
858 @subsection Updating Time Stamps Automatically
860 @cindex modification dates
861 @cindex locale, date format
863 You can arrange to put a time stamp in a file, so that it will be updated
864 automatically each time you edit and save the file. The time stamp
865 has to be in the first eight lines of the file, and you should
880 Then add the hook function @code{time-stamp} to the hook
881 @code{before-save-hook}; that hook function will automatically update
882 the time stamp, inserting the current date and time when you save the
883 file. You can also use the command @kbd{M-x time-stamp} to update the
884 time stamp manually. For other customizations, see the Custom group
885 @code{time-stamp}. Note that non-numeric fields in the time stamp are
886 formatted according to your locale setting (@pxref{Environment}).
889 @section Reverting a Buffer
890 @findex revert-buffer
891 @cindex drastic changes
892 @cindex reread a file
894 If you have made extensive changes to a file and then change your mind
895 about them, you can get rid of them by reading in the previous version
896 of the file. To do this, use @kbd{M-x revert-buffer}, which operates on
897 the current buffer. Since reverting a buffer unintentionally could lose
898 a lot of work, you must confirm this command with @kbd{yes}.
900 @code{revert-buffer} tries to position point in such a way that, if
901 the file was edited only slightly, you will be at approximately the
902 same piece of text after reverting as before. However, if you have made
903 drastic changes, point may wind up in a totally different piece of text.
905 Reverting marks the buffer as ``not modified''.
907 Some kinds of buffers that are not associated with files, such as
908 Dired buffers, can also be reverted. For them, reverting means
909 recalculating their contents. Buffers created explicitly with
910 @kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error
913 @vindex revert-without-query
914 When you edit a file that changes automatically and frequently---for
915 example, a log of output from a process that continues to run---it may
916 be useful for Emacs to revert the file without querying you. To
917 request this behavior, set the variable @code{revert-without-query} to
918 a list of regular expressions. When a file name matches one of these
919 regular expressions, @code{find-file} and @code{revert-buffer} will
920 revert it automatically if it has changed---provided the buffer itself
921 is not modified. (If you have edited the text, it would be wrong to
922 discard your changes.)
924 @cindex Global Auto-Revert mode
925 @cindex mode, Global Auto-Revert
926 @cindex Auto-Revert mode
927 @cindex mode, Auto-Revert
928 @findex global-auto-revert-mode
929 @findex auto-revert-mode
930 @findex auto-revert-tail-mode
931 @vindex auto-revert-interval
933 In addition, you can tell Emacs to periodically revert a buffer by
934 typing @kbd{M-x auto-revert-mode}. This turns on Auto-Revert mode, a
935 minor mode that makes Emacs automatically revert the current buffer
936 every five seconds. You can change this interval through the variable
937 @code{auto-revert-interval}. Typing @kbd{M-x global-auto-revert-mode}
938 enables Global Auto-Revert mode, which does the same for all file
939 buffers. Auto-Revert mode and Global Auto-Revert modes do not check
940 or revert remote files, because that is usually too slow.
942 One use of Auto-Revert mode is to ``tail'' a file such as a system
943 log, so that changes made to that file by other programs are
944 continuously displayed. To do this, just move the point to the end of
945 the buffer, and it will stay there as the file contents change.
946 However, if you are sure that the file will only change by growing at
947 the end, use Auto-Revert Tail mode instead
948 (@code{auto-revert-tail-mode}). It is more efficient for this.
950 @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that
951 visit files under version control.
954 @include arevert-xtra.texi
958 @section Auto-Saving: Protection Against Disasters
959 @cindex Auto Save mode
960 @cindex mode, Auto Save
963 From time to time, Emacs automatically saves each visited file in a
964 separate file, without altering the file you actually use. This is
965 called @dfn{auto-saving}. It prevents you from losing more than a
966 limited amount of work if the system crashes.
968 When Emacs determines that it is time for auto-saving, it considers
969 each buffer, and each is auto-saved if auto-saving is enabled for it
970 and it has been changed since the last time it was auto-saved. The
971 message @samp{Auto-saving...} is displayed in the echo area during
972 auto-saving, if any files are actually auto-saved. Errors occurring
973 during auto-saving are caught so that they do not interfere with the
974 execution of commands you have been typing.
977 * Files: Auto Save Files. The file where auto-saved changes are
978 actually made until you save the file.
979 * Control: Auto Save Control. Controlling when and how often to auto-save.
980 * Recover:: Recovering text from auto-save files.
983 @node Auto Save Files
984 @subsection Auto-Save Files
986 Auto-saving does not normally save in the files that you visited,
987 because it can be very undesirable to save a change that you did not
988 want to make permanent. Instead, auto-saving is done in a different
989 file called the @dfn{auto-save file}, and the visited file is changed
990 only when you request saving explicitly (such as with @kbd{C-x C-s}).
992 Normally, the auto-save file name is made by appending @samp{#} to the
993 front and rear of the visited file name. Thus, a buffer visiting file
994 @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that
995 are not visiting files are auto-saved only if you request it explicitly;
996 when they are auto-saved, the auto-save file name is made by appending
997 @samp{#} to the front and rear of buffer name, then
998 adding digits and letters at the end for uniqueness. For
999 example, the @samp{*mail*} buffer in which you compose messages to be
1000 sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file
1001 names are made this way unless you reprogram parts of Emacs to do
1002 something different (the functions @code{make-auto-save-file-name} and
1003 @code{auto-save-file-name-p}). The file name to be used for auto-saving
1004 in a buffer is calculated when auto-saving is turned on in that buffer.
1006 @cindex auto-save for remote files
1007 @vindex auto-save-file-name-transforms
1008 The variable @code{auto-save-file-name-transforms} allows a degree
1009 of control over the auto-save file name. It lets you specify a series
1010 of regular expressions and replacements to transform the auto save
1011 file name. The default value puts the auto-save files for remote
1012 files (@pxref{Remote Files}) into the temporary file directory on the
1015 When you delete a substantial part of the text in a large buffer, auto
1016 save turns off temporarily in that buffer. This is because if you
1017 deleted the text unintentionally, you might find the auto-save file more
1018 useful if it contains the deleted text. To reenable auto-saving after
1019 this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
1022 @vindex auto-save-visited-file-name
1023 If you want auto-saving to be done in the visited file rather than
1024 in a separate auto-save file, set the variable
1025 @code{auto-save-visited-file-name} to a non-@code{nil} value. In this
1026 mode, there is no real difference between auto-saving and explicit
1029 @vindex delete-auto-save-files
1030 A buffer's auto-save file is deleted when you save the buffer in its
1031 visited file. (You can inhibit this by setting the variable
1032 @code{delete-auto-save-files} to @code{nil}.) Changing the visited
1033 file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames
1034 any auto-save file to go with the new visited name.
1036 @node Auto Save Control
1037 @subsection Controlling Auto-Saving
1039 @vindex auto-save-default
1040 @findex auto-save-mode
1041 Each time you visit a file, auto-saving is turned on for that file's
1042 buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
1043 in batch mode; @pxref{Entering Emacs}). The default for this variable is
1044 @code{t}, so auto-saving is the usual practice for file-visiting buffers.
1045 Auto-saving can be turned on or off for any existing buffer with the
1046 command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
1047 auto-save-mode} turns auto-saving on with a positive argument, off with a
1048 zero or negative argument; with no argument, it toggles.
1050 @vindex auto-save-interval
1051 Emacs does auto-saving periodically based on counting how many characters
1052 you have typed since the last time auto-saving was done. The variable
1053 @code{auto-save-interval} specifies how many characters there are between
1054 auto-saves. By default, it is 300. Emacs doesn't accept values that are
1055 too small: if you customize @code{auto-save-interval} to a value less
1056 than 20, Emacs will behave as if the value is 20.
1058 @vindex auto-save-timeout
1059 Auto-saving also takes place when you stop typing for a while. The
1060 variable @code{auto-save-timeout} says how many seconds Emacs should
1061 wait before it does an auto save (and perhaps also a garbage
1062 collection). (The actual time period is longer if the current buffer is
1063 long; this is a heuristic which aims to keep out of your way when you
1064 are editing long buffers, in which auto-save takes an appreciable amount
1065 of time.) Auto-saving during idle periods accomplishes two things:
1066 first, it makes sure all your work is saved if you go away from the
1067 terminal for a while; second, it may avoid some auto-saving while you
1068 are actually typing.
1070 Emacs also does auto-saving whenever it gets a fatal error. This
1071 includes killing the Emacs job with a shell command such as @samp{kill
1072 %emacs}, or disconnecting a phone line or network connection.
1074 @findex do-auto-save
1075 You can request an auto-save explicitly with the command @kbd{M-x
1079 @subsection Recovering Data from Auto-Saves
1081 @findex recover-file
1082 You can use the contents of an auto-save file to recover from a loss
1083 of data with the command @kbd{M-x recover-file @key{RET} @var{file}
1084 @key{RET}}. This visits @var{file} and then (after your confirmation)
1085 restores the contents from its auto-save file @file{#@var{file}#}.
1086 You can then save with @kbd{C-x C-s} to put the recovered text into
1087 @var{file} itself. For example, to recover file @file{foo.c} from its
1088 auto-save file @file{#foo.c#}, do:@refill
1091 M-x recover-file @key{RET} foo.c @key{RET}
1096 Before asking for confirmation, @kbd{M-x recover-file} displays a
1097 directory listing describing the specified file and the auto-save file,
1098 so you can compare their sizes and dates. If the auto-save file
1099 is older, @kbd{M-x recover-file} does not offer to read it.
1101 @findex recover-session
1102 If Emacs or the computer crashes, you can recover all the files you
1103 were editing from their auto save files with the command @kbd{M-x
1104 recover-session}. This first shows you a list of recorded interrupted
1105 sessions. Move point to the one you choose, and type @kbd{C-c C-c}.
1107 Then @code{recover-session} asks about each of the files that were
1108 being edited during that session, asking whether to recover that file.
1109 If you answer @kbd{y}, it calls @code{recover-file}, which works in its
1110 normal fashion. It shows the dates of the original file and its
1111 auto-save file, and asks once again whether to recover that file.
1113 When @code{recover-session} is done, the files you've chosen to
1114 recover are present in Emacs buffers. You should then save them. Only
1115 this---saving them---updates the files themselves.
1117 @vindex auto-save-list-file-prefix
1118 Emacs records information about interrupted sessions for later
1119 recovery in files named
1120 @file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. The
1121 directory used, @file{~/.emacs.d/auto-save-list/}, is determined by
1122 the variable @code{auto-save-list-file-prefix}. You can record
1123 sessions in a different place by customizing that variable. If you
1124 set @code{auto-save-list-file-prefix} to @code{nil} in your
1125 @file{.emacs} file, sessions are not recorded for recovery.
1128 @section File Name Aliases
1129 @cindex symbolic links (visiting)
1130 @cindex hard links (visiting)
1132 Symbolic links and hard links both make it possible for several file
1133 names to refer to the same file. Hard links are alternate names that
1134 refer directly to the file; all the names are equally valid, and no one
1135 of them is preferred. By contrast, a symbolic link is a kind of defined
1136 alias: when @file{foo} is a symbolic link to @file{bar}, you can use
1137 either name to refer to the file, but @file{bar} is the real name, while
1138 @file{foo} is just an alias. More complex cases occur when symbolic
1139 links point to directories.
1141 @vindex find-file-existing-other-name
1142 @vindex find-file-suppress-same-file-warnings
1144 Normally, if you visit a file which Emacs is already visiting under
1145 a different name, Emacs displays a message in the echo area and uses
1146 the existing buffer visiting that file. This can happen on systems
1147 that support hard or symbolic links, or if you use a long file name on
1148 a system that truncates long file names, or on a case-insensitive file
1149 system. You can suppress the message by setting the variable
1150 @code{find-file-suppress-same-file-warnings} to a non-@code{nil}
1151 value. You can disable this feature entirely by setting the variable
1152 @code{find-file-existing-other-name} to @code{nil}: then if you visit
1153 the same file under two different names, you get a separate buffer for
1156 @vindex find-file-visit-truename
1157 @cindex truenames of files
1158 @cindex file truenames
1159 If the variable @code{find-file-visit-truename} is non-@code{nil},
1160 then the file name recorded for a buffer is the file's @dfn{truename}
1161 (made by replacing all symbolic links with their target names), rather
1162 than the name you specify. Setting @code{find-file-visit-truename} also
1163 implies the effect of @code{find-file-existing-other-name}.
1166 @section File Directories
1168 @cindex file directory
1169 @cindex directory listing
1170 The file system groups files into @dfn{directories}. A @dfn{directory
1171 listing} is a list of all the files in a directory. Emacs provides
1172 commands to create and delete directories, and to make directory
1173 listings in brief format (file names only) and verbose format (sizes,
1174 dates, and authors included). Emacs also includes a directory browser
1175 feature called Dired; see @ref{Dired}.
1178 @item C-x C-d @var{dir-or-pattern} @key{RET}
1179 Display a brief directory listing (@code{list-directory}).
1180 @item C-u C-x C-d @var{dir-or-pattern} @key{RET}
1181 Display a verbose directory listing.
1182 @item M-x make-directory @key{RET} @var{dirname} @key{RET}
1183 Create a new directory named @var{dirname}.
1184 @item M-x delete-directory @key{RET} @var{dirname} @key{RET}
1185 Delete the directory named @var{dirname}. It must be empty,
1186 or you get an error.
1189 @findex list-directory
1191 The command to display a directory listing is @kbd{C-x C-d}
1192 (@code{list-directory}). It reads using the minibuffer a file name
1193 which is either a directory to be listed or a wildcard-containing
1194 pattern for the files to be listed. For example,
1197 C-x C-d /u2/emacs/etc @key{RET}
1201 lists all the files in directory @file{/u2/emacs/etc}. Here is an
1202 example of specifying a file name pattern:
1205 C-x C-d /u2/emacs/src/*.c @key{RET}
1208 Normally, @kbd{C-x C-d} displays a brief directory listing containing
1209 just file names. A numeric argument (regardless of value) tells it to
1210 make a verbose listing including sizes, dates, and owners (like
1213 @vindex list-directory-brief-switches
1214 @vindex list-directory-verbose-switches
1215 The text of a directory listing is mostly obtained by running
1216 @code{ls} in an inferior process. Two Emacs variables control the
1217 switches passed to @code{ls}: @code{list-directory-brief-switches} is
1218 a string giving the switches to use in brief listings (@code{"-CF"} by
1219 default), and @code{list-directory-verbose-switches} is a string
1220 giving the switches to use in a verbose listing (@code{"-l"} by
1223 @vindex directory-free-space-program
1224 @vindex directory-free-space-args
1225 In verbose directory listings, Emacs adds information about the
1226 amount of free space on the disk that contains the directory. To do
1227 this, it runs the program specified by
1228 @code{directory-free-space-program} with arguments
1229 @code{directory-free-space-args}.
1231 @node Comparing Files
1232 @section Comparing Files
1233 @cindex comparing files
1236 @vindex diff-switches
1237 The command @kbd{M-x diff} prompts for two file names, using the
1238 minibuffer, and displays the differences between the two files in a
1239 buffer named @samp{*diff*}. This works by running the @command{diff}
1240 program, using options taken from the variable @code{diff-switches}.
1241 The value of @code{diff-switches} should be a string; the default is
1242 @code{"-c"} to specify a context diff. @xref{Top,, Diff, diff,
1243 Comparing and Merging Files}, for more information about
1244 @command{diff} output formats.
1246 The output of the @code{diff} command is shown using a major mode
1247 called Diff mode. @xref{Diff Mode}.
1250 The command @kbd{M-x diff-backup} compares a specified file with its
1251 most recent backup. If you specify the name of a backup file,
1252 @code{diff-backup} compares it with the source file that it is a
1253 backup of. In all other respects, this behaves like @kbd{M-x diff}.
1255 @findex compare-windows
1256 The command @kbd{M-x compare-windows} compares the text in the
1257 current window with that in the next window. (For more information
1258 about windows in Emacs, @ref{Windows}.) Comparison starts at point in
1259 each window, after pushing each initial point value on the mark ring
1260 in its respective buffer. Then it moves point forward in each window,
1261 one character at a time, until it reaches characters that don't match.
1262 Then the command exits.
1264 If point in the two windows is followed by non-matching text when
1265 the command starts, @kbd{M-x compare-windows} tries heuristically to
1266 advance up to matching text in the two windows, and then exits. So if
1267 you use @kbd{M-x compare-windows} repeatedly, each time it either
1268 skips one matching range or finds the start of another.
1270 @vindex compare-ignore-case
1271 @vindex compare-ignore-whitespace
1272 With a numeric argument, @code{compare-windows} ignores changes in
1273 whitespace. If the variable @code{compare-ignore-case} is
1274 non-@code{nil}, the comparison ignores differences in case as well.
1275 If the variable @code{compare-ignore-whitespace} is non-@code{nil},
1276 @code{compare-windows} normally ignores changes in whitespace, and a
1277 prefix argument turns that off.
1281 @cindex failed merges
1282 @cindex merges, failed
1283 @cindex comparing 3 files (@code{diff3})
1284 You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor
1285 mode for editing output from the @command{diff3} program. This is
1286 typically the result of a failed merge from a version control system
1287 ``update'' outside VC, due to conflicting changes to a file. Smerge
1288 mode provides commands to resolve conflicts by selecting specific
1292 @xref{Emerge,,, emacs-xtra, Specialized Emacs Features},
1297 for the Emerge facility, which provides a powerful interface for
1304 @cindex patches, editing
1306 Diff mode is a major mode used for the output of @kbd{M-x diff} and
1307 other similar commands, as well as the output of the @command{diff}
1308 program. This kind of output is called a @dfn{patch}, because it can
1309 be passed to the @command{patch} command to automatically apply the
1310 specified changes. To select Diff mode manually, type @kbd{M-x
1314 The changes specified in a patch are grouped into @dfn{hunks}, which
1315 are contiguous chunks of text that contain one or more changed lines.
1316 Hunks can also include unchanged lines to provide context for the
1317 changes. Each hunk is preceded by a @dfn{hunk header}, which
1318 specifies the old and new line numbers at which the hunk occurs. Diff
1319 mode highlights each hunk header, to distinguish it from the actual
1320 contents of the hunk.
1322 @vindex diff-update-on-the-fly
1323 You can edit a Diff mode buffer like any other buffer. (If it is
1324 read-only, you need to make it writable first. @xref{Misc Buffer}.)
1325 Whenever you change a hunk, Diff mode attempts to automatically
1326 correct the line numbers in the hunk headers, to ensure that the diff
1327 remains ``correct''. To disable automatic line number correction,
1328 change the variable @code{diff-update-on-the-fly} to @code{nil}.
1330 Diff mode treats each hunk as an ``error message,'' similar to
1331 Compilation mode. Thus, you can use commands such as @kbd{C-x '} to
1332 visit the corresponding source locations. @xref{Compilation Mode}.
1334 In addition, Diff mode provides the following commands to navigate,
1335 manipulate and apply parts of patches:
1339 @findex diff-hunk-next
1340 Move to the next hunk-start (@code{diff-hunk-next}).
1343 @findex diff-hunk-prev
1344 Move to the previous hunk-start (@code{diff-hunk-prev}).
1347 @findex diff-file-next
1348 Move to the next file-start, in a multi-file patch
1349 (@code{diff-file-next}).
1352 @findex diff-file-prev
1353 Move to the previous file-start, in a multi-file patch
1354 (@code{diff-file-prev}).
1357 @findex diff-hunk-kill
1358 Kill the hunk at point (@code{diff-hunk-kill}).
1361 @findex diff-file-kill
1362 In a multi-file patch, kill the current file part.
1363 (@code{diff-file-kill}).
1366 @findex diff-apply-hunk
1367 Apply this hunk to its target file (@code{diff-apply-hunk}). With a
1368 prefix argument of @kbd{C-u}, revert this hunk.
1371 @findex diff-refine-hunk
1372 Highlight the changes of the hunk at point with a finer granularity
1373 (@code{diff-refine-hunk}). This allows you to see exactly which parts
1374 of each changed line were actually changed.
1377 @findex diff-goto-source
1378 Go to the source file and line corresponding to this hunk
1379 (@code{diff-goto-source}).
1382 @findex diff-ediff-patch
1383 Start an Ediff session with the patch (@code{diff-ediff-patch}).
1384 @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
1387 @findex diff-restrict-view
1388 Restrict the view to the current hunk (@code{diff-restrict-view}).
1389 @xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the
1390 view to the current file of a multiple-file patch. To widen again,
1391 use @kbd{C-x n w} (@code{widen}).
1394 @findex diff-reverse-direction
1395 Reverse the direction of comparison for the entire buffer
1396 (@code{diff-reverse-direction}).
1399 @findex diff-split-hunk
1400 Split the hunk at point (@code{diff-split-hunk}). This is for
1401 manually editing patches, and only works with the @dfn{unified diff
1402 format} produced by the @option{-u} or @option{--unified} options to
1403 the @command{diff} program. If you need to split a hunk in the
1404 @dfn{context diff format} produced by the @option{-c} or
1405 @option{--context} options to @command{diff}, first convert the buffer
1406 to the unified diff format with @kbd{C-c C-u}.
1409 @findex diff-unified->context
1410 Convert the entire buffer to the @dfn{context diff format}
1411 (@code{diff-unified->context}). With a prefix argument, convert only
1412 the text within the region.
1415 @findex diff-context->unified
1416 Convert the entire buffer to unified diff format
1417 (@code{diff-context->unified}). With a prefix argument, convert
1418 unified format to context format. When the mark is active, convert
1419 only the text within the region.
1422 @findex diff-refine-hunk
1423 Refine the current hunk so that it disregards changes in whitespace
1424 (@code{diff-refine-hunk}).
1427 @findex diff-add-change-log-entries-other-window
1428 @findex add-change-log-entry-other-window@r{, in Diff mode}
1429 Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change
1430 Log}), for each one of the hunks
1431 (@code{diff-add-change-log-entries-other-window}). This creates a
1432 skeleton of the log of changes that you can later fill with the actual
1433 descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode
1434 operates on behalf of the current hunk's file, but gets the function
1435 name from the patch itself. This is useful for making log entries for
1436 functions that are deleted by the patch.
1438 @item M-x diff-show-trailing-whitespaces RET
1439 @findex diff-show-trailing-whitespaces
1440 Highlight trailing whitespace characters, except for those used by the
1441 patch syntax (@pxref{Useless Whitespace}).
1446 @section Miscellaneous File Operations
1448 Emacs has commands for performing many other operations on files.
1449 All operate on one file; they do not accept wildcard file names.
1455 @kbd{M-x view-file} allows you to scan or read a file by sequential
1456 screenfuls. It reads a file name argument using the minibuffer. After
1457 reading the file into an Emacs buffer, @code{view-file} displays the
1458 beginning. You can then type @key{SPC} to scroll forward one windowful,
1459 or @key{DEL} to scroll backward. Various other commands are provided
1460 for moving around in the file, but none for changing it; type @kbd{?}
1461 while viewing for a list of them. They are mostly the same as normal
1462 Emacs cursor motion commands. To exit from viewing, type @kbd{q}.
1463 The commands for viewing are defined by a special minor mode called View
1466 A related command, @kbd{M-x view-buffer}, views a buffer already present
1467 in Emacs. @xref{Misc Buffer}.
1471 @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
1472 contents of the specified file into the current buffer at point,
1473 leaving point unchanged before the contents. The position after the
1474 inserted contents is added to the mark ring, without activating the
1475 mark (@pxref{Mark Ring}).
1477 @findex insert-file-literally
1478 @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
1479 except the file is inserted ``literally'': it is treated as a sequence
1480 of @acronym{ASCII} characters with no special encoding or conversion,
1481 similar to the @kbd{M-x find-file-literally} command
1484 @findex write-region
1485 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
1486 copies the contents of the region into the specified file. @kbd{M-x
1487 append-to-file} adds the text of the region to the end of the
1488 specified file. @xref{Accumulating Text}. The variable
1489 @code{write-region-inhibit-fsync} applies to these commands, as well
1490 as saving files; see @ref{Customize Save}.
1493 @cindex deletion (of files)
1494 @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
1495 command in the shell. If you are deleting many files in one directory, it
1496 may be more convenient to use Dired (@pxref{Dired}).
1499 @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
1500 the minibuffer, then renames file @var{old} as @var{new}. If the file name
1501 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
1502 done; this is because renaming causes the old meaning of the name @var{new}
1503 to be lost. If @var{old} and @var{new} are on different file systems, the
1504 file @var{old} is copied and deleted.
1506 If the argument @var{new} is just a directory name, the real new
1507 name is in that directory, with the same non-directory component as
1508 @var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET}
1509 renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all
1510 the remaining commands in this section. All of them ask for
1511 confirmation when the new file name already exists, too.
1513 @findex add-name-to-file
1514 @cindex hard links (creation)
1515 The similar command @kbd{M-x add-name-to-file} is used to add an
1516 additional name to an existing file without removing its old name.
1517 The new name is created as a ``hard link'' to the existing file.
1518 The new name must belong on the same file system that the file is on.
1519 On MS-Windows, this command works only if the file resides in an NTFS
1520 file system. On MS-DOS, it works by copying the file.
1523 @cindex copying files
1524 @kbd{M-x copy-file} reads the file @var{old} and writes a new file
1525 named @var{new} with the same contents.
1527 @findex make-symbolic-link
1528 @cindex symbolic links (creation)
1529 @kbd{M-x make-symbolic-link} reads two file names @var{target} and
1530 @var{linkname}, then creates a symbolic link named @var{linkname},
1531 which points at @var{target}. The effect is that future attempts to
1532 open file @var{linkname} will refer to whatever file is named
1533 @var{target} at the time the opening is done, or will get an error if
1534 the name @var{target} is nonexistent at that time. This command does
1535 not expand the argument @var{target}, so that it allows you to specify
1536 a relative name as the target of the link.
1538 Not all systems support symbolic links; on systems that don't
1539 support them, this command is not defined.
1541 @node Compressed Files
1542 @section Accessing Compressed Files
1544 @cindex uncompression
1545 @cindex Auto Compression mode
1546 @cindex mode, Auto Compression
1549 Emacs automatically uncompresses compressed files when you visit
1550 them, and automatically recompresses them if you alter them and save
1551 them. Emacs recognizes compressed files by their file names. File
1552 names ending in @samp{.gz} indicate a file compressed with
1553 @code{gzip}. Other endings indicate other compression programs.
1555 Automatic uncompression and compression apply to all the operations in
1556 which Emacs uses the contents of a file. This includes visiting it,
1557 saving it, inserting its contents into a buffer, loading it, and byte
1560 @findex auto-compression-mode
1561 @vindex auto-compression-mode
1562 To disable this feature, type the command @kbd{M-x
1563 auto-compression-mode}. You can disable it permanently by
1564 customizing the variable @code{auto-compression-mode}.
1567 @section File Archives
1570 @cindex file archives
1572 A file whose name ends in @samp{.tar} is normally an @dfn{archive}
1573 made by the @code{tar} program. Emacs views these files in a special
1574 mode called Tar mode which provides a Dired-like list of the contents
1575 (@pxref{Dired}). You can move around through the list just as you
1576 would in Dired, and visit the subfiles contained in the archive.
1577 However, not all Dired commands are available in Tar mode.
1579 If Auto Compression mode is enabled (@pxref{Compressed Files}), then
1580 Tar mode is used also for compressed archives---files with extensions
1581 @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}.
1583 The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file
1584 into its own buffer. You can edit it there, and if you save the
1585 buffer, the edited version will replace the version in the Tar buffer.
1586 @kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts
1587 the file and displays it in another window, so you could edit the file
1588 and operate on the archive simultaneously. @kbd{d} marks a file for
1589 deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in
1590 Dired. @kbd{C} copies a file from the archive to disk and @kbd{R}
1591 renames a file within the archive. @kbd{g} reverts the buffer from
1592 the archive on disk.
1594 The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission
1595 bits, group, and owner, respectively.
1597 If your display supports colors and the mouse, moving the mouse
1598 pointer across a file name highlights that file name, indicating that
1599 you can click on it. Clicking @kbd{Mouse-2} on the highlighted file
1600 name extracts the file into a buffer and displays that buffer.
1602 Saving the Tar buffer writes a new version of the archive to disk with
1603 the changes you made to the components.
1605 You don't need the @code{tar} program to use Tar mode---Emacs reads
1606 the archives directly. However, accessing compressed archives
1607 requires the appropriate uncompression program.
1609 @cindex Archive mode
1610 @cindex mode, archive
1623 @cindex Java class archives
1624 @cindex unzip archives
1625 A separate but similar Archive mode is used for archives produced by
1626 the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip},
1627 @code{rar}, and @code{zoo}, which have extensions corresponding to the
1628 program names. Archive mode also works for those @code{exe} files
1629 that are self-extracting executables.
1631 The key bindings of Archive mode are similar to those in Tar mode,
1632 with the addition of the @kbd{m} key which marks a file for subsequent
1633 operations, and @kbd{M-@key{DEL}} which unmarks all the marked files.
1634 Also, the @kbd{a} key toggles the display of detailed file
1635 information, for those archive types where it won't fit in a single
1636 line. Operations such as renaming a subfile, or changing its mode or
1637 owner, are supported only for some of the archive formats.
1639 Unlike Tar mode, Archive mode runs the archiving program to unpack
1640 and repack archives. Details of the program names and their options
1641 can be set in the @samp{Archive} Customize group. However, you don't
1642 need these programs to look at the archive table of contents, only to
1643 extract or manipulate the subfiles in the archive.
1646 @section Remote Files
1650 @cindex remote file access
1651 You can refer to files on other machines using a special file name
1656 /@var{host}:@var{filename}
1657 /@var{user}@@@var{host}:@var{filename}
1658 /@var{user}@@@var{host}#@var{port}:@var{filename}
1659 /@var{method}:@var{user}@@@var{host}:@var{filename}
1660 /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
1665 To carry out this request, Emacs uses a remote-login program such as
1666 @command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}.
1667 You can always specify in the file name which method to use---for
1668 example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP,
1669 whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses
1670 @command{ssh}. When you don't specify a method in the file name,
1671 Emacs chooses the method as follows:
1675 If the host name starts with @samp{ftp.} (with dot), then Emacs uses
1678 If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses
1681 If the variable @code{tramp-default-method} is set to @samp{ftp},
1682 then Emacs uses FTP.
1684 If @command{ssh-agent} is running, then Emacs uses @command{scp}.
1686 Otherwise, Emacs uses @command{ssh}.
1689 @cindex disabling remote files
1691 You can entirely turn off the remote file name feature by setting the
1692 variable @code{tramp-mode} to @code{nil}. You can turn off the
1693 feature in individual cases by quoting the file name with @samp{/:}
1694 (@pxref{Quoted File Names}).
1696 Remote file access through FTP is handled by the Ange-FTP package, which
1697 is documented in the following. Remote file access through the other
1698 methods is handled by the Tramp package, which has its own manual.
1699 @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}.
1701 When the Ange-FTP package is used, Emacs logs in through FTP using your
1702 user name or the name @var{user}. It may ask you for a password from
1703 time to time; this is used for logging in on @var{host}. The form using
1704 @var{port} allows you to access servers running on a non-default TCP
1707 @cindex backups for remote files
1708 @vindex ange-ftp-make-backup-files
1709 If you want to disable backups for remote files, set the variable
1710 @code{ange-ftp-make-backup-files} to @code{nil}.
1712 By default, the auto-save files (@pxref{Auto Save Files}) for remote
1713 files are made in the temporary file directory on the local machine.
1714 This is achieved using the variable @code{auto-save-file-name-transforms}.
1717 @vindex ange-ftp-default-user
1718 @cindex user name for remote file access
1719 Normally, if you do not specify a user name in a remote file name,
1720 that means to use your own user name. But if you set the variable
1721 @code{ange-ftp-default-user} to a string, that string is used instead.
1723 @cindex anonymous FTP
1724 @vindex ange-ftp-generate-anonymous-password
1725 To visit files accessible by anonymous FTP, you use special user
1726 names @samp{anonymous} or @samp{ftp}. Passwords for these user names
1727 are handled specially. The variable
1728 @code{ange-ftp-generate-anonymous-password} controls what happens: if
1729 the value of this variable is a string, then that string is used as
1730 the password; if non-@code{nil} (the default), then the value of
1731 @code{user-mail-address} is used; if @code{nil}, then Emacs prompts
1732 you for a password as usual.
1734 @cindex firewall, and accessing remote files
1735 @cindex gateway, and remote file access with @code{ange-ftp}
1736 @vindex ange-ftp-smart-gateway
1737 @vindex ange-ftp-gateway-host
1738 Sometimes you may be unable to access files on a remote machine
1739 because a @dfn{firewall} in between blocks the connection for security
1740 reasons. If you can log in on a @dfn{gateway} machine from which the
1741 target files @emph{are} accessible, and whose FTP server supports
1742 gatewaying features, you can still use remote file names; all you have
1743 to do is specify the name of the gateway machine by setting the
1744 variable @code{ange-ftp-gateway-host}, and set
1745 @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able
1746 to make remote file names work, but the procedure is complex. You can
1747 read the instructions by typing @kbd{M-x finder-commentary @key{RET}
1748 ange-ftp @key{RET}}.
1750 @node Quoted File Names
1751 @section Quoted File Names
1753 @cindex quoting file names
1754 @cindex file names, quote special characters
1755 You can @dfn{quote} an absolute file name to prevent special
1756 characters and syntax in it from having their special effects.
1757 The way to do this is to add @samp{/:} at the beginning.
1759 For example, you can quote a local file name which appears remote, to
1760 prevent it from being treated as a remote file name. Thus, if you have
1761 a directory named @file{/foo:} and a file named @file{bar} in it, you
1762 can refer to that file in Emacs as @samp{/:/foo:/bar}.
1764 @samp{/:} can also prevent @samp{~} from being treated as a special
1765 character for a user's home directory. For example, @file{/:/tmp/~hack}
1766 refers to a file whose name is @file{~hack} in directory @file{/tmp}.
1768 Quoting with @samp{/:} is also a way to enter in the minibuffer a
1769 file name that contains @samp{$}. In order for this to work, the
1770 @samp{/:} must be at the beginning of the minibuffer contents. (You
1771 can also double each @samp{$}; see @ref{File Names with $}.)
1773 You can also quote wildcard characters with @samp{/:}, for visiting.
1774 For example, @file{/:/tmp/foo*bar} visits the file
1775 @file{/tmp/foo*bar}.
1777 Another method of getting the same result is to enter
1778 @file{/tmp/foo[*]bar}, which is a wildcard specification that matches
1779 only @file{/tmp/foo*bar}. However, in many cases there is no need to
1780 quote the wildcard characters because even unquoted they give the
1781 right result. For example, if the only file name in @file{/tmp} that
1782 starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar},
1783 then specifying @file{/tmp/foo*bar} will visit only
1784 @file{/tmp/foo*bar}.
1786 @node File Name Cache
1787 @section File Name Cache
1789 @cindex file name caching
1790 @cindex cache of file names
1793 @findex file-cache-minibuffer-complete
1794 You can use the @dfn{file name cache} to make it easy to locate a
1795 file by name, without having to remember exactly where it is located.
1796 When typing a file name in the minibuffer, @kbd{C-@key{tab}}
1797 (@code{file-cache-minibuffer-complete}) completes it using the file
1798 name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the
1799 possible completions of what you had originally typed. (However, note
1800 that the @kbd{C-@key{tab}} character cannot be typed on most text-only
1803 The file name cache does not fill up automatically. Instead, you
1804 load file names into the cache using these commands:
1806 @findex file-cache-add-directory
1808 @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET}
1809 Add each file name in @var{directory} to the file name cache.
1810 @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET}
1811 Add each file name in @var{directory} and all of its nested
1812 subdirectories to the file name cache.
1813 @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET}
1814 Add each file name in @var{directory} and all of its nested
1815 subdirectories to the file name cache, using @command{locate} to find
1817 @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET}
1818 Add each file name in each directory listed in @var{variable}
1819 to the file name cache. @var{variable} should be a Lisp variable
1820 such as @code{load-path} or @code{exec-path}, whose value is a list
1822 @item M-x file-cache-clear-cache @key{RET}
1823 Clear the cache; that is, remove all file names from it.
1826 The file name cache is not persistent: it is kept and maintained
1827 only for the duration of the Emacs session. You can view the contents
1828 of the cache with the @code{file-cache-display} command.
1830 @node File Conveniences
1831 @section Convenience Features for Finding Files
1833 In this section, we introduce some convenient facilities for finding
1834 recently-opened files, reading file names from a buffer, and viewing
1837 @findex recentf-mode
1838 @vindex recentf-mode
1839 @findex recentf-save-list
1840 @findex recentf-edit-list
1841 If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
1842 @samp{File} menu includes a submenu containing a list of recently
1843 opened files. @kbd{M-x recentf-save-list} saves the current
1844 @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list}
1847 The @kbd{M-x ffap} command generalizes @code{find-file} with more
1848 powerful heuristic defaults (@pxref{FFAP}), often based on the text at
1849 point. Partial Completion mode offers other features extending
1850 @code{find-file}, which can be used with @code{ffap}.
1851 @xref{Completion Options}.
1854 @findex image-toggle-display
1855 @cindex images, viewing
1856 Visiting image files automatically selects Image mode. This major
1857 mode allows you to toggle between displaying the file as an image in
1858 the Emacs buffer, and displaying its underlying text representation,
1859 using the command @kbd{C-c C-c} (@code{image-toggle-display}). This
1860 works only when Emacs can display the specific image type. If the
1861 displayed image is wider or taller than the frame, the usual point
1862 motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts
1863 of the image to be displayed.
1866 @findex mode, thumbs
1867 See also the Image-Dired package (@pxref{Image-Dired}) for viewing
1868 images as thumbnails.
1874 @findex filesets-init
1875 If you regularly edit a certain group of files, you can define them
1876 as a @dfn{fileset}. This lets you perform certain operations, such as
1877 visiting, @code{query-replace}, and shell commands on all the files
1878 at once. To make use of filesets, you must first add the expression
1879 @code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}).
1880 This adds a @samp{Filesets} menu to the menu bar.
1882 @findex filesets-add-buffer
1883 @findex filesets-remove-buffer
1884 The simplest way to define a fileset is by adding files to it one
1885 at a time. To add a file to fileset @var{name}, visit the file and
1886 type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If
1887 there is no fileset @var{name}, this creates a new one, which
1888 initially creates only the current file. The command @kbd{M-x
1889 filesets-remove-buffer} removes the current file from a fileset.
1891 You can also edit the list of filesets directly, with @kbd{M-x
1892 filesets-edit} (or by choosing @samp{Edit Filesets} from the
1893 @samp{Filesets} menu). The editing is performed in a Customize buffer
1894 (@pxref{Easy Customization}). Filesets need not be a simple list of
1895 files---you can also define filesets using regular expression matching
1896 file names. Some examples of these more complicated filesets are
1897 shown in the Customize buffer. Remember to select @samp{Save for
1898 future sessions} if you want to use the same filesets in future Emacs
1901 You can use the command @kbd{M-x filesets-open} to visit all the
1902 files in a fileset, and @kbd{M-x filesets-close} to close them. Use
1903 @kbd{M-x filesets-run-cmd} to run a shell command on all the files in
1904 a fileset. These commands are also available from the @samp{Filesets}
1905 menu, where each existing fileset is represented by a submenu.
1907 Emacs uses the concept of a fileset elsewhere @pxref{Version
1908 Control} to describe sets of files to be treated as a group for
1909 purposes of version control operations. Those filesets are unnamed
1910 and do not persist across Emacs sessions.
1913 arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250