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