0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @node Files
0006: @chapter File Handling
0007: @cindex files
0008: 
0009:   The operating system stores data permanently in named @dfn{files}, so
0010: most of the text you edit with Emacs comes from a file and is ultimately
0011: stored in a file.
0012: 
0013:   To edit a file, you must tell Emacs to read the file and prepare a
0014: buffer containing a copy of the file's text.  This is called
0015: @dfn{visiting} the file.  Editing commands apply directly to text in the
0016: buffer; that is, to the copy inside Emacs.  Your changes appear in the
0017: file itself only when you @dfn{save} the buffer back into the file.
0018: 
0019:   In addition to visiting and saving files, Emacs can delete, copy,
0020: rename, and append to files, keep multiple versions of them, and operate
0021: on file directories.
0022: 
0023: @menu
0024: * File Names::          How to type and edit file-name arguments.
0025: * Visiting::            Visiting a file prepares Emacs to edit the file.
0026: * Saving::              Saving makes your changes permanent.
0027: * Reverting::           Reverting cancels all the changes not saved.
0028: @ifnottex
0029: * Autorevert::          Auto Reverting non-file buffers.
0030: @end ifnottex
0031: * Auto Save::           Auto Save periodically protects against loss of data.
0032: * File Aliases::        Handling multiple names for one file.
0033: * Directories::         Creating, deleting, and listing file directories.
0034: * Comparing Files::     Finding where two files differ.
0035: * Diff Mode::           Mode for editing file differences.
0036: * Copying and Naming::  Copying, naming and renaming files.
0037: * Misc File Ops::       Other things you can do on files.
0038: * Compressed Files::    Accessing compressed files.
0039: * File Archives::       Operating on tar, zip, jar etc. archive files.
0040: * Remote Files::        Accessing files on other machines.
0041: * Quoted File Names::   Quoting special characters in file names.
0042: * File Name Cache::     Completion against a list of files you often use.
0043: * File Conveniences::   Convenience Features for Finding Files.
0044: * Filesets::            Handling sets of files.
0045: @end menu
0046: 
0047: @node File Names
0048: @section File Names
0049: @cindex file names
0050: 
0051: @cindex default file name
0052:   Many Emacs commands that operate on a file require you to specify
0053: the file name, using the minibuffer (@pxref{Minibuffer File}).
0054: 
0055:   While in the minibuffer, you can use the usual completion and
0056: history commands (@pxref{Minibuffer}).  Note that file name completion
0057: ignores file names whose extensions appear in the variable
0058: @code{completion-ignored-extensions} (@pxref{Completion Options}).
0059: Note also that most commands use permissive completion with
0060: confirmation for reading file names: you are allowed to submit a
0061: nonexistent file name, but if you type @key{RET} immediately after
0062: completing up to a nonexistent file name, Emacs prints
0063: @samp{[Confirm]} and you must type a second @key{RET} to confirm.
0064: @xref{Completion Exit}, for details.
0065: 
0066: Minibuffer history commands offer some special features for reading
0067: file names, see @ref{Minibuffer History}.
0068: 
0069: @cindex default directory, of a buffer
0070: @vindex default-directory
0071:   Each buffer has a @dfn{default directory}, stored in the
0072: buffer-local variable @code{default-directory}.  Whenever Emacs reads
0073: a file name using the minibuffer, it usually inserts the default
0074: directory into the minibuffer as the initial contents.  You can
0075: inhibit this insertion by changing the variable
0076: @code{insert-default-directory} to @code{nil} (@pxref{Minibuffer
0077: File}).  Regardless, Emacs always assumes that any relative file name
0078: is relative to the default directory, e.g., entering a file name
0079: without a directory specifies a file in the default directory.
0080: 
0081: @findex cd
0082: @findex pwd
0083:   When you visit a file, Emacs sets @code{default-directory} in the
0084: visiting buffer to the directory of its file.  When you create a new
0085: buffer that is not visiting a file, via a command like @kbd{C-x b},
0086: its default directory is usually copied from the buffer that was
0087: current at the time (@pxref{Select Buffer}).  You can use the command
0088: @kbd{M-x pwd} to see the value of @code{default-directory} in the
0089: current buffer.  The command @kbd{M-x cd} prompts for a directory's
0090: name, and sets the buffer's @code{default-directory} to that directory
0091: (doing this does not change the buffer's file name, if any).
0092: 
0093:   As an example, when you visit the file @file{/u/rms/gnu/gnu.tasks},
0094: the default directory is set to @file{/u/rms/gnu/}.  If you invoke a
0095: command that reads a file name, entering just @samp{foo} in the
0096: minibuffer, with a directory omitted, specifies the file
0097: @file{/u/rms/gnu/foo}; entering @samp{../.login} specifies
0098: @file{/u/rms/.login}; and entering @samp{new/foo} specifies
0099: @file{/u/rms/gnu/new/foo}.
0100: 
0101:   When typing a file name into the minibuffer, you can make use of a
0102: couple of shortcuts: a double slash ignores everything before the
0103: second slash in the pair, and @samp{~/} is your home directory.
0104: @xref{Minibuffer File}.
0105: 
0106: @cindex environment variables in file names
0107: @cindex expansion of environment variables
0108: @cindex @code{$} in file names
0109:   @anchor{File Names with $}The character @samp{$} is used to
0110: substitute an environment variable into a file name.  The name of the
0111: environment variable consists of all the alphanumeric characters after
0112: the @samp{$}; alternatively, it can be enclosed in braces after the
0113: @samp{$}.  For example, if you have used the shell command
0114: @command{export FOO=rms/hacks} to set up an environment variable named
0115: @env{FOO}, then both @file{/u/$FOO/test.c} and
0116: @file{/u/$@{FOO@}/test.c} are abbreviations for
0117: @file{/u/rms/hacks/test.c}.  If the environment variable is not
0118: defined, no substitution occurs, so that the character @samp{$} stands
0119: for itself.  Note that environment variables set outside Emacs affect
0120: Emacs only if they are applied before Emacs is started.
0121: 
0122:   To access a file with @samp{$} in its name, if the @samp{$} causes
0123: expansion, type @samp{$$}.  This pair is converted to a single
0124: @samp{$} at the same time that variable substitution is performed for
0125: a single @samp{$}.  Alternatively, quote the whole file name with
0126: @samp{/:} (@pxref{Quoted File Names}).  File names which begin with a
0127: literal @samp{~} should also be quoted with @samp{/:}.
0128: 
0129:   You can include non-@acronym{ASCII} characters in file names.
0130: @xref{File Name Coding}.
0131: 
0132: @node Visiting
0133: @section Visiting Files
0134: @cindex visiting files
0135: @cindex open file
0136: 
0137: @table @kbd
0138: @item C-x C-f
0139: Visit a file (@code{find-file}).
0140: @item C-x C-r
0141: Visit a file for viewing, without allowing changes to it
0142: (@code{find-file-read-only}).
0143: @item C-x C-v
0144: Visit a different file instead of the one visited last
0145: (@code{find-alternate-file}).
0146: @item C-x 4 f
0147: Visit a file, in another window (@code{find-file-other-window}).  Don't
0148: alter what is displayed in the selected window.
0149: @item C-x 5 f
0150: Visit a file, in a new frame (@code{find-file-other-frame}).  Don't
0151: alter what is displayed in the selected frame.
0152: @item M-x find-file-literally
0153: Visit a file with no conversion of the contents.
0154: @end table
0155: 
0156: @cindex files, visiting and saving
0157: @cindex saving files
0158:   @dfn{Visiting} a file means reading its contents into an Emacs
0159: buffer so you can edit them.  Emacs makes a new buffer for each file
0160: that you visit.
0161: 
0162: @kindex C-x C-f
0163: @findex find-file
0164:   To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the
0165: minibuffer to enter the name of the desired file.  While in the
0166: minibuffer, you can abort the command by typing @kbd{C-g}.  @xref{File
0167: Names}, for details about entering file names into minibuffers.
0168: 
0169:   If the specified file exists but the system does not allow you to
0170: read it, an error message is displayed in the echo area (on GNU and
0171: Unix systems you might be able to visit such a file using the
0172: @samp{su} or @samp{sudo} methods; @pxref{Remote Files}).  Otherwise,
0173: you can tell that @kbd{C-x C-f} has completed successfully by the
0174: appearance of new text on the screen, and by the buffer name shown in
0175: the mode line (@pxref{Mode Line}).  Emacs normally constructs the
0176: buffer name from the file name, omitting the directory name.  For
0177: example, a file named @file{/usr/rms/emacs.tex} is visited in a buffer
0178: named @samp{emacs.tex}.  If there is already a buffer with that name,
0179: Emacs constructs a unique name; the normal method is to add a suffix
0180: based on the directory name (e.g., @samp{<rms>}, @samp{<tmp>},
0181: and so on), but you can select other methods.  @xref{Uniquify}.
0182: 
0183: @cindex creating files
0184:   To create a new file, just visit it using the same command, @kbd{C-x
0185: C-f}.  Emacs displays @samp{(New file)} in the echo area, but in other
0186: respects behaves as if you had visited an existing empty file.
0187: 
0188: @cindex modified (buffer)
0189:   After visiting a file, the changes you make with editing commands are
0190: made in the Emacs buffer.  They do not take effect in the visited
0191: file, until you @dfn{save} the buffer (@pxref{Saving}).  If a buffer
0192: contains changes that have not been saved, we say the buffer is
0193: @dfn{modified}.  This implies that some changes will be lost if the
0194: buffer is not saved.  The mode line displays two stars near the left
0195: margin to indicate that the buffer is modified.
0196: 
0197:   If you visit a file that is already in Emacs, @kbd{C-x C-f} switches
0198: to the existing buffer instead of making another copy.  Before doing
0199: so, it checks whether the file has changed since you last visited or
0200: saved it.  If the file has changed, Emacs offers to reread it.
0201: 
0202: @vindex large-file-warning-threshold
0203: @cindex file, warning when size is large
0204: @cindex size of file, warning when visiting
0205: @cindex maximum buffer size exceeded, error message
0206:   If you try to visit a file larger than
0207: @code{large-file-warning-threshold} (the default is 10000000, which is
0208: about 10 megabytes), Emacs asks you for confirmation first.  You can
0209: answer @kbd{y} to proceed with visiting the file or @kbd{l} to visit
0210: the file literally (see below).  Visiting large files literally speeds
0211: up navigation and editing of such files, because various
0212: potentially-expensive features are turned off.  Note, however, that
0213: Emacs cannot visit files that are larger than the maximum Emacs buffer
0214: size, which is limited by the amount of memory Emacs can allocate and
0215: by the integers that Emacs can represent (@pxref{Buffers}).  If you
0216: try, Emacs displays an error message saying that the maximum buffer
0217: size has been exceeded.
0218: 
0219: @cindex wildcard characters in file names
0220: @vindex find-file-wildcards
0221:   If the file name you specify contains shell-style wildcard
0222: characters, Emacs visits all the files that match it.  (On
0223: case-insensitive filesystems, Emacs matches the wildcards disregarding
0224: the letter case.)  Wildcards include @samp{?}, @samp{*}, and
0225: @samp{[@dots{}]} sequences.  To enter the wild card @samp{?} in a file
0226: name in the minibuffer, you need to type @kbd{C-q ?}.  @xref{Quoted
0227: File Names}, for information on how to visit a file whose name
0228: actually contains wildcard characters.  You can disable the wildcard
0229: feature by customizing @code{find-file-wildcards}.
0230: 
0231: @kindex C-x C-v
0232: @findex find-alternate-file
0233:   If you visit the wrong file unintentionally by typing its name
0234: incorrectly, type @kbd{C-x C-v} (@code{find-alternate-file}) to visit
0235: the file you really wanted.  @kbd{C-x C-v} is similar to @kbd{C-x
0236: C-f}, but it kills the current buffer (after first offering to save it
0237: if it is modified).  When @kbd{C-x C-v} reads the file name to visit,
0238: it inserts the entire default file name in the buffer, with point just
0239: after the directory part; this is convenient if you made a slight
0240: error in typing the name.
0241: 
0242: @vindex find-file-run-dired
0243:   If you visit a file that is actually a directory, Emacs invokes
0244: Dired, the Emacs directory browser.  @xref{Dired}.  You can disable
0245: this behavior by setting the variable @code{find-file-run-dired} to
0246: @code{nil}; in that case, it is an error to try to visit a directory.
0247: 
0248:   Files which are actually collections of other files, or @dfn{file
0249: archives}, are visited in special modes which invoke a Dired-like
0250: environment to allow operations on archive members.  @xref{File
0251: Archives}, for more about these features.
0252: 
0253:   If you visit a file that the operating system won't let you modify,
0254: or that is marked read-only, Emacs makes the buffer read-only too, so
0255: that you won't go ahead and make changes that you'll have trouble
0256: saving afterward.  You can make the buffer writable with @kbd{C-x C-q}
0257: (@code{read-only-mode}).  @xref{Misc Buffer}.
0258: 
0259: @kindex C-x C-r
0260: @findex find-file-read-only
0261:   If you want to visit a file as read-only in order to protect
0262: yourself from entering changes accidentally, visit it with the command
0263: @kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}.
0264: 
0265: @kindex C-x 4 f
0266: @findex find-file-other-window
0267:   @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
0268: except that the buffer containing the specified file is selected in another
0269: window.  The window that was selected before @kbd{C-x 4 f} continues to
0270: show the same buffer it was already showing.  If this command is used when
0271: only one window is being displayed, that window is split in two, with one
0272: window showing the same buffer as before, and the other one showing the
0273: newly requested file.  @xref{Windows}.
0274: 
0275: @kindex C-x 5 f
0276: @findex find-file-other-frame
0277:   @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
0278: new frame, or selects any existing frame showing the specified file.
0279: @xref{Frames}.
0280: 
0281: @cindex file selection dialog
0282:   On graphical displays, there are two additional methods for visiting
0283: files.  Firstly, when Emacs is built with a suitable GUI toolkit,
0284: commands invoked with the mouse (by clicking on the menu bar or tool
0285: bar) use the toolkit's standard file selection dialog instead of
0286: prompting for the file name in the minibuffer.  On GNU/Linux and Unix
0287: platforms, Emacs does this when built with GTK+, LessTif, and Motif
0288: toolkits; on MS-Windows and Mac, the GUI version does that by default.
0289: For information on how to customize this, see @ref{Dialog Boxes}.
0290: 
0291:   Secondly, Emacs supports drag and drop: dropping a file into an
0292: ordinary Emacs window visits the file using that window.  As an
0293: exception, dropping a file into a window displaying a Dired buffer
0294: moves or copies the file into the displayed directory.  For details,
0295: see @ref{Drag and Drop}, and @ref{Misc Dired Features}.
0296: 
0297:   On text-mode terminals and on graphical displays when Emacs was
0298: built without a GUI toolkit, you can visit files via the menu-bar
0299: @samp{File} menu, which has the @samp{Visit New File} and the
0300: @samp{Open File} items.
0301: 
0302:   Each time you visit a file, Emacs automatically scans its contents
0303: to detect what character encoding and end-of-line convention it uses,
0304: and converts these to Emacs's internal encoding and end-of-line
0305: convention within the buffer.  When you save the buffer, Emacs
0306: performs the inverse conversion, writing the file to disk with its
0307: original encoding and end-of-line convention.  @xref{Coding Systems}.
0308: 
0309: @findex find-file-literally
0310:   If you wish to edit a file as a sequence of @acronym{ASCII}
0311: characters with no special encoding or conversion, use the @kbd{M-x
0312: find-file-literally} command.  This visits a file, like @kbd{C-x C-f},
0313: but does not do format conversion (@pxref{Format Conversion,, Format
0314: Conversion, elisp, the Emacs Lisp Reference Manual}), character code
0315: conversion (@pxref{Coding Systems}), or automatic uncompression
0316: (@pxref{Compressed Files}), and does not add a final newline because
0317: of @code{require-final-newline} (@pxref{Customize Save}).  If you have
0318: already visited the same file in the usual (non-literal) manner, this
0319: command asks you whether to visit it literally instead.
0320: 
0321: @vindex find-file-hook
0322: @vindex find-file-not-found-functions
0323:   Two special hook variables allow extensions to modify the operation
0324: of visiting files.  Visiting a file that does not exist runs the
0325: functions in @code{find-file-not-found-functions}; this variable holds
0326: a list of functions, which are called one by one (with no arguments)
0327: until one of them returns non-@code{nil}.  This is not a normal hook,
0328: and the name ends in @samp{-functions} rather than @samp{-hook} to
0329: indicate that fact.
0330: 
0331:   Successful visiting of any file, whether existing or not, calls the
0332: functions in @code{find-file-hook}, with no arguments.  This variable
0333: is a normal hook.  In the case of a nonexistent file, the
0334: @code{find-file-not-found-functions} are run first.  @xref{Hooks}.
0335: 
0336:   There are several ways to specify automatically the major mode for
0337: editing the file (@pxref{Choosing Modes}), and to specify local
0338: variables defined for that file (@pxref{File Variables}).
0339: 
0340: @node Saving
0341: @section Saving Files
0342: 
0343:   @dfn{Saving} a buffer in Emacs means writing its contents back into the file
0344: that was visited in the buffer.
0345: 
0346: @menu
0347: * Save Commands::       Commands for saving files.
0348: * Backup::              How Emacs saves the old version of your file.
0349: * Customize Save::      Customizing the saving of files.
0350: * Interlocking::        How Emacs protects against simultaneous editing
0351:                           of one file by two users.
0352: * Shadowing: File Shadowing.  Copying files to ``shadows'' automatically.
0353: * Time Stamps::         Emacs can update time stamps on saved files.
0354: @end menu
0355: 
0356: @node Save Commands
0357: @subsection Commands for Saving Files
0358: 
0359:   These are the commands that relate to saving and writing files.
0360: 
0361: @table @kbd
0362: @item C-x C-s
0363: Save the current buffer to its file (@code{save-buffer}).
0364: @item C-x s
0365: Save any or all buffers to their files (@code{save-some-buffers}).
0366: @item M-~
0367: Forget that the current buffer has been changed (@code{not-modified}).
0368: With prefix argument (@kbd{C-u}), mark the current buffer as changed.
0369: @item C-x C-w
0370: Save the current buffer with a specified file name (@code{write-file}).
0371: @item M-x set-visited-file-name
0372: Change the file name under which the current buffer will be saved.
0373: @end table
0374: 
0375: @kindex C-x C-s
0376: @findex save-buffer
0377:   When you wish to save the file and make your changes permanent, type
0378: @kbd{C-x C-s} (@code{save-buffer}).  After saving is finished, @kbd{C-x C-s}
0379: displays a message like this:
0380: 
0381: @example
0382: Wrote /u/rms/gnu/gnu.tasks
0383: @end example
0384: 
0385: @noindent
0386: If the current buffer is not modified (no changes have been made in it
0387: since the buffer was created or last saved), saving is not really
0388: done, because it would have no effect.  Instead, @kbd{C-x C-s}
0389: displays a message like this in the echo area:
0390: 
0391: @example
0392: (No changes need to be saved)
0393: @end example
0394: 
0395: With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer
0396: to be backed up when the next save is done.  @xref{Backup}.
0397: 
0398: @kindex C-x s
0399: @findex save-some-buffers
0400:   The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
0401: or all modified buffers.  It asks you what to do with each buffer.  The
0402: possible responses are analogous to those of @code{query-replace}:
0403: 
0404: @table @kbd
0405: @item y
0406: @item @key{SPC}
0407: Save this buffer and ask about the rest of the buffers.
0408: @item n
0409: @item @key{DEL}
0410: Don't save this buffer, but ask about the rest of the buffers.
0411: @item !
0412: Save this buffer and all the rest with no more questions.
0413: @item q
0414: @c following generates acceptable underfull hbox
0415: @item @key{RET}
0416: Terminate @code{save-some-buffers} without any more saving.
0417: @item .
0418: Save this buffer, then exit @code{save-some-buffers} without even asking
0419: about other buffers.
0420: @item C-r
0421: View the buffer that you are currently being asked about.  When you exit
0422: View mode, you get back to @code{save-some-buffers}, which asks the
0423: question again.
0424: @item d
0425: Diff the buffer against its corresponding file, so you can see what
0426: changes you would be saving.  This calls the command
0427: @code{diff-buffer-with-file} (@pxref{Comparing Files}).
0428: @item C-h
0429: Display a help message about these options.
0430: @end table
0431: 
0432: @noindent
0433: @vindex save-some-buffers-default-predicate
0434: You can customize the value of
0435: @code{save-some-buffers-default-predicate} to control which buffers
0436: Emacs will ask about.
0437: 
0438:   @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
0439: @code{save-some-buffers} and therefore asks the same questions.
0440: 
0441: @kindex M-~
0442: @findex not-modified
0443:   If you have changed a buffer but do not wish to save the changes,
0444: you should take some action to prevent it.  Otherwise, each time you
0445: use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer
0446: by mistake.  One thing you can do is type @kbd{M-~}
0447: (@code{not-modified}), which clears out the indication that the buffer
0448: is modified.  If you do this, none of the save commands will believe
0449: that the buffer needs to be saved.  (@samp{~} is often used as a
0450: mathematical symbol for ``not''; thus @kbd{M-~} is ``not'', metafied.)
0451: Alternatively, you can cancel all the changes made since the file was
0452: visited or saved, by reading the text from the file again.  This is
0453: called @dfn{reverting}.  @xref{Reverting}.  (You could also undo all
0454: the changes by repeating the undo command @kbd{C-x u} until you have
0455: undone all the changes; but reverting is easier.)
0456: 
0457: @findex set-visited-file-name
0458:   @kbd{M-x set-visited-file-name} alters the name of the file that the
0459: current buffer is visiting.  It reads the new file name using the
0460: minibuffer.  Then it marks the buffer as visiting that file name, and
0461: changes the buffer name correspondingly.  @code{set-visited-file-name}
0462: does not save the buffer in the newly visited file; it just alters the
0463: records inside Emacs in case you do save later.  It also marks the
0464: buffer as modified so that @kbd{C-x C-s} in that buffer
0465: @emph{will} save.
0466: 
0467: @kindex C-x C-w
0468: @findex write-file
0469:   If you wish to mark the buffer as visiting a different file and save
0470: it right away, use @kbd{C-x C-w} (@code{write-file}).  This is
0471: equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s},
0472: except that @kbd{C-x C-w} asks for confirmation if the file exists.
0473: @kbd{C-x C-s} used on a buffer that is not visiting a file has the
0474: same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
0475: buffer as visiting that file, and saves it there.  The default file
0476: name in a buffer that is not visiting a file is made by combining the
0477: buffer name with the buffer's default directory (@pxref{File Names}).
0478: 
0479:   If the new file name implies a major mode, then @kbd{C-x C-w} switches
0480: to that major mode, in most cases.  The command
0481: @code{set-visited-file-name} also does this.  @xref{Choosing Modes}.
0482: 
0483:   If Emacs is about to save a file and sees that the date of the latest
0484: version on disk does not match what Emacs last read or wrote, Emacs
0485: notifies you of this fact, because it probably indicates a problem caused
0486: by simultaneous editing and requires your immediate attention.
0487: @xref{Interlocking,, Simultaneous Editing}.
0488: 
0489: @node Backup
0490: @subsection Backup Files
0491: @cindex backup file
0492: @vindex make-backup-files
0493: 
0494:   On most operating systems, rewriting a file automatically destroys all
0495: record of what the file used to contain.  Thus, saving a file from Emacs
0496: throws away the old contents of the file---or it would, except that
0497: Emacs carefully copies the old contents to another file, called the
0498: @dfn{backup} file, before actually saving.
0499: 
0500:   Emacs makes a backup for a file only the first time the file is
0501: saved from a buffer.  No matter how many times you subsequently save
0502: the file, its backup remains unchanged.  However, if you kill the
0503: buffer and then visit the file again, a new backup file will be made.
0504: 
0505:   For most files, the variable @code{make-backup-files} determines
0506: whether to make backup files.  On most operating systems, its default
0507: value is @code{t}, so that Emacs does write backup files.
0508: 
0509:   For files managed by a version control system (@pxref{Version
0510: Control}), the variable @code{vc-make-backup-files} determines whether
0511: to make backup files.  By default it is @code{nil}, since backup files
0512: are redundant when you store all the previous versions in a version
0513: control system.
0514: @iftex
0515: @xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}.
0516: @end iftex
0517: @ifnottex
0518: @xref{General VC Options}.
0519: @end ifnottex
0520: 
0521:   At your option, Emacs can keep either a single backup for each file,
0522: or make a series of numbered backup files for each file that you edit.
0523: @xref{Backup Names}.
0524: 
0525: @vindex backup-enable-predicate
0526: @vindex temporary-file-directory
0527: @vindex small-temporary-file-directory
0528:   The default value of the @code{backup-enable-predicate} variable
0529: prevents backup files being written for files in the directories used
0530: for temporary files, specified by @code{temporary-file-directory} or
0531: @code{small-temporary-file-directory}.
0532: 
0533:   You can explicitly tell Emacs to make another backup file from a
0534: buffer, even though that buffer has been saved before.  If you save
0535: the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
0536: into a backup file if you save the buffer again.  @kbd{C-u C-u C-x
0537: C-s} saves the buffer, but first makes the previous file contents into
0538: a new backup file.  @kbd{C-u C-u C-u C-x C-s} does both things: it
0539: makes a backup from the previous contents, and arranges to make
0540: another from the newly saved contents if you save again.
0541: 
0542: @vindex backup-directory-alist
0543:   You can customize the variable @code{backup-directory-alist} to
0544: specify that files matching certain patterns should be backed up in
0545: specific directories.  A typical use is to add an element @code{("."
0546: . @var{dir})} to make all backups in the directory with absolute name
0547: @var{dir}.  Emacs modifies the backup file names to avoid clashes
0548: between files with the same names originating in different
0549: directories.  Alternatively, adding, @code{("." . ".~")} would make
0550: backups in the invisible subdirectory @file{.~} of the original file's
0551: directory.  Emacs creates the directory, if necessary, to make the
0552: backup.
0553: 
0554: @menu
0555: * Names: Backup Names.          How backup files are named.
0556: * Deletion: Backup Deletion.    Emacs deletes excess numbered backups.
0557: * Copying: Backup Copying.      Backups can be made by copying or renaming.
0558: @end menu
0559: 
0560: @node Backup Names
0561: @subsubsection Single or Numbered Backups
0562: @cindex backup file names
0563: @cindex names of backup files
0564: 
0565: @cindex @file{~}, in names of backup files
0566: @cindex tilde (@file{~}) at end of backup file name
0567:   When Emacs makes a backup file, its name is normally constructed by
0568: appending @samp{~} to the file name being edited; thus, the backup
0569: file for @file{eval.c} would be @file{eval.c~}.
0570: 
0571: @cindex @file{~/.emacs.d/%backup%~}
0572:   If access control stops Emacs from writing backup files under the
0573: usual names, it writes the backup file as @file{~/.emacs.d/%backup%~}.
0574: Only one such file can exist, so only the most recently made such
0575: backup is available.
0576: 
0577:   Emacs can also make @dfn{numbered backup files}.  Numbered backup
0578: file names contain @samp{.~}, the number, and another @samp{~} after
0579: the original file name.  Thus, the backup files of @file{eval.c} would
0580: be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way
0581: through names like @file{eval.c.~259~} and beyond.
0582: 
0583: @vindex version-control
0584:   The variable @code{version-control} determines whether to make
0585: single backup files or multiple numbered backup files.  Its possible
0586: values are:
0587: 
0588: @table @code
0589: @item nil
0590: Make numbered backups for files that have numbered backups already.
0591: Otherwise, make single backups.  This is the default.
0592: @item t
0593: Make numbered backups.
0594: @item never
0595: Never make numbered backups; always make single backups.
0596: @end table
0597: 
0598: @noindent
0599: The usual way to set this variable is globally, through your init file
0600: or the customization buffer.  However, you can set
0601: @code{version-control} locally in an individual buffer to control the
0602: making of backups for that buffer's file (@pxref{Locals}).  You can
0603: have Emacs set @code{version-control} locally whenever you visit a
0604: given file (@pxref{File Variables}).  Some modes, such as Rmail mode,
0605: set this variable.
0606: 
0607: @cindex @env{VERSION_CONTROL} environment variable
0608:   If you set the environment variable @env{VERSION_CONTROL}, to tell
0609: various GNU utilities what to do with backup files, Emacs also obeys the
0610: environment variable by setting the Lisp variable @code{version-control}
0611: accordingly at startup.  If the environment variable's value is @samp{t}
0612: or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
0613: value is @samp{nil} or @samp{existing}, then @code{version-control}
0614: becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
0615: @code{version-control} becomes @code{never}.
0616: 
0617: @vindex make-backup-file-name-function
0618:   If you set the variable @code{make-backup-file-name-function} to
0619: a suitable Lisp function, you can override the usual way Emacs
0620: constructs backup file names.
0621: 
0622: @node Backup Deletion
0623: @subsubsection Automatic Deletion of Backups
0624: 
0625:   To prevent excessive consumption of disk space, Emacs can delete numbered
0626: backup versions automatically.  Generally Emacs keeps the first few backups
0627: and the latest few backups, deleting any in between.  This happens every
0628: time a new backup is made.
0629: 
0630: @vindex kept-old-versions
0631: @vindex kept-new-versions
0632:   The two variables @code{kept-old-versions} and
0633: @code{kept-new-versions} control this deletion.  Their values are,
0634: respectively, the number of oldest (lowest-numbered) backups to keep
0635: and the number of newest (highest-numbered) ones to keep, each time a
0636: new backup is made.  The backups in the middle (excluding those oldest
0637: and newest) are the excess middle versions---those backups are
0638: deleted.  These variables' values are used when it is time to delete
0639: excess versions, just after a new backup version is made; the newly
0640: made backup is included in the count in @code{kept-new-versions}.  By
0641: default, both variables are 2.
0642: 
0643: @vindex delete-old-versions
0644:   If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
0645: backup files silently.  If it is @code{nil}, the default, Emacs asks
0646: you whether it should delete the excess backup versions.  If it has
0647: any other value, then Emacs never automatically deletes backups.
0648: 
0649:   Dired's @kbd{.} (Period) command can also be used to delete old versions.
0650: @xref{Flagging Many Files}.
0651: 
0652: @node Backup Copying
0653: @subsubsection Copying vs.@: Renaming
0654: 
0655:   Backup files can be made by copying the old file or by renaming it.
0656: This makes a difference when the old file has multiple names (hard
0657: links).  If the old file is renamed into the backup file, then the
0658: alternate names become names for the backup file.  If the old file is
0659: copied instead, then the alternate names remain names for the file
0660: that you are editing, and the contents accessed by those names will be
0661: the new contents.
0662: 
0663:   The method of making a backup file may also affect the file's owner
0664: and group.  If copying is used, these do not change.  If renaming is used,
0665: you become the file's owner, and the file's group becomes the default
0666: (different operating systems have different defaults for the group).
0667: 
0668: @vindex backup-by-copying
0669: @vindex backup-by-copying-when-linked
0670: @vindex backup-by-copying-when-mismatch
0671: @vindex backup-by-copying-when-privileged-mismatch
0672: @cindex file ownership, and backup
0673: @cindex backup, and user-id
0674:   The choice of renaming or copying is made as follows:
0675: 
0676: @itemize
0677: @item
0678: If the variable @code{backup-by-copying} is non-@code{nil} (the
0679: default is @code{nil}), use copying.
0680: 
0681: @item
0682: Otherwise, if the variable @code{backup-by-copying-when-linked} is
0683: non-@code{nil} (the default is @code{nil}), and the file has multiple
0684: names, use copying.
0685: 
0686: @item
0687: Otherwise, if the variable @code{backup-by-copying-when-mismatch} is
0688: non-@code{nil} (the default is @code{t}), and renaming would change
0689: the file's owner or group, use copying.
0690: 
0691: If you change @code{backup-by-copying-when-mismatch} to @code{nil},
0692: Emacs checks the numeric user-id of the file's owner.  If this is
0693: higher than @code{backup-by-copying-when-privileged-mismatch}, then it
0694: behaves as though @code{backup-by-copying-when-mismatch} is
0695: non-@code{nil} anyway.
0696: 
0697: @item
0698: Otherwise, renaming is the default choice.
0699: @end itemize
0700: 
0701:   When a file is managed with a version control system (@pxref{Version
0702: Control}), Emacs does not normally make backups in the usual way for
0703: that file.  But @dfn{committing} (a.k.a.@: @dfn{checking in},
0704: @pxref{VCS Concepts}) new versions of files is similar in some ways
0705: to making backups.  One unfortunate similarity is that these
0706: operations typically break hard links, disconnecting the file name you
0707: visited from any alternate names for the same file.  This has nothing
0708: to do with Emacs---the version control system does it.
0709: 
0710: @node Customize Save
0711: @subsection Customizing Saving of Files
0712: 
0713: @vindex require-final-newline
0714:   If the value of the variable @code{require-final-newline} is
0715: @code{t}, saving or writing a file silently puts a newline at the end
0716: if there isn't already one there.  If the value is @code{visit}, Emacs
0717: adds a newline at the end of any file that doesn't have one, just
0718: after it visits the file.  (This marks the buffer as modified, and you
0719: can undo it.)  If the value is @code{visit-save}, Emacs adds such
0720: newlines both on visiting and on saving.  If the value is @code{nil},
0721: Emacs leaves the end of the file unchanged; any other non-@code{nil}
0722: value means Emacs asks you whether to add a newline.  The default is
0723: @code{nil}.
0724: 
0725: @vindex mode-require-final-newline
0726:   Some major modes are designed for specific kinds of files that are
0727: always supposed to end in newlines.  Such major modes set the variable
0728: @code{require-final-newline} to the value of
0729: @code{mode-require-final-newline}, which defaults to @code{t}.  By
0730: setting the latter variable, you can control how these modes handle
0731: final newlines.
0732: 
0733: @vindex write-region-inhibit-fsync
0734:   Normally, when a program writes a file, the operating system briefly
0735: caches the file's data in main memory before committing the data to
0736: disk.  This can greatly improve performance; for example, when running
0737: on laptops, it can avoid a disk spin-up each time a file is written.
0738: However, it risks data loss if the operating system crashes before
0739: committing the cache to disk.
0740: 
0741:   To lessen this risk, Emacs can invoke the @code{fsync} system call
0742: after saving a file.  Using @code{fsync} does not eliminate the risk
0743: of data loss, partly because many systems do not implement
0744: @code{fsync} properly, and partly because Emacs's file-saving
0745: procedure typically relies also on directory updates that might not
0746: survive a crash even if @code{fsync} works properly.
0747: 
0748:   The @code{write-region-inhibit-fsync} variable controls whether
0749: Emacs invokes @code{fsync} after saving a file.  The variable's
0750: default value is @code{nil} when Emacs is interactive, and @code{t}
0751: when Emacs runs in batch mode (@pxref{Initial Options, Batch Mode}).
0752: 
0753:   Emacs never uses @code{fsync} when writing auto-save files, as these
0754: files might lose data anyway.
0755: 
0756: @node Interlocking
0757: @subsection Protection against Simultaneous Editing
0758: 
0759: @cindex file dates
0760: @cindex simultaneous editing
0761:   Simultaneous editing occurs when two users visit the same file, both
0762: make changes, and then both save them.  If nobody is informed that
0763: this is happening, whichever user saves first would later find that
0764: their changes were lost.
0765: 
0766:   On some systems, Emacs notices immediately when the second user starts
0767: to change the file, and issues an immediate warning.  On all systems,
0768: Emacs checks when you save the file, and warns if you are about to
0769: overwrite another user's changes.  You can prevent loss of the other
0770: user's work by taking the proper corrective action instead of saving the
0771: file.
0772: 
0773: @findex ask-user-about-lock
0774: @cindex locking files
0775: @cindex .#, lock file names
0776: @cindex file locking
0777:   When you make the first modification in an Emacs buffer that is
0778: visiting a file, Emacs records that the file is @dfn{locked} by you.
0779: (It does this by creating a specially-named symbolic link@footnote{If
0780: your file system does not support symbolic links, a regular file is
0781: used.} with special contents in the same directory.  @xref{File
0782: Locks,,, elisp}, for more details.)  Emacs removes the lock when you
0783: save the changes.  The idea is that the file is locked whenever an
0784: Emacs buffer visiting it has unsaved changes.
0785: 
0786: @vindex create-lockfiles
0787:   You can prevent the creation of lock files by setting the variable
0788: @code{create-lockfiles} to @code{nil}.  @strong{Caution:} by
0789: doing so you will lose the benefits that this feature provides.
0790: 
0791: @cindex collision
0792:   If you begin to modify the buffer while the visited file is locked by
0793: someone else, this constitutes a @dfn{collision}.  When Emacs detects a
0794: collision, it asks you what to do, by calling the Lisp function
0795: @code{ask-user-about-lock}.  You can redefine this function for the sake
0796: of customization.  The standard definition of this function asks you a
0797: question and accepts three possible answers:
0798: 
0799: @table @kbd
0800: @item s
0801: Steal the lock.  Whoever was already changing the file loses the lock,
0802: and you gain the lock.
0803: @item p
0804: Proceed.  Go ahead and edit the file despite its being locked by someone else.
0805: @item q
0806: Quit.  This causes an error (@code{file-locked}), and the buffer
0807: contents remain unchanged---the modification you were trying to make
0808: does not actually take place.
0809: @end table
0810: 
0811:   If Emacs or the operating system crashes, this may leave behind lock
0812: files which are stale, so you may occasionally get warnings about
0813: spurious collisions.  When you determine that the collision is
0814: spurious, just use @kbd{p} to tell Emacs to go ahead anyway.
0815: 
0816:   Note that locking works on the basis of a file name; if a file has
0817: multiple names, Emacs does not prevent two users from editing it
0818: simultaneously under different names.
0819: 
0820:   A lock file cannot be written in some circumstances, e.g., if Emacs
0821: lacks the system permissions or cannot create lock files for some
0822: other reason.  In these cases, Emacs can still detect the collision
0823: when you try to save a file, by checking the file's last-modification
0824: date.  If the file has changed since the last time Emacs visited or
0825: saved it, that implies that changes have been made in some other way,
0826: and will be lost if Emacs proceeds with saving.  Emacs then displays a
0827: warning message and asks for confirmation before saving; answer
0828: @kbd{yes} to save, and @kbd{no} or @kbd{C-g} cancel the save.
0829: 
0830:   If you are notified that simultaneous editing has already taken
0831: place, one way to compare the buffer to its file is the @kbd{M-x
0832: diff-buffer-with-file} command.  @xref{Comparing Files}.
0833: 
0834: @node File Shadowing
0835: @subsection Shadowing Files
0836: @cindex shadow files
0837: @cindex file shadows
0838: @findex shadow-initialize
0839: 
0840:   You can arrange to keep identical @dfn{shadow} copies of certain
0841: files in more than one place---possibly on different machines.  To do
0842: this, first you must set up a @dfn{shadow file group}, which is a set
0843: of identically-named files shared between a list of sites.  The file
0844: group is permanent and applies to further Emacs sessions as well as
0845: the current one.  Once the group is set up, every time you exit Emacs,
0846: it will copy the file you edited to the other files in its group.  You
0847: can also do the copying without exiting Emacs, by typing @w{@kbd{M-x
0848: shadow-copy-files}}.
0849: 
0850: @cindex shadow cluster
0851: A @dfn{shadow cluster} is a group of hosts that share directories, so
0852: that copying to or from one of them is sufficient to update the file
0853: on all of them.  Each shadow cluster has a name, and specifies the
0854: network address of a primary host (the one we copy files to), and a
0855: regular expression that matches the host names of all the other hosts
0856: in the cluster.  You can define a shadow cluster with @w{@kbd{M-x
0857: shadow-define-cluster}}.
0858: 
0859: @table @kbd
0860: @item M-x shadow-initialize
0861: Set up file shadowing.
0862: @item M-x shadow-define-literal-group
0863: Declare a single file to be shared between sites.
0864: @item M-x shadow-define-regexp-group
0865: Make all files that match each of a group of files be shared between hosts.
0866: @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
0867: Define a shadow file cluster @var{name}.
0868: @item M-x shadow-copy-files
0869: Copy all pending shadow files.
0870: @item M-x shadow-cancel
0871: Cancel the instruction to shadow some files.
0872: @end table
0873: 
0874: To set up a shadow file group, use @w{@kbd{M-x
0875: shadow-define-literal-group}} or @w{@kbd{M-x
0876: shadow-define-regexp-group}}.  See their documentation strings for
0877: further information.
0878: 
0879: Before copying a file to its shadows, Emacs asks for confirmation.
0880: You can answer ``no'' to bypass copying of this file, this time.  If
0881: you want to cancel the shadowing permanently for a certain file, use
0882: @w{@kbd{M-x shadow-cancel}} to eliminate or change the shadow file group.
0883: 
0884: File Shadowing is not available on MS Windows.
0885: 
0886: @node Time Stamps
0887: @subsection Updating Time Stamps Automatically
0888: @cindex time stamps
0889: @cindex modification dates
0890: @cindex locale, date format
0891: 
0892: You can arrange to put a time stamp in a file, so that it is updated
0893: automatically each time you edit and save the file.  The time stamp
0894: must be in the first eight lines of the file, and you should insert it
0895: like this:
0896: 
0897: @example
0898: Time-stamp: <>
0899: @end example
0900: 
0901: @noindent
0902: or like this:
0903: 
0904: @example
0905: Time-stamp: " "
0906: @end example
0907: 
0908: @findex time-stamp
0909:   Then add the function @code{time-stamp} to the hook
0910: @code{before-save-hook} (@pxref{Hooks}).  When you save the file, this
0911: function then automatically updates the time stamp with the current
0912: date and time.  You can also use the command @kbd{M-x time-stamp} to
0913: update the time stamp manually.  By default the time stamp is
0914: formatted according to your locale setting (@pxref{Environment}) and
0915: time zone (@pxref{Time of Day,,, elisp, The Emacs Lisp Reference
0916: Manual}).  For customizations, see the Custom group @code{time-stamp}.
0917: 
0918: @node Reverting
0919: @section Reverting a Buffer
0920: @findex revert-buffer
0921: @cindex drastic changes
0922: @cindex reread a file
0923: 
0924:   If you have made extensive changes to a file-visiting buffer and
0925: then change your mind, you can @dfn{revert} the changes and go back to
0926: the saved version of the file.  To do this, type @kbd{M-x
0927: revert-buffer}.  Since reverting unintentionally could lose a lot of
0928: work, Emacs asks for confirmation first.
0929: 
0930:   The @code{revert-buffer} command tries to position point in such a
0931: way that, if the file was edited only slightly, you will be at
0932: approximately the same part of the text as before.  But if you have
0933: made major changes, point may end up in a totally different location.
0934: 
0935:   Reverting marks the buffer as not modified.  However, it adds the
0936: reverted changes as a single modification to the buffer's undo history
0937: (@pxref{Undo}).  Thus, after reverting, you can type @kbd{C-/} or its
0938: aliases to bring the reverted changes back, if you happen to change
0939: your mind.
0940: 
0941:   Some kinds of buffers that are not associated with files, such as
0942: Dired buffers, can also be reverted.  For them, reverting means
0943: recalculating their contents.  Buffers created explicitly with
0944: @kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error
0945: if you try.
0946: 
0947: @vindex revert-without-query
0948:   When you edit a file that changes automatically and frequently---for
0949: example, a log of output from a process that continues to run---it may
0950: be useful for Emacs to revert the file without querying you.  To
0951: request this behavior, set the variable @code{revert-without-query} to
0952: a list of regular expressions.  When a file name matches one of these
0953: regular expressions, @code{find-file} and @code{revert-buffer} will
0954: revert it automatically if it has changed---provided the buffer itself
0955: is not modified.  (If you have edited the text, it would be wrong to
0956: discard your changes.)
0957: 
0958: @cindex Global Auto Revert mode
0959: @cindex mode, Global Auto Revert
0960: @cindex Auto Revert mode
0961: @cindex mode, Auto Revert
0962: @findex global-auto-revert-mode
0963: @findex auto-revert-mode
0964: @findex auto-revert-tail-mode
0965: @vindex auto-revert-interval
0966: @vindex auto-revert-remote-files
0967: @vindex auto-revert-verbose
0968:   You can also tell Emacs to revert buffers periodically.  To do this
0969: for a specific buffer, enable the minor mode Auto-Revert mode by
0970: typing @kbd{M-x auto-revert-mode}.  This automatically reverts the
0971: current buffer when its visited file changes on disk.  To do the same
0972: for all file buffers, type @kbd{M-x global-auto-revert-mode} to enable
0973: Global Auto-Revert mode.  These minor modes do not check or revert
0974: remote files, because that is usually too slow.  This behavior can be
0975: changed by setting the variable @code{auto-revert-remote-files} to
0976: non-@code{nil}.
0977: 
0978: @cindex file notifications
0979: @vindex auto-revert-use-notify
0980:   By default, Auto-Revert mode works using @dfn{file notifications},
0981: whereby changes in the filesystem are reported to Emacs by the OS.
0982: You can disable use of file notifications by customizing the variable
0983: @code{auto-revert-use-notify} to a @code{nil} value, then Emacs will
0984: check for file changes by polling every five seconds.  You can change
0985: the polling interval through the variable @code{auto-revert-interval}.
0986: 
0987:   Not all systems support file notifications; where they are not
0988: supported, @code{auto-revert-use-notify} will be @code{nil} by
0989: default.
0990: 
0991:   One use of Auto-Revert mode is to ``tail'' a file such as a system
0992: log, so that changes made to that file by other programs are
0993: continuously displayed.  To do this, just move the point to the end of
0994: the buffer, and it will stay there as the file contents change.
0995: However, if you are sure that the file will only change by growing at
0996: the end, use Auto-Revert Tail mode instead
0997: (@code{auto-revert-tail-mode}).  It is more efficient for this.
0998: Auto-Revert Tail mode works also for remote files.
0999: 
1000:   When a buffer is auto-reverted, a message is generated.  This can be
1001: suppressed by setting @code{auto-revert-verbose} to @code{nil}.
1002: 
1003:   In Dired buffers (@pxref{Dired}), Auto-Revert mode refreshes the
1004: buffer when a file is created or deleted in the buffer's directory.
1005: 
1006:   @xref{VC Undo}, for commands to revert to earlier versions of files
1007: under version control.  @xref{VC Mode Line}, for Auto Revert
1008: peculiarities when visiting files under version control.
1009: 
1010: @ifnottex
1011: @include arevert-xtra.texi
1012: @end ifnottex
1013: 
1014: @node Auto Save
1015: @section Auto-Saving: Protection Against Disasters
1016: @cindex Auto Save mode
1017: @cindex mode, Auto Save
1018: @cindex crashes
1019: 
1020:   From time to time, Emacs automatically saves each visited file in a
1021: separate file, without altering the file you actually use.  This is
1022: called @dfn{auto-saving}.  It prevents you from losing more than a
1023: limited amount of work if the system crashes.
1024: 
1025: @vindex auto-save-no-message
1026:   When Emacs determines that it is time for auto-saving, it considers
1027: each buffer, and each is auto-saved if auto-saving is enabled for it
1028: and it has been changed since the last time it was auto-saved.  When
1029: the @code{auto-save-no-message} variable is set to @code{nil} (the
1030: default), the message @samp{Auto-saving...} is displayed in the echo
1031: area during auto-saving, if any files are actually auto-saved; to
1032: disable these messages, customize the variable to a non-@code{nil}
1033: value.  Errors occurring during auto-saving are caught so that they do
1034: not interfere with the execution of commands you have been typing.
1035: 
1036: @menu
1037: * Files: Auto Save Files.       The file where auto-saved changes are
1038:                                   actually made until you save the file.
1039: * Control: Auto Save Control.   Controlling when and how often to auto-save.
1040: * Recover::                     Recovering text from auto-save files.
1041: @end menu
1042: 
1043: @node Auto Save Files
1044: @subsection Auto-Save Files
1045: 
1046:   Auto-saving does not normally save in the files that you visited,
1047: because it can be very undesirable to save a change that you did not
1048: want to make permanent.  Instead, auto-saving is done in a different
1049: file called the @dfn{auto-save file}, and the visited file is changed
1050: only when you request saving explicitly (such as with @kbd{C-x C-s}).
1051: 
1052:   Normally, the auto-save file name is made by appending @samp{#} to the
1053: front and rear of the visited file name.  Thus, a buffer visiting file
1054: @file{foo.c} is auto-saved in a file @file{#foo.c#}.  Most buffers that
1055: are not visiting files are auto-saved only if you request it explicitly;
1056: when they are auto-saved, the auto-save file name is made by appending
1057: @samp{#} to the front and rear of buffer name, then
1058: adding digits and letters at the end for uniqueness.  For
1059: example, the @file{*mail*} buffer in which you compose messages to be
1060: sent might be auto-saved in a file named @file{#*mail*#704juu}.  Auto-save file
1061: names are made this way unless you reprogram parts of Emacs to do
1062: something different (the functions @code{make-auto-save-file-name} and
1063: @code{auto-save-file-name-p}).  The file name to be used for auto-saving
1064: in a buffer is calculated when auto-saving is turned on in that buffer.
1065: 
1066: @cindex auto-save for remote files
1067: @vindex auto-save-file-name-transforms
1068:   The variable @code{auto-save-file-name-transforms} allows a degree
1069: of control over the auto-save file name.  It lets you specify a series
1070: of regular expressions and replacements to transform the auto save
1071: file name.  The default value puts the auto-save files for remote
1072: files (@pxref{Remote Files}) into the temporary file directory on the
1073: local machine.
1074: 
1075:   When you delete a substantial part of the text in a large buffer, auto
1076: save turns off temporarily in that buffer.  This is because if you
1077: deleted the text unintentionally, you might find the auto-save file more
1078: useful if it contains the deleted text.  To reenable auto-saving after
1079: this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
1080: auto-save-mode}.
1081: 
1082: @vindex auto-save-visited-mode
1083:   If you want auto-saving to be done in the visited file rather than
1084: in a separate auto-save file, enable the global minor mode
1085: @code{auto-save-visited-mode}.  In this mode, auto-saving is identical
1086: to explicit saving.  Note that this mode is orthogonal to the
1087: @code{auto-save} mode described above; you can enable both at the same
1088: time.  However, if @code{auto-save} mode is active in some buffer and
1089: the obsolete @code{auto-save-visited-file-name} variable is set to a
1090: non-@code{nil} value, that buffer won't be affected by
1091: @code{auto-save-visited-mode}.
1092: 
1093:   You can use the variable @code{auto-save-visited-interval} to
1094: customize the interval between auto-save operations in
1095: @code{auto-save-visited-mode}; by default it's five seconds.
1096: @code{auto-save-interval} and @code{auto-save-timeout} have no effect
1097: on @code{auto-save-visited-mode}.  @xref{Auto Save Control}, for
1098: details on these variables.
1099: 
1100: @vindex delete-auto-save-files
1101:   A buffer's auto-save file is deleted when you save the buffer in its
1102: visited file.  (You can inhibit this by setting the variable
1103: @code{delete-auto-save-files} to @code{nil}.)  Changing the visited
1104: file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames
1105: any auto-save file to go with the new visited name.
1106: 
1107: @node Auto Save Control
1108: @subsection Controlling Auto-Saving
1109: 
1110: @vindex auto-save-default
1111: @findex auto-save-mode
1112:   Each time you visit a file, auto-saving is turned on for that file's
1113: buffer if the variable @code{auto-save-default} is non-@code{nil} (but
1114: not in batch mode; @pxref{Initial Options}).  The default for this
1115: variable is @code{t}, so auto-saving is the usual practice for
1116: file-visiting buffers.  To toggle auto-saving in the current buffer,
1117: type @kbd{M-x auto-save-mode}.  Auto Save mode acts as a buffer-local
1118: minor mode (@pxref{Minor Modes}).
1119: 
1120: @vindex auto-save-interval
1121:   Emacs auto-saves periodically based on how many characters you have
1122: typed since the last auto-save.  The variable
1123: @code{auto-save-interval} specifies how many characters there are
1124: between auto-saves.  By default, it is 300.  Emacs doesn't accept
1125: values that are too small: if you customize @code{auto-save-interval}
1126: to a value less than 20, Emacs will behave as if the value is 20.
1127: 
1128: @vindex auto-save-timeout
1129:   Auto-saving also takes place when you stop typing for a while.  By
1130: default, it does this after 30 seconds of idleness (at this time,
1131: Emacs may also perform garbage collection; @pxref{Garbage
1132: Collection,,, elisp, The Emacs Lisp Reference Manual}).  To change
1133: this interval, customize the variable @code{auto-save-timeout}.  The
1134: actual time period is longer if the current buffer is long; this is a
1135: heuristic which aims to keep out of your way when you are editing long
1136: buffers, in which auto-save takes an appreciable amount of time.
1137: Auto-saving during idle periods accomplishes two things: first, it
1138: makes sure all your work is saved if you go away from the terminal for
1139: a while; second, it may avoid some auto-saving while you are actually
1140: typing.
1141: 
1142: @vindex auto-save-visited-interval
1143:   When @code{auto-save-visited-mode} is enabled, Emacs will auto-save
1144: file-visiting buffers after five seconds of idle time.  You can
1145: customize the variable @code{auto-save-visited-interval} to change the
1146: idle time interval.
1147: 
1148:   Emacs also does auto-saving whenever it gets a fatal error.  This
1149: includes killing the Emacs job with a shell command such as @samp{kill
1150: %emacs}, or disconnecting a phone line or network connection.
1151: 
1152: @findex do-auto-save
1153:   You can perform an auto-save explicitly with the command @kbd{M-x
1154: do-auto-save}.
1155: 
1156: @node Recover
1157: @subsection Recovering Data from Auto-Saves
1158: 
1159: @findex recover-file
1160:   You can use the contents of an auto-save file to recover from a loss
1161: of data with the command @kbd{M-x recover-file @key{RET} @var{file}
1162: @key{RET}}.  This visits @var{file} and then (after your confirmation)
1163: restores the contents from its auto-save file @file{#@var{file}#}.
1164: You can then save with @kbd{C-x C-s} to put the recovered text into
1165: @var{file} itself.  For example, to recover file @file{foo.c} from its
1166: auto-save file @file{#foo.c#}, do:
1167: 
1168: @example
1169: M-x recover-file @key{RET} foo.c @key{RET}
1170: yes @key{RET}
1171: C-x C-s
1172: @end example
1173: 
1174:   Before asking for confirmation, @kbd{M-x recover-file} displays a
1175: directory listing describing the specified file and the auto-save file,
1176: so you can compare their sizes and dates.  If the auto-save file
1177: is older, @kbd{M-x recover-file} does not offer to read it.
1178: 
1179: @findex recover-session
1180:   If Emacs or the computer crashes, you can recover all the files you
1181: were editing from their auto save files with the command @kbd{M-x
1182: recover-session}.  This first shows you a list of recorded interrupted
1183: sessions.  Move point to the one you choose, and type @kbd{C-c C-c}.
1184: 
1185:   Then @code{recover-session} asks about each of the files that were
1186: being edited during that session, asking whether to recover that file.
1187: If you answer @kbd{y}, it calls @code{recover-file}, which works in its
1188: normal fashion.  It shows the dates of the original file and its
1189: auto-save file, and asks once again whether to recover that file.
1190: 
1191:   When @code{recover-session} is done, the files you've chosen to
1192: recover are present in Emacs buffers.  You should then save them.  Only
1193: this---saving them---updates the files themselves.
1194: 
1195: @vindex auto-save-list-file-prefix
1196:   Emacs records information about interrupted sessions in files named
1197: @file{.saves-@var{pid}-@var{hostname}~} in the directory
1198: @file{~/.emacs.d/auto-save-list/}.  This directory is determined by
1199: the variable @code{auto-save-list-file-prefix}.  If you set
1200: @code{auto-save-list-file-prefix} to @code{nil}, sessions are not
1201: recorded for recovery.
1202: 
1203: @node File Aliases
1204: @section File Name Aliases
1205: @cindex symbolic links (visiting)
1206: @cindex hard links (visiting)
1207: 
1208:   Symbolic links and hard links both make it possible for several file
1209: names to refer to the same file.  Hard links are alternate names that
1210: refer directly to the file; all the names are equally valid, and no one
1211: of them is preferred.  By contrast, a symbolic link is a kind of defined
1212: alias: when @file{foo} is a symbolic link to @file{bar}, you can use
1213: either name to refer to the file, but @file{bar} is the real name, while
1214: @file{foo} is just an alias.  More complex cases occur when symbolic
1215: links point to directories.
1216: 
1217: @vindex find-file-existing-other-name
1218: @vindex find-file-suppress-same-file-warnings
1219:   Normally, if you visit a file which Emacs is already visiting under
1220: a different name, Emacs displays a message in the echo area and uses
1221: the existing buffer visiting that file.  This can happen on systems
1222: that support hard or symbolic links, or if you use a long file name on
1223: a system that truncates long file names, or on a case-insensitive file
1224: system.  You can suppress the message by setting the variable
1225: @code{find-file-suppress-same-file-warnings} to a non-@code{nil}
1226: value.  You can disable this feature entirely by setting the variable
1227: @code{find-file-existing-other-name} to @code{nil}: then if you visit
1228: the same file under two different names, you get a separate buffer for
1229: each file name.
1230: 
1231: @vindex find-file-visit-truename
1232: @cindex truenames of files
1233: @cindex file truenames
1234:   If the variable @code{find-file-visit-truename} is non-@code{nil},
1235: then the file name recorded for a buffer is the file's @dfn{truename}
1236: (made by replacing all symbolic links with their target names), rather
1237: than the name you specify.  Setting @code{find-file-visit-truename} also
1238: implies the effect of @code{find-file-existing-other-name}.
1239: 
1240: @cindex directory name abbreviation
1241: @vindex directory-abbrev-alist
1242:   Sometimes, a directory is ordinarily accessed through a symbolic
1243: link, and you may want Emacs to preferentially show its linked
1244: name.  To do this, customize @code{directory-abbrev-alist}.  Each
1245: element in this list should have the form @code{(@var{from}
1246: . @var{to})}, which means to replace @var{from} with @var{to} whenever
1247: @var{from} appears in a directory name.  The @var{from} string is a
1248: regular expression (@pxref{Regexps}).  It is matched against directory
1249: names anchored at the first character, and should start with @samp{\`}
1250: (to support directory names with embedded newlines, which would defeat
1251: @samp{^}).  The @var{to} string should be an ordinary absolute
1252: directory name pointing to the same directory.  Do not use @samp{~} to
1253: stand for a home directory in the @var{to} string; Emacs performs
1254: these substitutions separately.  Here's an example, from a system on
1255: which @file{/home/fsf} is normally accessed through a symbolic link
1256: named @file{/fsf}:
1257: 
1258: @example
1259: (("\\`/home/fsf" . "/fsf"))
1260: @end example
1261: 
1262: @node Directories
1263: @section File Directories
1264: 
1265: @cindex file directory
1266: @cindex directory listing
1267:   The file system groups files into @dfn{directories}.  A @dfn{directory
1268: listing} is a list of all the files in a directory.  Emacs provides
1269: commands to create and delete directories, and to make directory
1270: listings in brief format (file names only) and verbose format (sizes,
1271: dates, and other attributes included).  Emacs also includes a
1272: directory browser feature called Dired, which you can invoke with
1273: @kbd{C-x d}; see @ref{Dired}.
1274: 
1275: @table @kbd
1276: @item C-x C-d @var{dir-or-pattern} @key{RET}
1277: Display a brief directory listing (@code{list-directory}).
1278: @item C-u C-x C-d @var{dir-or-pattern} @key{RET}
1279: Display a verbose directory listing.
1280: @item M-x make-directory @key{RET} @var{dirname} @key{RET}
1281: Create a new directory named @var{dirname}.
1282: @item M-x delete-directory @key{RET} @var{dirname} @key{RET}
1283: Delete the directory named @var{dirname}.  If it isn't empty,
1284: you will be asked whether you want to delete it recursively.
1285: @end table
1286: 
1287: @findex list-directory
1288: @kindex C-x C-d
1289:   The command to display a directory listing is @kbd{C-x C-d}
1290: (@code{list-directory}).  It reads using the minibuffer a file name
1291: which is either a directory to be listed or a wildcard-containing
1292: pattern for the files to be listed.  For example,
1293: 
1294: @example
1295: C-x C-d /u2/emacs/etc @key{RET}
1296: @end example
1297: 
1298: @noindent
1299: lists all the files in directory @file{/u2/emacs/etc}.  Here is an
1300: example of specifying a file name pattern:
1301: 
1302: @example
1303: C-x C-d /u2/emacs/src/*.c @key{RET}
1304: @end example
1305: 
1306:   Normally, @kbd{C-x C-d} displays a brief directory listing containing
1307: just file names.  A numeric argument (regardless of value) tells it to
1308: make a verbose listing including sizes, dates, and owners (like
1309: @samp{ls -l}).
1310: 
1311: @vindex list-directory-brief-switches
1312: @vindex list-directory-verbose-switches
1313:   The text of a directory listing is mostly obtained by running
1314: @code{ls} in an inferior process.  Two Emacs variables control the
1315: switches passed to @code{ls}: @code{list-directory-brief-switches} is
1316: a string giving the switches to use in brief listings (@code{"-CF"} by
1317: default), and @code{list-directory-verbose-switches} is a string
1318: giving the switches to use in a verbose listing (@code{"-l"} by
1319: default).
1320: 
1321:   In verbose directory listings, Emacs adds information about the
1322: amount of free space on the disk that contains the directory.
1323: 
1324:   The command @kbd{M-x delete-directory} prompts for a directory's name
1325: using the minibuffer, and deletes the directory if it is empty.  If
1326: the directory is not empty, you will be asked whether you want to
1327: delete it recursively.  On systems that have a ``Trash'' (or ``Recycle
1328: Bin'') feature, you can make this command move the specified directory
1329: to the Trash instead of deleting it outright, by changing the variable
1330: @code{delete-by-moving-to-trash} to @code{t}.  @xref{Misc File Ops},
1331: for more information about using the Trash.
1332: 
1333: @node Comparing Files
1334: @section Comparing Files
1335: @cindex comparing files
1336: 
1337: @findex diff
1338: @vindex diff-switches
1339:   The command @kbd{M-x diff} prompts for two file names, using the
1340: minibuffer, and displays the differences between the two files in a
1341: buffer named @file{*diff*}.  This works by running the @command{diff}
1342: program, using options taken from the variable @code{diff-switches}.
1343: The value of @code{diff-switches} should be a string; the default is
1344: @code{"-u"} to specify a unified context diff.
1345: @c Note that the actual name of the info file is diffutils.info,
1346: @c but it adds a dir entry for diff too.
1347: @c On older systems, only "info diff" works, not "info diffutils".
1348: @xref{Top,, Diff, diffutils, Comparing and Merging Files}, for more
1349: information about the @command{diff} program.
1350: 
1351:   The output of the @code{diff} command is shown using a major mode
1352: called Diff mode.  @xref{Diff Mode}.
1353: 
1354:   A (much more sophisticated) alternative is @kbd{M-x ediff}
1355: (@pxref{Top, Ediff, Ediff, ediff, The Ediff Manual}).
1356: 
1357: @findex diff-backup
1358:   The command @kbd{M-x diff-backup} compares a specified file with its
1359: most recent backup.  If you specify the name of a backup file,
1360: @code{diff-backup} compares it with the source file that it is a
1361: backup of.  In all other respects, this behaves like @kbd{M-x diff}.
1362: 
1363: @findex diff-buffer-with-file
1364:   The command @kbd{M-x diff-buffer-with-file} compares a specified
1365: buffer with its corresponding file.  This shows you what changes you
1366: would make to the file if you save the buffer.
1367: 
1368: @findex compare-windows
1369:   The command @kbd{M-x compare-windows} compares the text in the
1370: current window with that in the window that was the selected window
1371: before you selected the current one.  (For more information about
1372: windows in Emacs, @ref{Windows}.)  Comparison starts at point in each
1373: window, after pushing each initial point value on the mark ring
1374: (@pxref{Mark Ring}) in its respective buffer.  Then it moves point
1375: forward in each window, one character at a time, until it reaches
1376: characters that don't match.  Then the command exits.
1377: 
1378:   If point in the two windows is followed by non-matching text when
1379: the command starts, @kbd{M-x compare-windows} tries heuristically to
1380: advance up to matching text in the two windows, and then exits.  So if
1381: you use @kbd{M-x compare-windows} repeatedly, each time it either
1382: skips one matching range or finds the start of another.
1383: 
1384: @vindex compare-ignore-case
1385: @vindex compare-ignore-whitespace
1386:   With a numeric argument, @code{compare-windows} ignores changes in
1387: whitespace.  If the variable @code{compare-ignore-case} is
1388: non-@code{nil}, the comparison ignores differences in case as well.
1389: If the variable @code{compare-ignore-whitespace} is non-@code{nil},
1390: @code{compare-windows} by default ignores changes in whitespace, but a
1391: prefix argument turns that off for that single invocation of the
1392: command.
1393: 
1394: @cindex Smerge mode
1395: @findex smerge-mode
1396: @cindex failed merges
1397: @cindex merges, failed
1398: @cindex comparing 3 files (@code{diff3})
1399:   You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor
1400: mode for editing output from the @command{diff3} program.  This is
1401: typically the result of a failed merge from a version control system
1402: update outside VC, due to conflicting changes to a file.  Smerge
1403: mode provides commands to resolve conflicts by selecting specific
1404: changes.
1405: 
1406: @iftex
1407: @xref{Emerge,,, emacs-xtra, Specialized Emacs Features},
1408: @end iftex
1409: @ifnottex
1410: @xref{Emerge},
1411: @end ifnottex
1412: for the Emerge facility, which provides a powerful interface for
1413: merging files.
1414: 
1415: @node Diff Mode
1416: @section Diff Mode
1417: @cindex Diff mode
1418: @findex diff-mode
1419: @cindex patches, editing
1420: 
1421:   Diff mode is a major mode used for the output of @kbd{M-x diff} and
1422: other similar commands.  This kind of output is called a @dfn{patch},
1423: because it can be passed to the @command{patch} command to
1424: automatically apply the specified changes.  To select Diff mode
1425: manually, type @kbd{M-x diff-mode}.
1426: 
1427: @cindex hunk, diff
1428:   The changes specified in a patch are grouped into @dfn{hunks}, which
1429: are contiguous chunks of text that contain one or more changed lines.
1430: Hunks usually also include unchanged lines to provide context for the
1431: changes.  Each hunk is preceded by a @dfn{hunk header}, which
1432: specifies the old and new line numbers where the hunk's changes occur.
1433: Diff mode highlights each hunk header, to distinguish it from the
1434: actual contents of the hunk.
1435: 
1436:   The first hunk in a patch is preceded by a file header, which shows
1437: the names of the new and the old versions of the file, and their time
1438: stamps.  If a patch shows changes for more than one file, each file
1439: has such a header before the first hunk of that file's changes.
1440: 
1441: @vindex diff-update-on-the-fly
1442:   You can edit a Diff mode buffer like any other buffer.  (If it is
1443: read-only, you need to make it writable first; see @ref{Misc Buffer}.)
1444: Whenever you edit a hunk, Diff mode attempts to automatically correct
1445: the line numbers in the hunk headers, to ensure that the patch remains
1446: correct, and could still be applied by @command{patch}.  To disable
1447: automatic line number correction, change the variable
1448: @code{diff-update-on-the-fly} to @code{nil}.
1449: 
1450:   Diff mode arranges for hunks to be treated as compiler error
1451: messages by @kbd{M-g M-n} and other commands that handle error messages
1452: (@pxref{Compilation Mode}).  Thus, you can use the compilation-mode
1453: commands to visit the corresponding source locations.
1454: 
1455:   In addition, Diff mode provides the following commands to navigate,
1456: manipulate and apply parts of patches:
1457: 
1458: @table @kbd
1459: @item M-n
1460: @findex diff-hunk-next
1461: Move to the next hunk-start (@code{diff-hunk-next}).  With prefix
1462: argument @var{n}, move forward to the @var{n}th next hunk.
1463: 
1464: @vindex diff-refine
1465: By default, Diff mode @dfn{refines} hunks as Emacs displays them,
1466: highlighting their changes with better granularity.  Alternatively, if
1467: you set @code{diff-refine} to the symbol @code{navigation}, Diff mode
1468: only refines the hunk you move to with this command or with
1469: @code{diff-hunk-prev}.
1470: 
1471: @item M-p
1472: @findex diff-hunk-prev
1473: Move to the previous hunk-start (@code{diff-hunk-prev}).  With prefix
1474: argument @var{n}, move back to the @var{n}th previous hunk.  Like
1475: @kbd{M-n}, this command refines the hunk you move to if you set
1476: @code{diff-refine} to the symbol @code{navigation}.
1477: 
1478: @item M-@}
1479: @findex diff-file-next
1480: Move to the next file-start, in a multi-file patch
1481: (@code{diff-file-next}).  With prefix argument @var{n}, move forward
1482: to the start of the @var{n}th next file.
1483: 
1484: @item M-@{
1485: @findex diff-file-prev
1486: Move to the previous file-start, in a multi-file patch
1487: (@code{diff-file-prev}).  With prefix argument @var{n}, move back to
1488: the start of the @var{n}th previous file.
1489: 
1490: @item M-k
1491: @findex diff-hunk-kill
1492: Kill the hunk at point (@code{diff-hunk-kill}).
1493: 
1494: @item M-K
1495: @findex diff-file-kill
1496: In a multi-file patch, kill the current file part.
1497: (@code{diff-file-kill}).
1498: 
1499: @item C-c C-a
1500: @findex diff-apply-hunk
1501: @cindex patches, applying
1502: Apply this hunk to its target file (@code{diff-apply-hunk}).  With a
1503: prefix argument of @kbd{C-u}, revert this hunk, i.e.@: apply the
1504: reverse of the hunk, which changes the ``new'' version into the ``old''
1505: version.  If @code{diff-jump-to-old-file} is non-@code{nil}, apply the
1506: hunk to the ``old'' version of the file instead.
1507: 
1508: @item C-c C-b
1509: @findex diff-refine-hunk
1510: Highlight the changes of the hunk at point with a finer granularity
1511: (@code{diff-refine-hunk}).  This allows you to see exactly which parts
1512: of each changed line were actually changed.
1513: 
1514: @vindex diff-refine
1515: By default, Diff mode refines hunks as Emacs displays them, so you may
1516: find this command useful if you customize @code{diff-refine} to a
1517: non-default value.
1518: 
1519: @item C-c C-c
1520: @findex diff-goto-source
1521: @vindex diff-jump-to-old-file
1522: Go to the source file and line corresponding to this hunk
1523: (@code{diff-goto-source}).  By default, this jumps to the ``new''
1524: version of the file, the one shown first on the file header.
1525: With a prefix argument, jump to the ``old'' version instead.  If
1526: @code{diff-jump-to-old-file} is non-@code{nil}, this command by
1527: default jumps to the ``old'' file, and the meaning of the prefix
1528: argument is reversed.  If the prefix argument is a number greater than
1529: 8 (e.g., if you type @kbd{C-u C-u C-c C-c}), then this command also
1530: sets @code{diff-jump-to-old-file} for the next invocation.
1531: If the source file is under version control (@pxref{Version Control}),
1532: this jumps to the work file by default.  With a prefix argument, jump
1533: to the ``old'' revision of the file (@pxref{Old Revisions}), when
1534: point is on the old line, or otherwise jump to the ``new'' revision.
1535: 
1536: @item C-c C-e
1537: @findex diff-ediff-patch
1538: Start an Ediff session with the patch (@code{diff-ediff-patch}).
1539: @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
1540: 
1541: @item C-c C-n
1542: @findex diff-restrict-view
1543: Restrict the view to the current hunk (@code{diff-restrict-view}).
1544: @xref{Narrowing}.  With a prefix argument, restrict the
1545: view to the current file of a multiple-file patch.  To widen again,
1546: use @kbd{C-x n w} (@code{widen}).
1547: 
1548: @item C-c C-r
1549: @findex diff-reverse-direction
1550: Reverse the direction of comparison for the entire buffer
1551: (@code{diff-reverse-direction}).  With a prefix argument, reverse the
1552: direction only inside the current region (@pxref{Mark}).  Reversing
1553: the direction means changing the hunks and the file-start headers to
1554: produce a patch that would change the ``new'' version into the ``old''
1555: one.
1556: 
1557: @item C-c C-s
1558: @findex diff-split-hunk
1559: Split the hunk at point (@code{diff-split-hunk}) into two separate
1560: hunks.  This inserts a hunk header and modifies the header of the
1561: current hunk.  This command is useful for manually editing patches,
1562: and only works with the @dfn{unified diff format} produced by the
1563: @option{-u} or @option{--unified} options to the @command{diff}
1564: program.  If you need to split a hunk in the @dfn{context diff format}
1565: produced by the @option{-c} or @option{--context} options to
1566: @command{diff}, first convert the buffer to the unified diff format
1567: with @kbd{C-c C-u}.
1568: 
1569: @item C-c C-d
1570: @findex diff-unified->context
1571: Convert the entire buffer to the @dfn{context diff format}
1572: (@code{diff-unified->context}).  With a prefix argument, convert only
1573: the hunks within the region.
1574: 
1575: @item C-c C-u
1576: @findex diff-context->unified
1577: Convert the entire buffer to unified diff format
1578: (@code{diff-context->unified}).  With a prefix argument, convert
1579: unified format to context format.  When the mark is active, convert
1580: only the hunks within the region.
1581: 
1582: @item C-c C-w
1583: @findex diff-ignore-whitespace-hunk
1584: Re-generate the current hunk, disregarding changes in whitespace
1585: (@code{diff-ignore-whitespace-hunk}).
1586: 
1587: @item C-x 4 A
1588: @findex diff-add-change-log-entries-other-window
1589: @findex add-change-log-entry-other-window@r{, in Diff mode}
1590: Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change
1591: Log}), for each one of the hunks
1592: (@code{diff-add-change-log-entries-other-window}).  This creates a
1593: skeleton of the log of changes that you can later fill with the actual
1594: descriptions of the changes.  @kbd{C-x 4 a} itself in Diff mode
1595: operates on behalf of the current hunk's file, but gets the function
1596: name from the patch itself.  This is useful for making log entries for
1597: functions that are deleted by the patch.
1598: @end table
1599: 
1600: @c Trailing whitespace is NOT shown by default.
1601: @c Emacs's dir-locals file enables this (for some reason).
1602: @cindex trailing whitespace, in patches
1603: @findex diff-delete-trailing-whitespace
1604:   Patches sometimes include trailing whitespace on modified lines, as
1605: an unintentional and undesired change.  There are two ways to deal
1606: with this problem.  Firstly, if you enable Whitespace mode in a Diff
1607: buffer (@pxref{Useless Whitespace}), it automatically highlights
1608: trailing whitespace in modified lines.  Secondly, you can use the
1609: command @kbd{M-x diff-delete-trailing-whitespace}, which searches for
1610: trailing whitespace in the lines modified by the patch, and removes
1611: that whitespace in both the patch and the patched source file(s).
1612: This command does not save the modifications that it makes, so you can
1613: decide whether to save the changes (the list of modified files is
1614: displayed in the echo area).  With a prefix argument, it tries to
1615: modify the original (``old'') source files rather than the patched
1616: (``new'') source files.
1617: 
1618: @vindex diff-font-lock-syntax
1619:   If non-@code{nil}, fragments of source in hunks are highlighted
1620: according to the appropriate major mode.
1621: 
1622: @node Copying and Naming
1623: @section Copying, Naming and Renaming Files
1624: 
1625:   Emacs has several commands for copying, naming, and renaming files.
1626: All of them read two file names, @var{old} (or @var{target}) and
1627: @var{new}, using the minibuffer, and then copy or adjust a file's name
1628: accordingly; they do not accept wildcard file names.
1629: 
1630: In all these commands, if the argument @var{new} is just a directory
1631: name (@pxref{Directory Names,,, elisp, the Emacs Lisp Reference
1632: Manual}), the real new name is in that directory, with the same
1633: non-directory component as @var{old}.  For example, the command
1634: @w{@kbd{M-x rename-file @key{RET} ~/foo @key{RET} /tmp/ @key{RET}}}
1635: renames @file{~/foo} to @file{/tmp/foo}.  On GNU and other POSIX-like
1636: systems, directory names end in @samp{/}.
1637: 
1638: All these commands ask for confirmation when the new file name already
1639: exists.
1640: 
1641: @findex copy-file
1642: @cindex copying files
1643:   @kbd{M-x copy-file} copies the contents of the file @var{old} to the
1644: file @var{new}.
1645: 
1646: @findex copy-directory
1647:   @kbd{M-x copy-directory} copies directories, similar to the
1648: @command{cp -r} shell command.  If @var{new} is a directory name, it
1649: creates a copy of the @var{old} directory and puts it in @var{new}.
1650: Otherwise it copies all the contents of @var{old} into a new directory
1651: named @var{new}.
1652: 
1653: @cindex renaming files
1654: @findex rename-file
1655:   @kbd{M-x rename-file} renames file @var{old} as @var{new}.  If the
1656: file name @var{new} already exists, you must confirm with @kbd{yes} or
1657: renaming is not done; this is because renaming causes the old meaning
1658: of the name @var{new} to be lost.  If @var{old} and @var{new} are on
1659: different file systems, the file @var{old} is copied and deleted.
1660: 
1661: @ifnottex
1662:   If a file is under version control (@pxref{Version Control}), you
1663: should rename it using @w{@kbd{M-x vc-rename-file}} instead of
1664: @w{@kbd{M-x rename-file}}.  @xref{VC Delete/Rename}.
1665: @end ifnottex
1666: 
1667: @findex add-name-to-file
1668: @cindex hard links (creation)
1669:   @kbd{M-x add-name-to-file} adds an additional name to an existing
1670: file without removing the old name.  The new name is created as a hard
1671: link to the existing file.  The new name must belong on the same file
1672: system that the file is on.  On MS-Windows, this command works only if
1673: the file resides in an NTFS file system.  On MS-DOS, and some remote
1674: system types, it works by copying the file.
1675: 
1676: @findex make-symbolic-link
1677: @cindex symbolic links (creation)
1678:   @kbd{M-x make-symbolic-link} creates a symbolic link named
1679: @var{new}, which points at @var{target}.  The effect is that future
1680: attempts to open file @var{new} will refer to whatever file is named
1681: @var{target} at the time the opening is done, or will get an error if
1682: the name @var{target} is nonexistent at that time.  This command does
1683: not expand the argument @var{target}, so that it allows you to specify
1684: a relative name as the target of the link.  However, this command
1685: does expand leading @samp{~} in @var{target} so that you can easily
1686: specify home directories, and strips leading @samp{/:} so that you can
1687: specify relative names beginning with literal @samp{~} or @samp{/:}.
1688: @xref{Quoted File Names}.  On MS-Windows, this command works only on
1689: MS Windows Vista and later.  When @var{new} is remote,
1690: it works depending on the system type.
1691: 
1692: @node Misc File Ops
1693: @section Miscellaneous File Operations
1694: 
1695:   Emacs has commands for performing many other operations on files.
1696: All operate on one file; they do not accept wildcard file names.
1697: 
1698: @findex delete-file
1699: @cindex deletion (of files)
1700:   @kbd{M-x delete-file} prompts for a file and deletes it.  If you are
1701: deleting many files in one directory, it may be more convenient to use
1702: Dired rather than @code{delete-file}.  @xref{Dired Deletion}.
1703: 
1704: @cindex trash
1705: @cindex recycle bin
1706: @findex move-file-to-trash
1707:   @kbd{M-x move-file-to-trash} moves a file into the system
1708: @dfn{Trash} (or @dfn{Recycle Bin}).  This is a facility available on
1709: most operating systems; files that are moved into the Trash can be
1710: brought back later if you change your mind.  (The way to restore
1711: trashed files is system-dependent.)
1712: 
1713: @vindex delete-by-moving-to-trash
1714:   By default, Emacs deletion commands do @emph{not} use the Trash.  To
1715: use the Trash (when it is available) for common deletion commands,
1716: change the variable @code{delete-by-moving-to-trash} to @code{t}.
1717: This affects the commands @kbd{M-x delete-file} and @kbd{M-x
1718: delete-directory} (@pxref{Directories}), as well as the deletion
1719: commands in Dired (@pxref{Dired Deletion}).  Supplying a prefix
1720: argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes
1721: them delete outright, instead of using the Trash, regardless of
1722: @code{delete-by-moving-to-trash}.
1723: 
1724: @ifnottex
1725:   If a file is under version control (@pxref{Version Control}), you
1726: should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x
1727: delete-file}.  @xref{VC Delete/Rename}.
1728: @end ifnottex
1729: 
1730: @kindex C-x i
1731: @findex insert-file
1732:   @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
1733: contents of the specified file into the current buffer at point,
1734: leaving point unchanged before the contents.  The position after the
1735: inserted contents is added to the mark ring, without activating the
1736: mark (@pxref{Mark Ring}).
1737: 
1738: @findex insert-file-literally
1739:   @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
1740: except the file is inserted literally: it is treated as a sequence
1741: of @acronym{ASCII} characters with no special encoding or conversion,
1742: similar to the @kbd{M-x find-file-literally} command
1743: (@pxref{Visiting}).
1744: 
1745: @findex write-region
1746:   @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
1747: copies the contents of the region into the specified file.  @kbd{M-x
1748: append-to-file} adds the text of the region to the end of the
1749: specified file.  @xref{Accumulating Text}.  The variable
1750: @code{write-region-inhibit-fsync} applies to these commands, as well
1751: as saving files; see @ref{Customize Save}.
1752: 
1753: @findex set-file-modes
1754: @cindex file modes
1755: @cindex file permissions
1756:   @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file
1757: mode}, and applies that file mode to the specified file.  File modes,
1758: also called @dfn{file permissions}, determine whether a file can be
1759: read, written to, or executed, and by whom.  This command reads file
1760: modes using the same symbolic or octal format accepted by the
1761: @command{chmod} command; for instance, @samp{u+x} means to add
1762: execution permission for the user who owns the file.  It has no effect
1763: on operating systems that do not support file modes.  @code{chmod} is a
1764: convenience alias for this function.
1765: 
1766: @node Compressed Files
1767: @section Accessing Compressed Files
1768: @cindex compression
1769: @cindex uncompression
1770: @cindex Auto Compression mode
1771: @cindex mode, Auto Compression
1772: @pindex gzip
1773: 
1774:   Emacs automatically uncompresses compressed files when you visit
1775: them, and automatically recompresses them if you alter them and save
1776: them.  Emacs recognizes compressed files by their file names.  File
1777: names ending in @samp{.gz} indicate a file compressed with
1778: @code{gzip}.  Other endings indicate other compression programs.
1779: 
1780:   Automatic uncompression and compression apply to all the operations in
1781: which Emacs uses the contents of a file.  This includes visiting it,
1782: saving it, inserting its contents into a buffer, loading it, and byte
1783: compiling it.
1784: 
1785: @findex auto-compression-mode
1786: @vindex auto-compression-mode
1787:   To disable this feature, type the command @kbd{M-x
1788: auto-compression-mode}.  You can disable it permanently by
1789: customizing the variable @code{auto-compression-mode}.
1790: 
1791: @node File Archives
1792: @section File Archives
1793: @cindex mode, tar
1794: @cindex Tar mode
1795: @cindex file archives
1796: 
1797:   A file whose name ends in @samp{.tar} is normally an @dfn{archive}
1798: made by the @code{tar} program.  Emacs views these files in a special
1799: mode called Tar mode which provides a Dired-like list of the contents
1800: (@pxref{Dired}).  You can move around through the list just as you
1801: would in Dired, and visit the subfiles contained in the archive.
1802: However, not all Dired commands are available in Tar mode.
1803: 
1804:   If Auto Compression mode is enabled (@pxref{Compressed Files}), then
1805: Tar mode is used also for compressed archives---files with extensions
1806: @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}.
1807: 
1808:   The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file
1809: into its own buffer.  You can edit it there, and if you save the
1810: buffer, the edited version will replace the version in the Tar buffer.
1811: Clicking with the mouse on the file name in the Tar buffer does
1812: likewise.  @kbd{v} extracts a file into a buffer in View mode
1813: (@pxref{View Mode}).  @kbd{o} extracts the file and displays it in
1814: another window, so you could edit the file and operate on the archive
1815: simultaneously.
1816: 
1817:   The @kbd{I} key adds a new (regular) file to the archive.  The file
1818: is initially empty, but can readily be edited using the commands
1819: above.  The command inserts the new file before the current one, so
1820: that using it on the topmost line of the Tar buffer makes the new file
1821: the first one in the archive, and using it at the end of the buffer
1822: makes it the last one.
1823: 
1824:   @kbd{d} marks a file for deletion when you later use @kbd{x}, and
1825: @kbd{u} unmarks a file, as in Dired.  @kbd{C} copies a file from the
1826: archive to disk and @kbd{R} renames a file within the archive.
1827: @kbd{g} reverts the buffer from the archive on disk.  The keys
1828: @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission bits,
1829: group, and owner, respectively.
1830: 
1831:   Saving the Tar buffer writes a new version of the archive to disk with
1832: the changes you made to the components.
1833: 
1834:   You don't need the @code{tar} program to use Tar mode---Emacs reads
1835: the archives directly.  However, accessing compressed archives
1836: requires the appropriate uncompression program.
1837: 
1838: @cindex Archive mode
1839: @cindex mode, archive
1840: @pindex arc
1841: @pindex jar
1842: @pindex zip
1843: @pindex rar
1844: @pindex lzh
1845: @pindex zoo
1846: @pindex 7z
1847: @cindex Java class archives
1848: @cindex unzip archives
1849:   A separate but similar Archive mode is used for @code{arc},
1850: @code{jar}, @code{lzh}, @code{zip}, @code{rar}, @code{7z}, and
1851: @code{zoo} archives, as well as @code{exe} files that are
1852: self-extracting executables.
1853: 
1854:   The key bindings of Archive mode are similar to those in Tar mode,
1855: with the addition of the @kbd{m} key which marks a file for subsequent
1856: operations, and @kbd{M-@key{DEL}} which unmarks all the marked files.
1857: Also, the @kbd{a} key toggles the display of detailed file
1858: information, for those archive types where it won't fit in a single
1859: line.  Operations such as renaming a subfile, or changing its mode or
1860: owner, are supported only for some of the archive formats.
1861: 
1862:   Unlike Tar mode, Archive mode runs the archiving programs to unpack
1863: and repack archives.  However, you don't need these programs to look
1864: at the archive table of contents, only to extract or manipulate the
1865: subfiles in the archive.  Details of the program names and their
1866: options can be set in the @samp{Archive} Customize group
1867: (@pxref{Customization Groups}).
1868: 
1869: @node Remote Files
1870: @section Remote Files
1871: 
1872: @cindex Tramp
1873: @cindex FTP
1874: @cindex remote file access
1875:   You can refer to files on other machines using a special file name
1876: syntax:
1877: 
1878: @example
1879: @group
1880: /@var{method}:@var{host}:@var{filename}
1881: /@var{method}:@var{user}@@@var{host}:@var{filename}
1882: /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
1883: @end group
1884: @end example
1885: 
1886: @noindent
1887: To carry out this request, Emacs uses a remote-login program such as
1888: @command{ssh}.
1889: You must always specify in the file name which method to use---for
1890: example, @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses
1891: @command{ssh}.  When you specify the pseudo method @samp{-} in the
1892: file name, Emacs chooses the method as follows:
1893: 
1894: @enumerate
1895: @item
1896: If the host name starts with @samp{ftp.} (with dot), Emacs uses FTP.
1897: @item
1898: If the user name is @samp{ftp} or @samp{anonymous}, Emacs uses FTP.
1899: @item
1900: If the variable @code{tramp-default-method} is set to @samp{ftp},
1901: Emacs uses FTP.
1902: @item
1903: If @command{ssh-agent} is running, Emacs uses @command{scp}.
1904: @item
1905: Otherwise, Emacs uses @command{ssh}.
1906: @end enumerate
1907: 
1908: @cindex disabling remote files
1909: @noindent
1910: You can entirely turn off the remote file name feature by setting the
1911: variable @code{tramp-mode} to @code{nil}.  You can turn off the
1912: feature in individual cases by quoting the file name with @samp{/:}
1913: (@pxref{Quoted File Names}).
1914: 
1915: @cindex @code{ange-ftp}
1916:   Remote file access through FTP is handled by the Ange-FTP package, which
1917: is documented in the following.  Remote file access through the other
1918: methods is handled by the Tramp package, which has its own manual.
1919: @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}.
1920: 
1921: @vindex ange-ftp-default-user
1922: @cindex user name for remote file access
1923:   When the Ange-FTP package is used, Emacs logs in through FTP using
1924: the name @var{user}, if that is specified in the remote file name.  If
1925: @var{user} is unspecified, Emacs logs in using your user name on the
1926: local system; but if you set the variable @code{ange-ftp-default-user}
1927: to a string, that string is used instead.  When logging in, Emacs may
1928: also ask for a password.
1929: 
1930: @cindex backups for remote files
1931: @vindex ange-ftp-make-backup-files
1932:   For performance reasons, Emacs does not make backup files for files
1933: accessed via FTP by default.  To make it do so, change the variable
1934: @code{ange-ftp-make-backup-files} to a non-@code{nil} value.
1935: 
1936:   By default, auto-save files for remote files are made in the
1937: temporary file directory on the local machine, as specified by the
1938: variable @code{auto-save-file-name-transforms}.  @xref{Auto Save
1939: Files}.
1940: 
1941: @cindex anonymous FTP
1942: @vindex ange-ftp-generate-anonymous-password
1943:   To visit files accessible by anonymous FTP, you use special user
1944: names @samp{anonymous} or @samp{ftp}.  Passwords for these user names
1945: are handled specially.  The variable
1946: @code{ange-ftp-generate-anonymous-password} controls what happens: if
1947: the value of this variable is a string, then that string is used as
1948: the password; if non-@code{nil} (the default), then the value of
1949: @code{user-mail-address} is used; if @code{nil}, then Emacs prompts
1950: you for a password as usual (@pxref{Passwords}).
1951: 
1952: @cindex firewall, and accessing remote files
1953: @cindex gateway, and remote file access with @code{ange-ftp}
1954: @vindex ange-ftp-smart-gateway
1955: @vindex ange-ftp-gateway-host
1956:   Sometimes you may be unable to access files on a remote machine
1957: because a @dfn{firewall} in between blocks the connection for security
1958: reasons.  If you can log in on a @dfn{gateway} machine from which the
1959: target files @emph{are} accessible, and whose FTP server supports
1960: gatewaying features, you can still use remote file names; all you have
1961: to do is specify the name of the gateway machine by setting the
1962: variable @code{ange-ftp-gateway-host}, and set
1963: @code{ange-ftp-smart-gateway} to @code{t}.  Otherwise you may be able
1964: to make remote file names work, but the procedure is complex.  You can
1965: read the instructions by typing @kbd{M-x finder-commentary @key{RET}
1966: ange-ftp @key{RET}}.
1967: 
1968: @node Quoted File Names
1969: @section Quoted File Names
1970: 
1971: @cindex quoting file names
1972: @cindex file names, quote special characters
1973:   You can @dfn{quote} an absolute file name to prevent special
1974: characters and syntax in it from having their special effects.
1975: The way to do this is to add @samp{/:} at the beginning.
1976: 
1977:   For example, you can quote a local file name which appears remote, to
1978: prevent it from being treated as a remote file name.  Thus, if you have
1979: a directory named @file{/foo:} and a file named @file{bar} in it, you
1980: can refer to that file in Emacs as @samp{/:/foo:/bar}.
1981: 
1982:   If you want to quote only special characters in the local part of a
1983: remote file name, you can quote just the local part.
1984: @samp{/ssh:baz:/:/foo:/bar} refers to the file @file{bar} of directory
1985: @file{/foo:} on the host @file{baz}.
1986: 
1987:   @samp{/:} can also prevent @samp{~} from being treated as a special
1988: character for a user's home directory.  For example, @file{/:/tmp/~hack}
1989: refers to a file whose name is @file{~hack} in directory @file{/tmp}.
1990: 
1991:   Quoting with @samp{/:} is also a way to enter in the minibuffer a
1992: file name that contains @samp{$}.  In order for this to work, the
1993: @samp{/:} must be at the beginning of the minibuffer contents.  (You
1994: can also double each @samp{$}; see @ref{File Names with $}.)
1995: 
1996:   You can also quote wildcard characters with @samp{/:}, for visiting.
1997: For example, @file{/:/tmp/foo*bar} visits the file
1998: @file{/tmp/foo*bar}.
1999: 
2000:   Another method of getting the same result is to enter
2001: @file{/tmp/foo[*]bar}, which is a wildcard specification that matches
2002: only @file{/tmp/foo*bar}.  However, in many cases there is no need to
2003: quote the wildcard characters because even unquoted they give the
2004: right result.  For example, if the only file name in @file{/tmp} that
2005: starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar},
2006: then specifying @file{/tmp/foo*bar} will visit only
2007: @file{/tmp/foo*bar}.
2008: 
2009: @node File Name Cache
2010: @section File Name Cache
2011: 
2012: @cindex file name caching
2013: @cindex cache of file names
2014: @pindex find
2015: @kindex C-TAB
2016: @findex file-cache-minibuffer-complete
2017:   You can use the @dfn{file name cache} to make it easy to locate a
2018: file by name, without having to remember exactly where it is located.
2019: When typing a file name in the minibuffer, @kbd{C-@key{TAB}}
2020: (@code{file-cache-minibuffer-complete}) completes it using the file
2021: name cache.  If you repeat @kbd{C-@key{TAB}}, that cycles through the
2022: possible completions of what you had originally typed.  (However, note
2023: that the @kbd{C-@key{TAB}} character cannot be typed on most text
2024: terminals.)
2025: 
2026:   The file name cache does not fill up automatically.  Instead, you
2027: load file names into the cache using these commands:
2028: 
2029: @findex file-cache-add-directory
2030: @table @kbd
2031: @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET}
2032: Add each file name in @var{directory} to the file name cache.
2033: @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET}
2034: Add each file name in @var{directory} and all of its nested
2035: subdirectories to the file name cache.
2036: @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET}
2037: Add each file name in @var{directory} and all of its nested
2038: subdirectories to the file name cache, using @command{locate} to find
2039: them all.
2040: @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET}
2041: Add each file name in each directory listed in @var{variable} to the
2042: file name cache.  @var{variable} should be a Lisp variable whose value
2043: is a list of directories, like @code{load-path}.
2044: @item M-x file-cache-clear-cache @key{RET}
2045: Clear the cache; that is, remove all file names from it.
2046: @end table
2047: 
2048:   The file name cache is not persistent: it is kept and maintained
2049: only for the duration of the Emacs session.  You can view the contents
2050: of the cache with the @code{file-cache-display} command.
2051: 
2052: @node File Conveniences
2053: @section Convenience Features for Finding Files
2054: 
2055:   In this section, we introduce some convenient facilities for finding
2056: recently-opened files, reading file names from a buffer, and viewing
2057: image files.
2058: 
2059: @findex recentf-mode
2060: @vindex recentf-mode
2061: @findex recentf-save-list
2062: @findex recentf-edit-list
2063:   If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
2064: @samp{File} menu includes a submenu containing a list of recently
2065: opened files.  @kbd{M-x recentf-save-list} saves the current
2066: @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list}
2067: edits it.
2068: 
2069: @c FIXME partial-completion-mode (complete.el) is obsolete.
2070:   The @kbd{M-x ffap} command generalizes @code{find-file} with more
2071: powerful heuristic defaults (@pxref{FFAP}), often based on the text at
2072: point.  Partial Completion mode offers other features extending
2073: @code{find-file}, which can be used with @code{ffap}.
2074: @xref{Completion Options}.
2075: 
2076: @findex image-mode
2077: @findex image-toggle-display
2078: @findex image-next-file
2079: @findex image-previous-file
2080: @cindex images, viewing
2081:   Visiting image files automatically selects Image mode.  In this
2082: major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display})
2083: to toggle between displaying the file as an image in the Emacs buffer,
2084: and displaying its underlying text (or raw byte) representation.
2085: Additionally you can type @kbd{C-c C-x} (@code{image-toggle-hex-display})
2086: to toggle between displaying the file as an image in the Emacs buffer,
2087: and displaying it in hex representation.
2088: Displaying the file as an image works only if Emacs is compiled with
2089: support for displaying such images.  If the displayed image is wider
2090: or taller than the frame, the usual point motion keys (@kbd{C-f},
2091: @kbd{C-p}, and so forth) cause different parts of the image to be
2092: displayed.  You can press @kbd{n} (@code{image-next-file}) and @kbd{p}
2093: (@code{image-previous-file}) to visit the next image file and the
2094: previous image file in the same directory, respectively.
2095: 
2096: @findex image-toggle-animation
2097: @findex image-next-frame
2098: @findex image-previous-frame
2099: @findex image-goto-frame
2100: @findex image-increase-speed
2101: @findex image-decrease-speed
2102: @findex image-reset-speed
2103: @findex image-reverse-speed
2104: @vindex image-animate-loop
2105: @cindex image animation
2106: @cindex animated images
2107:   If the image can be animated, the command @key{RET}
2108: (@code{image-toggle-animation}) starts or stops the animation.
2109: Animation plays once, unless the option @code{image-animate-loop} is
2110: non-@code{nil}.  With @kbd{f} (@code{image-next-frame}) and @kbd{b}
2111: (@code{image-previous-frame}) you can step through the individual
2112: frames.  Both commands accept a numeric prefix to step through several
2113: frames at once.  You can go to a specific frame with @kbd{F}
2114: (@code{image-goto-frame}).  Frames are indexed from 1.  Typing @kbd{a
2115: +} (@code{image-increase-speed}) increases the speed of the animation,
2116: @kbd{a -} (@code{image-decrease-speed}) decreases it, and @kbd{a r}
2117: (@code{image-reverse-speed}) reverses it.  The command @kbd{a 0}
2118: (@code{image-reset-speed}) resets the speed to the original value.
2119: 
2120: @cindex ImageMagick support
2121: @vindex imagemagick-enabled-types
2122: @vindex imagemagick-types-inhibit
2123:   If Emacs was compiled with support for the ImageMagick library, it
2124: can use ImageMagick to render a wide variety of images.  The variable
2125: @code{imagemagick-enabled-types} lists the image types that Emacs may
2126: render using ImageMagick; each element in the list should be an
2127: internal ImageMagick name for an image type, as a symbol or an
2128: equivalent string (e.g., @code{BMP} for @file{.bmp} images).  To
2129: enable ImageMagick for all possible image types, change
2130: @code{imagemagick-enabled-types} to @code{t}.  The variable
2131: @code{imagemagick-types-inhibit} lists the image types which should
2132: never be rendered using ImageMagick, regardless of the value of
2133: @code{imagemagick-enabled-types} (the default list includes types like
2134: @code{C} and @code{HTML}, which ImageMagick can render as an image
2135: but Emacs should not).  To disable ImageMagick entirely, change
2136: @code{imagemagick-types-inhibit} to @code{t}.
2137: 
2138: @findex thumbs-mode
2139: @cindex mode, Thumbs
2140:   The Image-Dired package can also be used to view images as
2141: thumbnails.  @xref{Image-Dired}.
2142: 
2143: @node Filesets
2144: @section Filesets
2145: @cindex filesets
2146: @cindex sets of files
2147: 
2148: @findex filesets-init
2149:   If you regularly edit a certain group of files, you can define them
2150: as a @dfn{fileset}.  This lets you perform certain operations, such as
2151: visiting, @code{query-replace}, and shell commands on all the files at
2152: once.  To make use of filesets, you must first add the expression
2153: @code{(filesets-init)} to your init file (@pxref{Init File}).  This
2154: adds a @samp{Filesets} sub-menu to the menu bar's @samp{File} menu.
2155: 
2156: @findex filesets-add-buffer
2157: @findex filesets-remove-buffer
2158:   The simplest way to define a fileset is by adding files to it one at
2159: a time.  To add a file to fileset @var{name}, visit the file and type
2160: @kbd{M-x filesets-add-buffer @key{RET} @var{name} @key{RET}}.  If
2161: there is no fileset @var{name}, this creates a new one, which
2162: initially contains only the current file.  The command @kbd{M-x
2163: filesets-remove-buffer} removes the current file from a fileset.
2164: 
2165:   You can also edit the list of filesets directly, with @kbd{M-x
2166: filesets-edit} (or by choosing @samp{Edit Filesets} from the
2167: @samp{Filesets} menu).  The editing is performed in a Customize buffer
2168: (@pxref{Easy Customization}).  Normally, a fileset is a simple list of
2169: files, but you can also define a fileset as a regular expression
2170: matching file names.  Some examples of these more complicated filesets
2171: are shown in the Customize buffer.  Remember to select @samp{Save for
2172: future sessions} if you want to use the same filesets in future Emacs
2173: sessions.
2174: 
2175:   You can use the command @kbd{M-x filesets-open} to visit all the
2176: files in a fileset, and @kbd{M-x filesets-close} to close them.  Use
2177: @kbd{M-x filesets-run-cmd} to run a shell command on all the files in
2178: a fileset.  These commands are also available from the @samp{Filesets}
2179: menu, where each existing fileset is represented by a submenu.
2180: 
2181:    @xref{Version Control}, for a different concept of filesets:
2182: groups of files bundled together for version control operations.
2183: Filesets of that type are unnamed, and do not persist across Emacs
2184: sessions.
2185: