1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2017 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.
421 @vindex save-some-buffers-default-predicate
422 You can customize the value of
423 @code{save-some-buffers-default-predicate} to control which buffers
424 Emacs will ask about.
426 @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
427 @code{save-some-buffers} and therefore asks the same questions.
431 If you have changed a buffer but do not wish to save the changes,
432 you should take some action to prevent it. Otherwise, each time you
433 use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer
434 by mistake. One thing you can do is type @kbd{M-~}
435 (@code{not-modified}), which clears out the indication that the buffer
436 is modified. If you do this, none of the save commands will believe
437 that the buffer needs to be saved. (@samp{~} is often used as a
438 mathematical symbol for ``not''; thus @kbd{M-~} is ``not'', metafied.)
439 Alternatively, you can cancel all the changes made since the file was
440 visited or saved, by reading the text from the file again. This is
441 called @dfn{reverting}. @xref{Reverting}. (You could also undo all
442 the changes by repeating the undo command @kbd{C-x u} until you have
443 undone all the changes; but reverting is easier.)
445 @findex set-visited-file-name
446 @kbd{M-x set-visited-file-name} alters the name of the file that the
447 current buffer is visiting. It reads the new file name using the
448 minibuffer. Then it marks the buffer as visiting that file name, and
449 changes the buffer name correspondingly. @code{set-visited-file-name}
450 does not save the buffer in the newly visited file; it just alters the
451 records inside Emacs in case you do save later. It also marks the
452 buffer as modified so that @kbd{C-x C-s} in that buffer
457 If you wish to mark the buffer as visiting a different file and save
458 it right away, use @kbd{C-x C-w} (@code{write-file}). This is
459 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s},
460 except that @kbd{C-x C-w} asks for confirmation if the file exists.
461 @kbd{C-x C-s} used on a buffer that is not visiting a file has the
462 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
463 buffer as visiting that file, and saves it there. The default file
464 name in a buffer that is not visiting a file is made by combining the
465 buffer name with the buffer's default directory (@pxref{File Names}).
467 If the new file name implies a major mode, then @kbd{C-x C-w} switches
468 to that major mode, in most cases. The command
469 @code{set-visited-file-name} also does this. @xref{Choosing Modes}.
471 If Emacs is about to save a file and sees that the date of the latest
472 version on disk does not match what Emacs last read or wrote, Emacs
473 notifies you of this fact, because it probably indicates a problem caused
474 by simultaneous editing and requires your immediate attention.
475 @xref{Interlocking,, Simultaneous Editing}.
478 @subsection Backup Files
480 @vindex make-backup-files
481 @vindex vc-make-backup-files
483 On most operating systems, rewriting a file automatically destroys all
484 record of what the file used to contain. Thus, saving a file from Emacs
485 throws away the old contents of the file---or it would, except that
486 Emacs carefully copies the old contents to another file, called the
487 @dfn{backup} file, before actually saving.
489 Emacs makes a backup for a file only the first time the file is
490 saved from a buffer. No matter how many times you subsequently save
491 the file, its backup remains unchanged. However, if you kill the
492 buffer and then visit the file again, a new backup file will be made.
494 For most files, the variable @code{make-backup-files} determines
495 whether to make backup files. On most operating systems, its default
496 value is @code{t}, so that Emacs does write backup files.
498 For files managed by a version control system (@pxref{Version
499 Control}), the variable @code{vc-make-backup-files} determines whether
500 to make backup files. By default it is @code{nil}, since backup files
501 are redundant when you store all the previous versions in a version
504 @xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}.
507 @xref{General VC Options}.
510 At your option, Emacs can keep either a single backup for each file,
511 or make a series of numbered backup files for each file that you edit.
514 @vindex backup-enable-predicate
515 @vindex temporary-file-directory
516 @vindex small-temporary-file-directory
517 The default value of the @code{backup-enable-predicate} variable
518 prevents backup files being written for files in the directories used
519 for temporary files, specified by @code{temporary-file-directory} or
520 @code{small-temporary-file-directory}.
522 You can explicitly tell Emacs to make another backup file from a
523 buffer, even though that buffer has been saved before. If you save
524 the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
525 into a backup file if you save the buffer again. @kbd{C-u C-u C-x
526 C-s} saves the buffer, but first makes the previous file contents into
527 a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it
528 makes a backup from the previous contents, and arranges to make
529 another from the newly saved contents if you save again.
531 @vindex backup-directory-alist
532 You can customize the variable @code{backup-directory-alist} to
533 specify that files matching certain patterns should be backed up in
534 specific directories. A typical use is to add an element @code{("."
535 . @var{dir})} to make all backups in the directory with absolute name
536 @var{dir}. Emacs modifies the backup file names to avoid clashes
537 between files with the same names originating in different
538 directories. Alternatively, adding, @code{("." . ".~")} would make
539 backups in the invisible subdirectory @file{.~} of the original file's
540 directory. Emacs creates the directory, if necessary, to make the
544 * Names: Backup Names. How backup files are named.
545 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
546 * Copying: Backup Copying. Backups can be made by copying or renaming.
550 @subsubsection Single or Numbered Backups
551 @cindex backup file names
552 @cindex names of backup files
554 @cindex @file{~}, in names of backup files
555 @cindex tilde (@file{~}) at end of backup file name
556 When Emacs makes a backup file, its name is normally constructed by
557 appending @samp{~} to the file name being edited; thus, the backup
558 file for @file{eval.c} would be @file{eval.c~}.
560 @cindex @file{~/.emacs.d/%backup%~}
561 If access control stops Emacs from writing backup files under the
562 usual names, it writes the backup file as @file{~/.emacs.d/%backup%~}.
563 Only one such file can exist, so only the most recently made such
566 Emacs can also make @dfn{numbered backup files}. Numbered backup
567 file names contain @samp{.~}, the number, and another @samp{~} after
568 the original file name. Thus, the backup files of @file{eval.c} would
569 be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way
570 through names like @file{eval.c.~259~} and beyond.
572 @vindex version-control
573 The variable @code{version-control} determines whether to make
574 single backup files or multiple numbered backup files. Its possible
579 Make numbered backups for files that have numbered backups already.
580 Otherwise, make single backups. This is the default.
582 Make numbered backups.
584 Never make numbered backups; always make single backups.
588 The usual way to set this variable is globally, through your init file
589 or the customization buffer. However, you can set
590 @code{version-control} locally in an individual buffer to control the
591 making of backups for that buffer's file (@pxref{Locals}). You can
592 have Emacs set @code{version-control} locally whenever you visit a
593 given file (@pxref{File Variables}). Some modes, such as Rmail mode,
596 @cindex @env{VERSION_CONTROL} environment variable
597 If you set the environment variable @env{VERSION_CONTROL}, to tell
598 various GNU utilities what to do with backup files, Emacs also obeys the
599 environment variable by setting the Lisp variable @code{version-control}
600 accordingly at startup. If the environment variable's value is @samp{t}
601 or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
602 value is @samp{nil} or @samp{existing}, then @code{version-control}
603 becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
604 @code{version-control} becomes @code{never}.
606 @vindex make-backup-file-name-function
607 If you set the variable @code{make-backup-file-name-function} to
608 a suitable Lisp function, you can override the usual way Emacs
609 constructs backup file names.
611 @node Backup Deletion
612 @subsubsection Automatic Deletion of Backups
614 To prevent excessive consumption of disk space, Emacs can delete numbered
615 backup versions automatically. Generally Emacs keeps the first few backups
616 and the latest few backups, deleting any in between. This happens every
617 time a new backup is made.
619 @vindex kept-old-versions
620 @vindex kept-new-versions
621 The two variables @code{kept-old-versions} and
622 @code{kept-new-versions} control this deletion. Their values are,
623 respectively, the number of oldest (lowest-numbered) backups to keep
624 and the number of newest (highest-numbered) ones to keep, each time a
625 new backup is made. The backups in the middle (excluding those oldest
626 and newest) are the excess middle versions---those backups are
627 deleted. These variables' values are used when it is time to delete
628 excess versions, just after a new backup version is made; the newly
629 made backup is included in the count in @code{kept-new-versions}. By
630 default, both variables are 2.
632 @vindex delete-old-versions
633 If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
634 backup files silently. If it is @code{nil}, the default, Emacs asks
635 you whether it should delete the excess backup versions. If it has
636 any other value, then Emacs never automatically deletes backups.
638 Dired's @kbd{.} (Period) command can also be used to delete old versions.
639 @xref{Dired Deletion}.
642 @subsubsection Copying vs.@: Renaming
644 Backup files can be made by copying the old file or by renaming it.
645 This makes a difference when the old file has multiple names (hard
646 links). If the old file is renamed into the backup file, then the
647 alternate names become names for the backup file. If the old file is
648 copied instead, then the alternate names remain names for the file
649 that you are editing, and the contents accessed by those names will be
652 The method of making a backup file may also affect the file's owner
653 and group. If copying is used, these do not change. If renaming is used,
654 you become the file's owner, and the file's group becomes the default
655 (different operating systems have different defaults for the group).
657 @vindex backup-by-copying
658 @vindex backup-by-copying-when-linked
659 @vindex backup-by-copying-when-mismatch
660 @vindex backup-by-copying-when-privileged-mismatch
661 @cindex file ownership, and backup
662 @cindex backup, and user-id
663 The choice of renaming or copying is made as follows:
667 If the variable @code{backup-by-copying} is non-@code{nil} (the
668 default is @code{nil}), use copying.
671 Otherwise, if the variable @code{backup-by-copying-when-linked} is
672 non-@code{nil} (the default is @code{nil}), and the file has multiple
676 Otherwise, if the variable @code{backup-by-copying-when-mismatch} is
677 non-@code{nil} (the default is @code{t}), and renaming would change
678 the file's owner or group, use copying.
680 If you change @code{backup-by-copying-when-mismatch} to @code{nil},
681 Emacs checks the numeric user-id of the file's owner. If this is
682 higher than @code{backup-by-copying-when-privileged-mismatch}, then it
683 behaves as though @code{backup-by-copying-when-mismatch} is
684 non-@code{nil} anyway.
687 Otherwise, renaming is the default choice.
690 When a file is managed with a version control system (@pxref{Version
691 Control}), Emacs does not normally make backups in the usual way for
692 that file. But check-in and check-out are similar in some ways to
693 making backups. One unfortunate similarity is that these operations
694 typically break hard links, disconnecting the file name you visited from
695 any alternate names for the same file. This has nothing to do with
696 Emacs---the version control system does it.
699 @subsection Customizing Saving of Files
701 @vindex require-final-newline
702 If the value of the variable @code{require-final-newline} is
703 @code{t}, saving or writing a file silently puts a newline at the end
704 if there isn't already one there. If the value is @code{visit}, Emacs
705 adds a newline at the end of any file that doesn't have one, just
706 after it visits the file. (This marks the buffer as modified, and you
707 can undo it.) If the value is @code{visit-save}, Emacs adds such
708 newlines both on visiting and on saving. If the value is @code{nil},
709 Emacs leaves the end of the file unchanged; any other non-@code{nil}
710 value means Emacs asks you whether to add a newline. The default is
713 @vindex mode-require-final-newline
714 Some major modes are designed for specific kinds of files that are
715 always supposed to end in newlines. Such major modes set the variable
716 @code{require-final-newline} to the value of
717 @code{mode-require-final-newline}, which defaults to @code{t}. By
718 setting the latter variable, you can control how these modes handle
721 @vindex write-region-inhibit-fsync
722 Normally, when a program writes a file, the operating system briefly
723 caches the file's data in main memory before committing the data to
724 disk. This can greatly improve performance; for example, when running
725 on laptops, it can avoid a disk spin-up each time a file is written.
726 However, it risks data loss if the operating system crashes before
727 committing the cache to disk.
729 To lessen this risk, Emacs can invoke the @code{fsync} system call
730 after saving a file. Using @code{fsync} does not eliminate the risk
731 of data loss, partly because many systems do not implement
732 @code{fsync} properly, and partly because Emacs's file-saving
733 procedure typically relies also on directory updates that might not
734 survive a crash even if @code{fsync} works properly.
736 The @code{write-region-inhibit-fsync} variable controls whether
737 Emacs invokes @code{fsync} after saving a file. The variable's
738 default value is @code{nil} when Emacs is interactive, and @code{t}
739 when Emacs runs in batch mode.
741 Emacs never uses @code{fsync} when writing auto-save files, as these
742 files might lose data anyway.
745 @subsection Protection against Simultaneous Editing
748 @cindex simultaneous editing
749 Simultaneous editing occurs when two users visit the same file, both
750 make changes, and then both save them. If nobody is informed that
751 this is happening, whichever user saves first would later find that
752 his changes were lost.
754 On some systems, Emacs notices immediately when the second user starts
755 to change the file, and issues an immediate warning. On all systems,
756 Emacs checks when you save the file, and warns if you are about to
757 overwrite another user's changes. You can prevent loss of the other
758 user's work by taking the proper corrective action instead of saving the
761 @findex ask-user-about-lock
762 @cindex locking files
763 When you make the first modification in an Emacs buffer that is
764 visiting a file, Emacs records that the file is @dfn{locked} by you.
765 (It does this by creating a specially-named symbolic link@footnote{If
766 your file system does not support symbolic links, a regular file is
767 used.} with special contents in the same directory.) Emacs removes the lock
768 when you save the changes. The idea is that the file is locked
769 whenever an Emacs buffer visiting it has unsaved changes.
771 @vindex create-lockfiles
772 You can prevent the creation of lock files by setting the variable
773 @code{create-lockfiles} to @code{nil}. @strong{Caution:} by
774 doing so you will lose the benefits that this feature provides.
777 If you begin to modify the buffer while the visited file is locked by
778 someone else, this constitutes a @dfn{collision}. When Emacs detects a
779 collision, it asks you what to do, by calling the Lisp function
780 @code{ask-user-about-lock}. You can redefine this function for the sake
781 of customization. The standard definition of this function asks you a
782 question and accepts three possible answers:
786 Steal the lock. Whoever was already changing the file loses the lock,
787 and you gain the lock.
789 Proceed. Go ahead and edit the file despite its being locked by someone else.
791 Quit. This causes an error (@code{file-locked}), and the buffer
792 contents remain unchanged---the modification you were trying to make
793 does not actually take place.
796 If Emacs or the operating system crashes, this may leave behind lock
797 files which are stale, so you may occasionally get warnings about
798 spurious collisions. When you determine that the collision is
799 spurious, just use @kbd{p} to tell Emacs to go ahead anyway.
801 Note that locking works on the basis of a file name; if a file has
802 multiple names, Emacs does not prevent two users from editing it
803 simultaneously under different names.
805 A lock file cannot be written in some circumstances, e.g., if Emacs
806 lacks the system permissions or cannot create lock files for some
807 other reason. In these cases, Emacs can still detect the collision
808 when you try to save a file, by checking the file's last-modification
809 date. If the file has changed since the last time Emacs visited or
810 saved it, that implies that changes have been made in some other way,
811 and will be lost if Emacs proceeds with saving. Emacs then displays a
812 warning message and asks for confirmation before saving; answer
813 @kbd{yes} to save, and @kbd{no} or @kbd{C-g} cancel the save.
815 If you are notified that simultaneous editing has already taken
816 place, one way to compare the buffer to its file is the @kbd{M-x
817 diff-buffer-with-file} command. @xref{Comparing Files}.
820 @subsection Shadowing Files
823 @findex shadow-initialize
826 @item M-x shadow-initialize
827 Set up file shadowing.
828 @item M-x shadow-define-literal-group
829 Declare a single file to be shared between sites.
830 @item M-x shadow-define-regexp-group
831 Make all files that match each of a group of files be shared between hosts.
832 @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
833 Define a shadow file cluster @var{name}.
834 @item M-x shadow-copy-files
835 Copy all pending shadow files.
836 @item M-x shadow-cancel
837 Cancel the instruction to shadow some files.
840 You can arrange to keep identical @dfn{shadow} copies of certain files
841 in more than one place---possibly on different machines. To do this,
842 first you must set up a @dfn{shadow file group}, which is a set of
843 identically-named files shared between a list of sites. The file
844 group is permanent and applies to further Emacs sessions as well as
845 the current one. Once the group is set up, every time you exit Emacs,
846 it will copy the file you edited to the other files in its group. You
847 can also do the copying without exiting Emacs, by typing @kbd{M-x
850 To set up a shadow file group, use @kbd{M-x
851 shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}.
852 See their documentation strings for further information.
854 Before copying a file to its shadows, Emacs asks for confirmation.
855 You can answer ``no'' to bypass copying of this file, this time. If
856 you want to cancel the shadowing permanently for a certain file, use
857 @kbd{M-x shadow-cancel} to eliminate or change the shadow file group.
859 A @dfn{shadow cluster} is a group of hosts that share directories, so
860 that copying to or from one of them is sufficient to update the file
861 on all of them. Each shadow cluster has a name, and specifies the
862 network address of a primary host (the one we copy files to), and a
863 regular expression that matches the host names of all the other hosts
864 in the cluster. You can define a shadow cluster with @kbd{M-x
865 shadow-define-cluster}.
868 @subsection Updating Time Stamps Automatically
870 @cindex modification dates
871 @cindex locale, date format
873 You can arrange to put a time stamp in a file, so that it is updated
874 automatically each time you edit and save the file. The time stamp
875 must be in the first eight lines of the file, and you should insert it
890 Then add the function @code{time-stamp} to the hook
891 @code{before-save-hook} (@pxref{Hooks}). When you save the file, this
892 function then automatically updates the time stamp with the current
893 date and time. You can also use the command @kbd{M-x time-stamp} to
894 update the time stamp manually. By default the time stamp is
895 formatted according to your locale setting (@pxref{Environment}) and
896 time zone (@pxref{Time of Day,,, elisp, The Emacs Lisp Reference
897 Manual}). For customizations, see the Custom group @code{time-stamp}.
900 @section Reverting a Buffer
901 @findex revert-buffer
902 @cindex drastic changes
903 @cindex reread a file
905 If you have made extensive changes to a file-visiting buffer and
906 then change your mind, you can @dfn{revert} the changes and go back to
907 the saved version of the file. To do this, type @kbd{M-x
908 revert-buffer}. Since reverting unintentionally could lose a lot of
909 work, Emacs asks for confirmation first.
911 The @code{revert-buffer} command tries to position point in such a
912 way that, if the file was edited only slightly, you will be at
913 approximately the same part of the text as before. But if you have
914 made major changes, point may end up in a totally different location.
916 Reverting marks the buffer as not modified. It also clears the
917 buffer's undo history (@pxref{Undo}). Thus, the reversion cannot be
918 undone---if you change your mind yet again, you can't use the undo
919 commands to bring the reverted changes back.
921 Some kinds of buffers that are not associated with files, such as
922 Dired buffers, can also be reverted. For them, reverting means
923 recalculating their contents. Buffers created explicitly with
924 @kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error
927 @vindex revert-without-query
928 When you edit a file that changes automatically and frequently---for
929 example, a log of output from a process that continues to run---it may
930 be useful for Emacs to revert the file without querying you. To
931 request this behavior, set the variable @code{revert-without-query} to
932 a list of regular expressions. When a file name matches one of these
933 regular expressions, @code{find-file} and @code{revert-buffer} will
934 revert it automatically if it has changed---provided the buffer itself
935 is not modified. (If you have edited the text, it would be wrong to
936 discard your changes.)
938 @cindex Global Auto-Revert mode
939 @cindex mode, Global Auto-Revert
940 @cindex Auto-Revert mode
941 @cindex mode, Auto-Revert
942 @findex global-auto-revert-mode
943 @findex auto-revert-mode
944 @findex auto-revert-tail-mode
945 @vindex auto-revert-interval
946 @vindex auto-revert-remote-files
947 @vindex auto-revert-verbose
948 You can also tell Emacs to revert buffers periodically. To do this
949 for a specific buffer, enable the minor mode Auto-Revert mode by
950 typing @kbd{M-x auto-revert-mode}. This automatically reverts the
951 current buffer every five seconds; you can change the interval through
952 the variable @code{auto-revert-interval}. To do the same for all file
953 buffers, type @kbd{M-x global-auto-revert-mode} to enable Global
954 Auto-Revert mode. These minor modes do not check or revert remote
955 files, because that is usually too slow. This behavior can be changed
956 by setting the variable @code{auto-revert-remote-files} to non-@code{nil}.
958 One use of Auto-Revert mode is to ``tail'' a file such as a system
959 log, so that changes made to that file by other programs are
960 continuously displayed. To do this, just move the point to the end of
961 the buffer, and it will stay there as the file contents change.
962 However, if you are sure that the file will only change by growing at
963 the end, use Auto-Revert Tail mode instead
964 (@code{auto-revert-tail-mode}). It is more efficient for this.
965 Auto-Revert Tail mode works also for remote files.
967 When a buffer is auto-reverted, a message is generated. This can be
968 suppressed by setting @code{auto-revert-verbose} to @code{nil}.
970 @xref{VC Undo}, for commands to revert to earlier versions of files
971 under version control. @xref{VC Mode Line}, for Auto Revert
972 peculiarities when visiting files under version control.
975 @include arevert-xtra.texi
979 @section Auto-Saving: Protection Against Disasters
980 @cindex Auto Save mode
981 @cindex mode, Auto Save
984 From time to time, Emacs automatically saves each visited file in a
985 separate file, without altering the file you actually use. This is
986 called @dfn{auto-saving}. It prevents you from losing more than a
987 limited amount of work if the system crashes.
989 When Emacs determines that it is time for auto-saving, it considers
990 each buffer, and each is auto-saved if auto-saving is enabled for it
991 and it has been changed since the last time it was auto-saved. The
992 message @samp{Auto-saving...} is displayed in the echo area during
993 auto-saving, if any files are actually auto-saved. Errors occurring
994 during auto-saving are caught so that they do not interfere with the
995 execution of commands you have been typing.
998 * Files: Auto Save Files. The file where auto-saved changes are
999 actually made until you save the file.
1000 * Control: Auto Save Control. Controlling when and how often to auto-save.
1001 * Recover:: Recovering text from auto-save files.
1004 @node Auto Save Files
1005 @subsection Auto-Save Files
1007 Auto-saving does not normally save in the files that you visited,
1008 because it can be very undesirable to save a change that you did not
1009 want to make permanent. Instead, auto-saving is done in a different
1010 file called the @dfn{auto-save file}, and the visited file is changed
1011 only when you request saving explicitly (such as with @kbd{C-x C-s}).
1013 Normally, the auto-save file name is made by appending @samp{#} to the
1014 front and rear of the visited file name. Thus, a buffer visiting file
1015 @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that
1016 are not visiting files are auto-saved only if you request it explicitly;
1017 when they are auto-saved, the auto-save file name is made by appending
1018 @samp{#} to the front and rear of buffer name, then
1019 adding digits and letters at the end for uniqueness. For
1020 example, the @file{*mail*} buffer in which you compose messages to be
1021 sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file
1022 names are made this way unless you reprogram parts of Emacs to do
1023 something different (the functions @code{make-auto-save-file-name} and
1024 @code{auto-save-file-name-p}). The file name to be used for auto-saving
1025 in a buffer is calculated when auto-saving is turned on in that buffer.
1027 @cindex auto-save for remote files
1028 @vindex auto-save-file-name-transforms
1029 The variable @code{auto-save-file-name-transforms} allows a degree
1030 of control over the auto-save file name. It lets you specify a series
1031 of regular expressions and replacements to transform the auto save
1032 file name. The default value puts the auto-save files for remote
1033 files (@pxref{Remote Files}) into the temporary file directory on the
1036 When you delete a substantial part of the text in a large buffer, auto
1037 save turns off temporarily in that buffer. This is because if you
1038 deleted the text unintentionally, you might find the auto-save file more
1039 useful if it contains the deleted text. To reenable auto-saving after
1040 this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
1043 @vindex auto-save-visited-file-name
1044 If you want auto-saving to be done in the visited file rather than
1045 in a separate auto-save file, set the variable
1046 @code{auto-save-visited-file-name} to a non-@code{nil} value. In this
1047 mode, auto-saving is very similar to explicit saving. However,
1048 differences still exist, in particular for modes which modify the
1049 buffer-saving process in non-trivial ways via various hooks
1050 (@pxref{Saving Buffers,,, elisp, The Emacs Lisp Reference Manual}).
1052 @vindex delete-auto-save-files
1053 A buffer's auto-save file is deleted when you save the buffer in its
1054 visited file. (You can inhibit this by setting the variable
1055 @code{delete-auto-save-files} to @code{nil}.) Changing the visited
1056 file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames
1057 any auto-save file to go with the new visited name.
1059 @node Auto Save Control
1060 @subsection Controlling Auto-Saving
1062 @vindex auto-save-default
1063 @findex auto-save-mode
1064 Each time you visit a file, auto-saving is turned on for that file's
1065 buffer if the variable @code{auto-save-default} is non-@code{nil} (but
1066 not in batch mode; @pxref{Initial Options}). The default for this
1067 variable is @code{t}, so auto-saving is the usual practice for
1068 file-visiting buffers. To toggle auto-saving in the current buffer,
1069 type @kbd{M-x auto-save-mode}. Auto Save mode acts as a buffer-local
1070 minor mode (@pxref{Minor Modes}).
1072 @vindex auto-save-interval
1073 Emacs auto-saves periodically based on how many characters you have
1074 typed since the last auto-save. The variable
1075 @code{auto-save-interval} specifies how many characters there are
1076 between auto-saves. By default, it is 300. Emacs doesn't accept
1077 values that are too small: if you customize @code{auto-save-interval}
1078 to a value less than 20, Emacs will behave as if the value is 20.
1080 @vindex auto-save-timeout
1081 Auto-saving also takes place when you stop typing for a while. By
1082 default, it does this after 30 seconds of idleness (at this time,
1083 Emacs may also perform garbage collection; @pxref{Garbage
1084 Collection,,, elisp, The Emacs Lisp Reference Manual}). To change
1085 this interval, customize the variable @code{auto-save-timeout}. The
1086 actual time period is longer if the current buffer is long; this is a
1087 heuristic which aims to keep out of your way when you are editing long
1088 buffers, in which auto-save takes an appreciable amount of time.
1089 Auto-saving during idle periods accomplishes two things: first, it
1090 makes sure all your work is saved if you go away from the terminal for
1091 a while; second, it may avoid some auto-saving while you are actually
1094 Emacs also does auto-saving whenever it gets a fatal error. This
1095 includes killing the Emacs job with a shell command such as @samp{kill
1096 %emacs}, or disconnecting a phone line or network connection.
1098 @findex do-auto-save
1099 You can perform an auto-save explicitly with the command @kbd{M-x
1103 @subsection Recovering Data from Auto-Saves
1105 @findex recover-file
1106 You can use the contents of an auto-save file to recover from a loss
1107 of data with the command @kbd{M-x recover-file @key{RET} @var{file}
1108 @key{RET}}. This visits @var{file} and then (after your confirmation)
1109 restores the contents from its auto-save file @file{#@var{file}#}.
1110 You can then save with @kbd{C-x C-s} to put the recovered text into
1111 @var{file} itself. For example, to recover file @file{foo.c} from its
1112 auto-save file @file{#foo.c#}, do:
1115 M-x recover-file @key{RET} foo.c @key{RET}
1120 Before asking for confirmation, @kbd{M-x recover-file} displays a
1121 directory listing describing the specified file and the auto-save file,
1122 so you can compare their sizes and dates. If the auto-save file
1123 is older, @kbd{M-x recover-file} does not offer to read it.
1125 @findex recover-session
1126 If Emacs or the computer crashes, you can recover all the files you
1127 were editing from their auto save files with the command @kbd{M-x
1128 recover-session}. This first shows you a list of recorded interrupted
1129 sessions. Move point to the one you choose, and type @kbd{C-c C-c}.
1131 Then @code{recover-session} asks about each of the files that were
1132 being edited during that session, asking whether to recover that file.
1133 If you answer @kbd{y}, it calls @code{recover-file}, which works in its
1134 normal fashion. It shows the dates of the original file and its
1135 auto-save file, and asks once again whether to recover that file.
1137 When @code{recover-session} is done, the files you've chosen to
1138 recover are present in Emacs buffers. You should then save them. Only
1139 this---saving them---updates the files themselves.
1141 @vindex auto-save-list-file-prefix
1142 Emacs records information about interrupted sessions in files named
1143 @file{.saves-@var{pid}-@var{hostname}} in the directory
1144 @file{~/.emacs.d/auto-save-list/}. This directory is determined by
1145 the variable @code{auto-save-list-file-prefix}. If you set
1146 @code{auto-save-list-file-prefix} to @code{nil}, sessions are not
1147 recorded for recovery.
1150 @section File Name Aliases
1151 @cindex symbolic links (visiting)
1152 @cindex hard links (visiting)
1154 Symbolic links and hard links both make it possible for several file
1155 names to refer to the same file. Hard links are alternate names that
1156 refer directly to the file; all the names are equally valid, and no one
1157 of them is preferred. By contrast, a symbolic link is a kind of defined
1158 alias: when @file{foo} is a symbolic link to @file{bar}, you can use
1159 either name to refer to the file, but @file{bar} is the real name, while
1160 @file{foo} is just an alias. More complex cases occur when symbolic
1161 links point to directories.
1163 @vindex find-file-existing-other-name
1164 @vindex find-file-suppress-same-file-warnings
1165 Normally, if you visit a file which Emacs is already visiting under
1166 a different name, Emacs displays a message in the echo area and uses
1167 the existing buffer visiting that file. This can happen on systems
1168 that support hard or symbolic links, or if you use a long file name on
1169 a system that truncates long file names, or on a case-insensitive file
1170 system. You can suppress the message by setting the variable
1171 @code{find-file-suppress-same-file-warnings} to a non-@code{nil}
1172 value. You can disable this feature entirely by setting the variable
1173 @code{find-file-existing-other-name} to @code{nil}: then if you visit
1174 the same file under two different names, you get a separate buffer for
1177 @vindex find-file-visit-truename
1178 @cindex truenames of files
1179 @cindex file truenames
1180 If the variable @code{find-file-visit-truename} is non-@code{nil},
1181 then the file name recorded for a buffer is the file's @dfn{truename}
1182 (made by replacing all symbolic links with their target names), rather
1183 than the name you specify. Setting @code{find-file-visit-truename} also
1184 implies the effect of @code{find-file-existing-other-name}.
1186 @cindex directory name abbreviation
1187 @vindex directory-abbrev-alist
1188 Sometimes, a directory is ordinarily accessed through a symbolic
1189 link, and you may want Emacs to preferentially show its linked
1190 name. To do this, customize @code{directory-abbrev-alist}. Each
1191 element in this list should have the form @code{(@var{from}
1192 . @var{to})}, which means to replace @var{from} with @var{to} whenever
1193 @var{from} appears in a directory name. The @var{from} string is a
1194 regular expression (@pxref{Regexps}). It is matched against directory
1195 names anchored at the first character, and should start with @samp{\`}
1196 (to support directory names with embedded newlines, which would defeat
1197 @samp{^}). The @var{to} string should be an ordinary absolute
1198 directory name pointing to the same directory. Do not use @samp{~} to
1199 stand for a home directory in the @var{to} string; Emacs performs
1200 these substitutions separately. Here's an example, from a system on
1201 which @file{/home/fsf} is normally accessed through a symbolic link
1205 (("\\`/home/fsf" . "/fsf"))
1209 @section File Directories
1211 @cindex file directory
1212 @cindex directory listing
1213 The file system groups files into @dfn{directories}. A @dfn{directory
1214 listing} is a list of all the files in a directory. Emacs provides
1215 commands to create and delete directories, and to make directory
1216 listings in brief format (file names only) and verbose format (sizes,
1217 dates, and authors included). Emacs also includes a directory browser
1218 feature called Dired; see @ref{Dired}.
1221 @item C-x C-d @var{dir-or-pattern} @key{RET}
1222 Display a brief directory listing (@code{list-directory}).
1223 @item C-u C-x C-d @var{dir-or-pattern} @key{RET}
1224 Display a verbose directory listing.
1225 @item M-x make-directory @key{RET} @var{dirname} @key{RET}
1226 Create a new directory named @var{dirname}.
1227 @item M-x delete-directory @key{RET} @var{dirname} @key{RET}
1228 Delete the directory named @var{dirname}. If it isn't empty,
1229 you will be asked whether you want to delete it recursively.
1232 @findex list-directory
1234 The command to display a directory listing is @kbd{C-x C-d}
1235 (@code{list-directory}). It reads using the minibuffer a file name
1236 which is either a directory to be listed or a wildcard-containing
1237 pattern for the files to be listed. For example,
1240 C-x C-d /u2/emacs/etc @key{RET}
1244 lists all the files in directory @file{/u2/emacs/etc}. Here is an
1245 example of specifying a file name pattern:
1248 C-x C-d /u2/emacs/src/*.c @key{RET}
1251 Normally, @kbd{C-x C-d} displays a brief directory listing containing
1252 just file names. A numeric argument (regardless of value) tells it to
1253 make a verbose listing including sizes, dates, and owners (like
1256 @vindex list-directory-brief-switches
1257 @vindex list-directory-verbose-switches
1258 The text of a directory listing is mostly obtained by running
1259 @code{ls} in an inferior process. Two Emacs variables control the
1260 switches passed to @code{ls}: @code{list-directory-brief-switches} is
1261 a string giving the switches to use in brief listings (@code{"-CF"} by
1262 default), and @code{list-directory-verbose-switches} is a string
1263 giving the switches to use in a verbose listing (@code{"-l"} by
1266 @vindex directory-free-space-program
1267 @vindex directory-free-space-args
1268 In verbose directory listings, Emacs adds information about the
1269 amount of free space on the disk that contains the directory. To do
1270 this, it runs the program specified by
1271 @code{directory-free-space-program} with arguments
1272 @code{directory-free-space-args}.
1274 The command @kbd{M-x delete-directory} prompts for a directory name
1275 using the minibuffer, and deletes the directory if it is empty. If
1276 the directory is not empty, you will be asked whether you want to
1277 delete it recursively. On systems that have a ``Trash'' (or ``Recycle
1278 Bin'') feature, you can make this command move the specified directory
1279 to the Trash instead of deleting it outright, by changing the variable
1280 @code{delete-by-moving-to-trash} to @code{t}. @xref{Misc File Ops},
1281 for more information about using the Trash.
1283 @node Comparing Files
1284 @section Comparing Files
1285 @cindex comparing files
1288 @vindex diff-switches
1289 The command @kbd{M-x diff} prompts for two file names, using the
1290 minibuffer, and displays the differences between the two files in a
1291 buffer named @file{*diff*}. This works by running the @command{diff}
1292 program, using options taken from the variable @code{diff-switches}.
1293 The value of @code{diff-switches} should be a string; the default is
1294 @code{"-u"} to specify a unified context diff.
1295 @c Note that the actual name of the info file is diffutils.info,
1296 @c but it adds a dir entry for diff too.
1297 @c On older systems, only "info diff" works, not "info diffutils".
1298 @xref{Top,, Diff, diffutils, Comparing and Merging Files}, for more
1299 information about the @command{diff} program.
1301 The output of the @code{diff} command is shown using a major mode
1302 called Diff mode. @xref{Diff Mode}.
1305 The command @kbd{M-x diff-backup} compares a specified file with its
1306 most recent backup. If you specify the name of a backup file,
1307 @code{diff-backup} compares it with the source file that it is a
1308 backup of. In all other respects, this behaves like @kbd{M-x diff}.
1310 @findex diff-buffer-with-file
1311 The command @kbd{M-x diff-buffer-with-file} compares a specified
1312 buffer with its corresponding file. This shows you what changes you
1313 would make to the file if you save the buffer.
1315 @findex compare-windows
1316 The command @kbd{M-x compare-windows} compares the text in the
1317 current window with that in the window that was the selected window
1318 before you selected the current one. (For more information about
1319 windows in Emacs, @ref{Windows}.) Comparison starts at point in each
1320 window, after pushing each initial point value on the mark ring in its
1321 respective buffer. Then it moves point forward in each window, one
1322 character at a time, until it reaches characters that don't match.
1323 Then the command exits.
1325 If point in the two windows is followed by non-matching text when
1326 the command starts, @kbd{M-x compare-windows} tries heuristically to
1327 advance up to matching text in the two windows, and then exits. So if
1328 you use @kbd{M-x compare-windows} repeatedly, each time it either
1329 skips one matching range or finds the start of another.
1331 @vindex compare-ignore-case
1332 @vindex compare-ignore-whitespace
1333 With a numeric argument, @code{compare-windows} ignores changes in
1334 whitespace. If the variable @code{compare-ignore-case} is
1335 non-@code{nil}, the comparison ignores differences in case as well.
1336 If the variable @code{compare-ignore-whitespace} is non-@code{nil},
1337 @code{compare-windows} normally ignores changes in whitespace, and a
1338 prefix argument turns that off.
1342 @cindex failed merges
1343 @cindex merges, failed
1344 @cindex comparing 3 files (@code{diff3})
1345 You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor
1346 mode for editing output from the @command{diff3} program. This is
1347 typically the result of a failed merge from a version control system
1348 update outside VC, due to conflicting changes to a file. Smerge
1349 mode provides commands to resolve conflicts by selecting specific
1353 @xref{Emerge,,, emacs-xtra, Specialized Emacs Features},
1358 for the Emerge facility, which provides a powerful interface for
1365 @cindex patches, editing
1367 Diff mode is a major mode used for the output of @kbd{M-x diff} and
1368 other similar commands. This kind of output is called a @dfn{patch},
1369 because it can be passed to the @command{patch} command to
1370 automatically apply the specified changes. To select Diff mode
1371 manually, type @kbd{M-x diff-mode}.
1374 The changes specified in a patch are grouped into @dfn{hunks}, which
1375 are contiguous chunks of text that contain one or more changed lines.
1376 Hunks can also include unchanged lines to provide context for the
1377 changes. Each hunk is preceded by a @dfn{hunk header}, which
1378 specifies the old and new line numbers at which the hunk occurs. Diff
1379 mode highlights each hunk header, to distinguish it from the actual
1380 contents of the hunk.
1382 @vindex diff-update-on-the-fly
1383 You can edit a Diff mode buffer like any other buffer. (If it is
1384 read-only, you need to make it writable first. @xref{Misc Buffer}.)
1385 Whenever you change a hunk, Diff mode attempts to automatically
1386 correct the line numbers in the hunk headers, to ensure that the patch
1387 remains correct. To disable automatic line number correction,
1388 change the variable @code{diff-update-on-the-fly} to @code{nil}.
1390 Diff mode treats each hunk as an error message, similar to
1391 Compilation mode. Thus, you can use commands such as @kbd{C-x `} to
1392 visit the corresponding source locations. @xref{Compilation Mode}.
1394 In addition, Diff mode provides the following commands to navigate,
1395 manipulate and apply parts of patches:
1399 @findex diff-hunk-next
1400 Move to the next hunk-start (@code{diff-hunk-next}).
1402 @findex diff-auto-refine-mode
1403 @cindex mode, Diff Auto-Refine
1404 @cindex Diff Auto-Refine mode
1405 This command has a side effect: it @dfn{refines} the hunk you move to,
1406 highlighting its changes with better granularity. To disable this
1407 feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor
1408 mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by
1409 default, add this to your init file (@pxref{Hooks}):
1412 (add-hook 'diff-mode-hook
1413 (lambda () (diff-auto-refine-mode -1)))
1417 @findex diff-hunk-prev
1418 Move to the previous hunk-start (@code{diff-hunk-prev}). Like
1419 @kbd{M-n}, this has the side-effect of refining the hunk you move to,
1420 unless you disable Diff Auto-Refine mode.
1423 @findex diff-file-next
1424 Move to the next file-start, in a multi-file patch
1425 (@code{diff-file-next}).
1428 @findex diff-file-prev
1429 Move to the previous file-start, in a multi-file patch
1430 (@code{diff-file-prev}).
1433 @findex diff-hunk-kill
1434 Kill the hunk at point (@code{diff-hunk-kill}).
1437 @findex diff-file-kill
1438 In a multi-file patch, kill the current file part.
1439 (@code{diff-file-kill}).
1442 @findex diff-apply-hunk
1443 @cindex patches, applying
1444 Apply this hunk to its target file (@code{diff-apply-hunk}). With a
1445 prefix argument of @kbd{C-u}, revert this hunk.
1448 @findex diff-refine-hunk
1449 Highlight the changes of the hunk at point with a finer granularity
1450 (@code{diff-refine-hunk}). This allows you to see exactly which parts
1451 of each changed line were actually changed.
1454 @findex diff-goto-source
1455 Go to the source file and line corresponding to this hunk
1456 (@code{diff-goto-source}).
1459 @findex diff-ediff-patch
1460 Start an Ediff session with the patch (@code{diff-ediff-patch}).
1461 @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
1464 @findex diff-restrict-view
1465 Restrict the view to the current hunk (@code{diff-restrict-view}).
1466 @xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the
1467 view to the current file of a multiple-file patch. To widen again,
1468 use @kbd{C-x n w} (@code{widen}).
1471 @findex diff-reverse-direction
1472 Reverse the direction of comparison for the entire buffer
1473 (@code{diff-reverse-direction}).
1476 @findex diff-split-hunk
1477 Split the hunk at point (@code{diff-split-hunk}). This is for
1478 manually editing patches, and only works with the @dfn{unified diff
1479 format} produced by the @option{-u} or @option{--unified} options to
1480 the @command{diff} program. If you need to split a hunk in the
1481 @dfn{context diff format} produced by the @option{-c} or
1482 @option{--context} options to @command{diff}, first convert the buffer
1483 to the unified diff format with @kbd{C-c C-u}.
1486 @findex diff-unified->context
1487 Convert the entire buffer to the @dfn{context diff format}
1488 (@code{diff-unified->context}). With a prefix argument, convert only
1489 the text within the region.
1492 @findex diff-context->unified
1493 Convert the entire buffer to unified diff format
1494 (@code{diff-context->unified}). With a prefix argument, convert
1495 unified format to context format. When the mark is active, convert
1496 only the text within the region.
1499 @findex diff-ignore-whitespace-hunk
1500 Re-diff the current hunk, disregarding changes in whitespace
1501 (@code{diff-ignore-whitespace-hunk}).
1504 @findex diff-add-change-log-entries-other-window
1505 @findex add-change-log-entry-other-window@r{, in Diff mode}
1506 Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change
1507 Log}), for each one of the hunks
1508 (@code{diff-add-change-log-entries-other-window}). This creates a
1509 skeleton of the log of changes that you can later fill with the actual
1510 descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode
1511 operates on behalf of the current hunk's file, but gets the function
1512 name from the patch itself. This is useful for making log entries for
1513 functions that are deleted by the patch.
1516 @c Trailing whitespace is NOT shown by default.
1517 @c Emacs's dir-locals file enables this (for some reason).
1518 @cindex trailing whitespace, in patches
1519 @findex diff-delete-trailing-whitespace
1520 Patches sometimes include trailing whitespace on modified lines, as
1521 an unintentional and undesired change. There are two ways to deal
1522 with this problem. Firstly, if you enable Whitespace mode in a Diff
1523 buffer (@pxref{Useless Whitespace}), it automatically highlights
1524 trailing whitespace in modified lines. Secondly, you can use the
1525 command @kbd{M-x diff-delete-trailing-whitespace}, which searches for
1526 trailing whitespace in the lines modified by the patch, and removes
1527 that whitespace in both the patch and the patched source file(s).
1528 This command does not save the modifications that it makes, so you can
1529 decide whether to save the changes (the list of modified files is
1530 displayed in the echo area). With a prefix argument, it tries to
1531 modify the original source files rather than the patched source files.
1534 @section Miscellaneous File Operations
1536 Emacs has commands for performing many other operations on files.
1537 All operate on one file; they do not accept wildcard file names.
1540 @cindex deletion (of files)
1541 @kbd{M-x delete-file} prompts for a file and deletes it. If you are
1542 deleting many files in one directory, it may be more convenient to use
1543 Dired rather than @code{delete-file}. @xref{Dired Deletion}.
1547 @kbd{M-x move-file-to-trash} moves a file into the system
1548 @dfn{Trash} (or @dfn{Recycle Bin}). This is a facility available on
1549 most operating systems; files that are moved into the Trash can be
1550 brought back later if you change your mind.
1552 @vindex delete-by-moving-to-trash
1553 By default, Emacs deletion commands do @emph{not} use the Trash. To
1554 use the Trash (when it is available) for common deletion commands,
1555 change the variable @code{delete-by-moving-to-trash} to @code{t}.
1556 This affects the commands @kbd{M-x delete-file} and @kbd{M-x
1557 delete-directory} (@pxref{Directories}), as well as the deletion
1558 commands in Dired (@pxref{Dired Deletion}). Supplying a prefix
1559 argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes
1560 them delete outright, instead of using the Trash, regardless of
1561 @code{delete-by-moving-to-trash}.
1564 If a file is under version control (@pxref{Version Control}), you
1565 should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x
1566 delete-file}. @xref{VC Delete/Rename}.
1570 @cindex copying files
1571 @kbd{M-x copy-file} copies the contents of the file @var{old} to the
1574 @findex copy-directory
1575 @kbd{M-x copy-directory} copies directories, similar to the
1576 @command{cp -r} shell command. It prompts for a directory @var{old}
1577 and a destination @var{new}. If @var{new} is an existing directory,
1578 it creates a copy of the @var{old} directory and puts it in @var{new}.
1579 If @var{new} is not an existing directory, it copies all the contents
1580 of @var{old} into a new directory named @var{new}.
1582 @cindex renaming files
1584 @kbd{M-x rename-file} reads two file names @var{old} and @var{new}
1585 using the minibuffer, then renames file @var{old} as @var{new}. If
1586 the file name @var{new} already exists, you must confirm with
1587 @kbd{yes} or renaming is not done; this is because renaming causes the
1588 old meaning of the name @var{new} to be lost. If @var{old} and
1589 @var{new} are on different file systems, the file @var{old} is copied
1590 and deleted. If the argument @var{new} is just a directory name, the
1591 real new name is in that directory, with the same non-directory
1592 component as @var{old}. For example, @kbd{M-x rename-file @key{RET}
1593 ~/foo @key{RET} /tmp @key{RET}} renames @file{~/foo} to
1594 @file{/tmp/foo}. The same rule applies to all the remaining commands
1595 in this section. All of them ask for confirmation when the new file
1596 name already exists, too.
1599 If a file is under version control (@pxref{Version Control}), you
1600 should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x
1601 rename-file}. @xref{VC Delete/Rename}.
1604 @findex add-name-to-file
1605 @cindex hard links (creation)
1606 @kbd{M-x add-name-to-file} adds an additional name to an existing
1607 file without removing its old name. The new name is created as a
1608 hard link to the existing file. The new name must belong on the
1609 same file system that the file is on. On MS-Windows, this command
1610 works only if the file resides in an NTFS file system. On MS-DOS, it
1611 works by copying the file.
1613 @findex make-symbolic-link
1614 @cindex symbolic links (creation)
1615 @kbd{M-x make-symbolic-link} reads two file names @var{target} and
1616 @var{linkname}, then creates a symbolic link named @var{linkname},
1617 which points at @var{target}. The effect is that future attempts to
1618 open file @var{linkname} will refer to whatever file is named
1619 @var{target} at the time the opening is done, or will get an error if
1620 the name @var{target} is nonexistent at that time. This command does
1621 not expand the argument @var{target}, so that it allows you to specify
1622 a relative name as the target of the link. On MS-Windows, this
1623 command works only on MS Windows Vista and later.
1627 @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
1628 contents of the specified file into the current buffer at point,
1629 leaving point unchanged before the contents. The position after the
1630 inserted contents is added to the mark ring, without activating the
1631 mark (@pxref{Mark Ring}).
1633 @findex insert-file-literally
1634 @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
1635 except the file is inserted literally: it is treated as a sequence
1636 of @acronym{ASCII} characters with no special encoding or conversion,
1637 similar to the @kbd{M-x find-file-literally} command
1640 @findex write-region
1641 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
1642 copies the contents of the region into the specified file. @kbd{M-x
1643 append-to-file} adds the text of the region to the end of the
1644 specified file. @xref{Accumulating Text}. The variable
1645 @code{write-region-inhibit-fsync} applies to these commands, as well
1646 as saving files; see @ref{Customize Save}.
1648 @findex set-file-modes
1650 @cindex file permissions
1651 @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file
1652 mode}, and applies that file mode to the specified file. File modes,
1653 also called @dfn{file permissions}, determine whether a file can be
1654 read, written to, or executed, and by whom. This command reads file
1655 modes using the same symbolic or octal format accepted by the
1656 @command{chmod} command; for instance, @samp{u+x} means to add
1657 execution permission for the user who owns the file. It has no effect
1658 on operating systems that do not support file modes. @code{chmod} is a
1659 convenience alias for this function.
1661 @node Compressed Files
1662 @section Accessing Compressed Files
1664 @cindex uncompression
1665 @cindex Auto Compression mode
1666 @cindex mode, Auto Compression
1669 Emacs automatically uncompresses compressed files when you visit
1670 them, and automatically recompresses them if you alter them and save
1671 them. Emacs recognizes compressed files by their file names. File
1672 names ending in @samp{.gz} indicate a file compressed with
1673 @code{gzip}. Other endings indicate other compression programs.
1675 Automatic uncompression and compression apply to all the operations in
1676 which Emacs uses the contents of a file. This includes visiting it,
1677 saving it, inserting its contents into a buffer, loading it, and byte
1680 @findex auto-compression-mode
1681 @vindex auto-compression-mode
1682 To disable this feature, type the command @kbd{M-x
1683 auto-compression-mode}. You can disable it permanently by
1684 customizing the variable @code{auto-compression-mode}.
1687 @section File Archives
1690 @cindex file archives
1692 A file whose name ends in @samp{.tar} is normally an @dfn{archive}
1693 made by the @code{tar} program. Emacs views these files in a special
1694 mode called Tar mode which provides a Dired-like list of the contents
1695 (@pxref{Dired}). You can move around through the list just as you
1696 would in Dired, and visit the subfiles contained in the archive.
1697 However, not all Dired commands are available in Tar mode.
1699 If Auto Compression mode is enabled (@pxref{Compressed Files}), then
1700 Tar mode is used also for compressed archives---files with extensions
1701 @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}.
1703 The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file
1704 into its own buffer. You can edit it there, and if you save the
1705 buffer, the edited version will replace the version in the Tar buffer.
1706 Clicking with the mouse on the file name in the Tar buffer does
1707 likewise. @kbd{v} extracts a file into a buffer in View mode
1708 (@pxref{View Mode}). @kbd{o} extracts the file and displays it in
1709 another window, so you could edit the file and operate on the archive
1712 The @kbd{I} key adds a new (regular) file to the archive. The file
1713 is initially empty, but can readily be edited using the commands
1714 above. The command inserts the new file before the current one, so
1715 that using it on the topmost line of the Tar buffer makes the new file
1716 the first one in the archive, and using it at the end of the buffer
1717 makes it the last one.
1719 @kbd{d} marks a file for deletion when you later use @kbd{x}, and
1720 @kbd{u} unmarks a file, as in Dired. @kbd{C} copies a file from the
1721 archive to disk and @kbd{R} renames a file within the archive.
1722 @kbd{g} reverts the buffer from the archive on disk. The keys
1723 @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission bits,
1724 group, and owner, respectively.
1726 Saving the Tar buffer writes a new version of the archive to disk with
1727 the changes you made to the components.
1729 You don't need the @code{tar} program to use Tar mode---Emacs reads
1730 the archives directly. However, accessing compressed archives
1731 requires the appropriate uncompression program.
1733 @cindex Archive mode
1734 @cindex mode, archive
1749 @cindex Java class archives
1750 @cindex unzip archives
1751 A separate but similar Archive mode is used for @code{arc},
1752 @code{jar}, @code{lzh}, @code{zip}, @code{rar}, @code{7z}, and
1753 @code{zoo} archives, as well as @code{exe} files that are
1754 self-extracting executables.
1756 The key bindings of Archive mode are similar to those in Tar mode,
1757 with the addition of the @kbd{m} key which marks a file for subsequent
1758 operations, and @kbd{M-@key{DEL}} which unmarks all the marked files.
1759 Also, the @kbd{a} key toggles the display of detailed file
1760 information, for those archive types where it won't fit in a single
1761 line. Operations such as renaming a subfile, or changing its mode or
1762 owner, are supported only for some of the archive formats.
1764 Unlike Tar mode, Archive mode runs the archiving programs to unpack
1765 and repack archives. However, you don't need these programs to look
1766 at the archive table of contents, only to extract or manipulate the
1767 subfiles in the archive. Details of the program names and their
1768 options can be set in the @samp{Archive} Customize group
1769 (@pxref{Customization Groups}).
1772 @section Remote Files
1776 @cindex remote file access
1777 You can refer to files on other machines using a special file name
1782 /@var{method}:@var{host}:@var{filename}
1783 /@var{method}:@var{user}@@@var{host}:@var{filename}
1784 /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
1789 To carry out this request, Emacs uses a remote-login program such as
1790 @command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}.
1791 You must always specify in the file name which method to use---for
1792 example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP,
1793 whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses
1794 @command{ssh}. When you specify the pseudo method @var{-} in the file
1795 name, Emacs chooses the method as follows:
1799 If the host name starts with @samp{ftp.} (with dot), Emacs uses FTP.
1801 If the user name is @samp{ftp} or @samp{anonymous}, Emacs uses FTP.
1803 If the variable @code{tramp-default-method} is set to @samp{ftp},
1806 If @command{ssh-agent} is running, Emacs uses @command{scp}.
1808 Otherwise, Emacs uses @command{ssh}.
1811 @cindex disabling remote files
1813 You can entirely turn off the remote file name feature by setting the
1814 variable @code{tramp-mode} to @code{nil}. You can turn off the
1815 feature in individual cases by quoting the file name with @samp{/:}
1816 (@pxref{Quoted File Names}).
1819 Remote file access through FTP is handled by the Ange-FTP package, which
1820 is documented in the following. Remote file access through the other
1821 methods is handled by the Tramp package, which has its own manual.
1822 @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}.
1824 @vindex ange-ftp-default-user
1825 @cindex user name for remote file access
1826 When the Ange-FTP package is used, Emacs logs in through FTP using
1827 the name @var{user}, if that is specified in the remote file name. If
1828 @var{user} is unspecified, Emacs logs in using your user name on the
1829 local system; but if you set the variable @code{ange-ftp-default-user}
1830 to a string, that string is used instead. When logging in, Emacs may
1831 also ask for a password.
1833 @cindex backups for remote files
1834 @vindex ange-ftp-make-backup-files
1835 For performance reasons, Emacs does not make backup files for files
1836 accessed via FTP by default. To make it do so, change the variable
1837 @code{ange-ftp-make-backup-files} to a non-@code{nil} value.
1839 By default, auto-save files for remote files are made in the
1840 temporary file directory on the local machine, as specified by the
1841 variable @code{auto-save-file-name-transforms}. @xref{Auto Save
1844 @cindex anonymous FTP
1845 @vindex ange-ftp-generate-anonymous-password
1846 To visit files accessible by anonymous FTP, you use special user
1847 names @samp{anonymous} or @samp{ftp}. Passwords for these user names
1848 are handled specially. The variable
1849 @code{ange-ftp-generate-anonymous-password} controls what happens: if
1850 the value of this variable is a string, then that string is used as
1851 the password; if non-@code{nil} (the default), then the value of
1852 @code{user-mail-address} is used; if @code{nil}, then Emacs prompts
1853 you for a password as usual (@pxref{Passwords}).
1855 @cindex firewall, and accessing remote files
1856 @cindex gateway, and remote file access with @code{ange-ftp}
1857 @vindex ange-ftp-smart-gateway
1858 @vindex ange-ftp-gateway-host
1859 Sometimes you may be unable to access files on a remote machine
1860 because a @dfn{firewall} in between blocks the connection for security
1861 reasons. If you can log in on a @dfn{gateway} machine from which the
1862 target files @emph{are} accessible, and whose FTP server supports
1863 gatewaying features, you can still use remote file names; all you have
1864 to do is specify the name of the gateway machine by setting the
1865 variable @code{ange-ftp-gateway-host}, and set
1866 @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able
1867 to make remote file names work, but the procedure is complex. You can
1868 read the instructions by typing @kbd{M-x finder-commentary @key{RET}
1869 ange-ftp @key{RET}}.
1871 @node Quoted File Names
1872 @section Quoted File Names
1874 @cindex quoting file names
1875 @cindex file names, quote special characters
1876 You can @dfn{quote} an absolute file name to prevent special
1877 characters and syntax in it from having their special effects.
1878 The way to do this is to add @samp{/:} at the beginning.
1880 For example, you can quote a local file name which appears remote, to
1881 prevent it from being treated as a remote file name. Thus, if you have
1882 a directory named @file{/foo:} and a file named @file{bar} in it, you
1883 can refer to that file in Emacs as @samp{/:/foo:/bar}.
1885 If you want to quote only special characters in the local part of a
1886 remote file name, you can quote just the local part.
1887 @samp{/ssh:baz:/:/foo:/bar} refers to the file @file{bar} of directory
1888 @file{/foo:} on the host @file{baz}.
1890 @samp{/:} can also prevent @samp{~} from being treated as a special
1891 character for a user's home directory. For example, @file{/:/tmp/~hack}
1892 refers to a file whose name is @file{~hack} in directory @file{/tmp}.
1894 Quoting with @samp{/:} is also a way to enter in the minibuffer a
1895 file name that contains @samp{$}. In order for this to work, the
1896 @samp{/:} must be at the beginning of the minibuffer contents. (You
1897 can also double each @samp{$}; see @ref{File Names with $}.)
1899 You can also quote wildcard characters with @samp{/:}, for visiting.
1900 For example, @file{/:/tmp/foo*bar} visits the file
1901 @file{/tmp/foo*bar}.
1903 Another method of getting the same result is to enter
1904 @file{/tmp/foo[*]bar}, which is a wildcard specification that matches
1905 only @file{/tmp/foo*bar}. However, in many cases there is no need to
1906 quote the wildcard characters because even unquoted they give the
1907 right result. For example, if the only file name in @file{/tmp} that
1908 starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar},
1909 then specifying @file{/tmp/foo*bar} will visit only
1910 @file{/tmp/foo*bar}.
1912 @node File Name Cache
1913 @section File Name Cache
1915 @cindex file name caching
1916 @cindex cache of file names
1919 @findex file-cache-minibuffer-complete
1920 You can use the @dfn{file name cache} to make it easy to locate a
1921 file by name, without having to remember exactly where it is located.
1922 When typing a file name in the minibuffer, @kbd{C-@key{TAB}}
1923 (@code{file-cache-minibuffer-complete}) completes it using the file
1924 name cache. If you repeat @kbd{C-@key{TAB}}, that cycles through the
1925 possible completions of what you had originally typed. (However, note
1926 that the @kbd{C-@key{TAB}} character cannot be typed on most text
1929 The file name cache does not fill up automatically. Instead, you
1930 load file names into the cache using these commands:
1932 @findex file-cache-add-directory
1934 @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET}
1935 Add each file name in @var{directory} to the file name cache.
1936 @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET}
1937 Add each file name in @var{directory} and all of its nested
1938 subdirectories to the file name cache.
1939 @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET}
1940 Add each file name in @var{directory} and all of its nested
1941 subdirectories to the file name cache, using @command{locate} to find
1943 @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET}
1944 Add each file name in each directory listed in @var{variable} to the
1945 file name cache. @var{variable} should be a Lisp variable whose value
1946 is a list of directory names, like @code{load-path}.
1947 @item M-x file-cache-clear-cache @key{RET}
1948 Clear the cache; that is, remove all file names from it.
1951 The file name cache is not persistent: it is kept and maintained
1952 only for the duration of the Emacs session. You can view the contents
1953 of the cache with the @code{file-cache-display} command.
1955 @node File Conveniences
1956 @section Convenience Features for Finding Files
1958 In this section, we introduce some convenient facilities for finding
1959 recently-opened files, reading file names from a buffer, and viewing
1962 @findex recentf-mode
1963 @vindex recentf-mode
1964 @findex recentf-save-list
1965 @findex recentf-edit-list
1966 If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
1967 @samp{File} menu includes a submenu containing a list of recently
1968 opened files. @kbd{M-x recentf-save-list} saves the current
1969 @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list}
1972 @c FIXME partial-completion-mode (complete.el) is obsolete.
1973 The @kbd{M-x ffap} command generalizes @code{find-file} with more
1974 powerful heuristic defaults (@pxref{FFAP}), often based on the text at
1975 point. Partial Completion mode offers other features extending
1976 @code{find-file}, which can be used with @code{ffap}.
1977 @xref{Completion Options}.
1980 @findex image-toggle-display
1981 @findex image-next-file
1982 @findex image-previous-file
1983 @cindex images, viewing
1984 Visiting image files automatically selects Image mode. In this
1985 major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display})
1986 to toggle between displaying the file as an image in the Emacs buffer,
1987 and displaying its underlying text (or raw byte) representation.
1988 Additionally you can type @kbd{C-c C-x} (@code{image-toggle-hex-display})
1989 to toggle between displaying the file as an image in the Emacs buffer,
1990 and displaying it in hex representation.
1991 Displaying the file as an image works only if Emacs is compiled with
1992 support for displaying such images. If the displayed image is wider
1993 or taller than the frame, the usual point motion keys (@kbd{C-f},
1994 @kbd{C-p}, and so forth) cause different parts of the image to be
1995 displayed. You can press @kbd{n} (@code{image-next-file}) and @kbd{p}
1996 (@code{image-previous-file}) to visit the next image file and the
1997 previous image file in the same directory, respectively.
1999 @findex image-toggle-animation
2000 @findex image-next-frame
2001 @findex image-previous-frame
2002 @findex image-goto-frame
2003 @findex image-increase-speed
2004 @findex image-decrease-speed
2005 @findex image-reset-speed
2006 @findex image-reverse-speed
2007 @vindex image-animate-loop
2008 @cindex image animation
2009 @cindex animated images
2010 If the image can be animated, the command @key{RET}
2011 (@code{image-toggle-animation}) starts or stops the animation.
2012 Animation plays once, unless the option @code{image-animate-loop} is
2013 non-@code{nil}. With @kbd{f} (@code{image-next-frame}) and @kbd{b}
2014 (@code{image-previous-frame}) you can step through the individual
2015 frames. Both commands accept a numeric prefix to step through several
2016 frames at once. You can go to a specific frame with @kbd{F}
2017 (@code{image-goto-frame}). Frames are indexed from 1. Typing @kbd{a
2018 +} (@code{image-increase-speed}) increases the speed of the animation,
2019 @kbd{a -} (@code{image-decrease-speed}) decreases it, and @kbd{a r}
2020 (@code{image-reverse-speed}) reverses it. The command @kbd{a 0}
2021 (@code{image-reset-speed}) resets the speed to the original value.
2023 @cindex ImageMagick support
2024 @vindex imagemagick-enabled-types
2025 @vindex imagemagick-types-inhibit
2026 If Emacs was compiled with support for the ImageMagick library, it
2027 can use ImageMagick to render a wide variety of images. The variable
2028 @code{imagemagick-enabled-types} lists the image types that Emacs may
2029 render using ImageMagick; each element in the list should be an
2030 internal ImageMagick name for an image type, as a symbol or an
2031 equivalent string (e.g., @code{BMP} for @file{.bmp} images). To
2032 enable ImageMagick for all possible image types, change
2033 @code{imagemagick-enabled-types} to @code{t}. The variable
2034 @code{imagemagick-types-inhibit} lists the image types which should
2035 never be rendered using ImageMagick, regardless of the value of
2036 @code{imagemagick-enabled-types} (the default list includes types like
2037 @code{C} and @code{HTML}, which ImageMagick can render as an image
2038 but Emacs should not). To disable ImageMagick entirely, change
2039 @code{imagemagick-types-inhibit} to @code{t}.
2042 @findex mode, thumbs
2043 The Image-Dired package can also be used to view images as
2044 thumbnails. @xref{Image-Dired}.
2049 @cindex sets of files
2051 @findex filesets-init
2052 If you regularly edit a certain group of files, you can define them
2053 as a @dfn{fileset}. This lets you perform certain operations, such as
2054 visiting, @code{query-replace}, and shell commands on all the files at
2055 once. To make use of filesets, you must first add the expression
2056 @code{(filesets-init)} to your init file (@pxref{Init File}). This
2057 adds a @samp{Filesets} menu to the menu bar.
2059 @findex filesets-add-buffer
2060 @findex filesets-remove-buffer
2061 The simplest way to define a fileset is by adding files to it one at
2062 a time. To add a file to fileset @var{name}, visit the file and type
2063 @kbd{M-x filesets-add-buffer @key{RET} @var{name} @key{RET}}. If
2064 there is no fileset @var{name}, this creates a new one, which
2065 initially contains only the current file. The command @kbd{M-x
2066 filesets-remove-buffer} removes the current file from a fileset.
2068 You can also edit the list of filesets directly, with @kbd{M-x
2069 filesets-edit} (or by choosing @samp{Edit Filesets} from the
2070 @samp{Filesets} menu). The editing is performed in a Customize buffer
2071 (@pxref{Easy Customization}). Normally, a fileset is a simple list of
2072 files, but you can also define a fileset as a regular expression
2073 matching file names. Some examples of these more complicated filesets
2074 are shown in the Customize buffer. Remember to select @samp{Save for
2075 future sessions} if you want to use the same filesets in future Emacs
2078 You can use the command @kbd{M-x filesets-open} to visit all the
2079 files in a fileset, and @kbd{M-x filesets-close} to close them. Use
2080 @kbd{M-x filesets-run-cmd} to run a shell command on all the files in
2081 a fileset. These commands are also available from the @samp{Filesets}
2082 menu, where each existing fileset is represented by a submenu.
2084 @xref{Version Control}, for a different concept of filesets:
2085 groups of files bundled together for version control operations.
2086 Filesets of that type are unnamed, and do not persist across Emacs