changeset 84239:6b41ff8832d5

Move here from ../../man

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/emacs/files.texi	Thu Sep 06 04:45:50 2007 +0000
@@ -0,0 +1,2950 @@
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
+@c   2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Files, Buffers, Keyboard Macros, Top
+@chapter File Handling
+@cindex files
+
+  The operating system stores data permanently in named @dfn{files}, so
+most of the text you edit with Emacs comes from a file and is ultimately
+stored in a file.
+
+  To edit a file, you must tell Emacs to read the file and prepare a
+buffer containing a copy of the file's text.  This is called
+@dfn{visiting} the file.  Editing commands apply directly to text in the
+buffer; that is, to the copy inside Emacs.  Your changes appear in the
+file itself only when you @dfn{save} the buffer back into the file.
+
+  In addition to visiting and saving files, Emacs can delete, copy,
+rename, and append to files, keep multiple versions of them, and operate
+on file directories.
+
+@menu
+* File Names::          How to type and edit file-name arguments.
+* Visiting::            Visiting a file prepares Emacs to edit the file.
+* Saving::              Saving makes your changes permanent.
+* Reverting::           Reverting cancels all the changes not saved.
+@ifnottex
+* Autorevert::          Auto Reverting non-file buffers.
+@end ifnottex
+* Auto Save::           Auto Save periodically protects against loss of data.
+* File Aliases::        Handling multiple names for one file.
+* Version Control::     Version control systems (RCS, CVS and SCCS).
+* Directories::         Creating, deleting, and listing file directories.
+* Comparing Files::     Finding where two files differ.
+* Diff Mode::           Mode for editing file differences.
+* Misc File Ops::       Other things you can do on files.
+* Compressed Files::    Accessing compressed files.
+* File Archives::       Operating on tar, zip, jar etc. archive files.
+* Remote Files::        Accessing files on other sites.
+* Quoted File Names::   Quoting special characters in file names.
+* File Name Cache::     Completion against a list of files you often use.
+* File Conveniences::   Convenience Features for Finding Files.
+* Filesets::            Handling sets of files.
+@end menu
+
+@node File Names
+@section File Names
+@cindex file names
+
+  Most Emacs commands that operate on a file require you to specify the
+file name.  (Saving and reverting are exceptions; the buffer knows which
+file name to use for them.)  You enter the file name using the
+minibuffer (@pxref{Minibuffer}).  @dfn{Completion} is available
+(@pxref{Completion}) to make it easier to specify long file names.  When
+completing file names, Emacs ignores those whose file-name extensions
+appear in the variable @code{completion-ignored-extensions}; see
+@ref{Completion Options}.
+
+  For most operations, there is a @dfn{default file name} which is used
+if you type just @key{RET} to enter an empty argument.  Normally the
+default file name is the name of the file visited in the current buffer;
+this makes it easy to operate on that file with any of the Emacs file
+commands.
+
+@vindex default-directory
+  Each buffer has a default directory which is normally the same as the
+directory of the file visited in that buffer.  When you enter a file
+name without a directory, the default directory is used.  If you specify
+a directory in a relative fashion, with a name that does not start with
+a slash, it is interpreted with respect to the default directory.  The
+default directory is kept in the variable @code{default-directory},
+which has a separate value in every buffer.
+
+@findex cd
+@findex pwd
+  The command @kbd{M-x pwd} displays the current buffer's default
+directory, and the command @kbd{M-x cd} sets it (to a value read using
+the minibuffer).  A buffer's default directory changes only when the
+@code{cd} command is used.  A file-visiting buffer's default directory
+is initialized to the directory of the file it visits.  If you create
+a buffer with @kbd{C-x b}, its default directory is copied from that
+of the buffer that was current at the time.
+
+  For example, if the default file name is @file{/u/rms/gnu/gnu.tasks}
+then the default directory is normally @file{/u/rms/gnu/}.  If you
+type just @samp{foo}, which does not specify a directory, it is short
+for @file{/u/rms/gnu/foo}.  @samp{../.login} would stand for
+@file{/u/rms/.login}.  @samp{new/foo} would stand for the file name
+@file{/u/rms/gnu/new/foo}.
+
+@vindex insert-default-directory
+  The default directory actually appears in the minibuffer when the
+minibuffer becomes active to read a file name.  This serves two
+purposes: it @emph{shows} you what the default is, so that you can type
+a relative file name and know with certainty what it will mean, and it
+allows you to @emph{edit} the default to specify a different directory.
+This insertion of the default directory is inhibited if the variable
+@code{insert-default-directory} is set to @code{nil}.
+
+  Note that it is legitimate to type an absolute file name after you
+enter the minibuffer, ignoring the presence of the default directory
+name as part of the text.  The final minibuffer contents may look
+invalid, but that is not so.  For example, if the minibuffer starts out
+with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get
+@samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the
+first slash in the double slash; the result is @samp{/x1/rms/foo}.
+@xref{Minibuffer File}.
+
+@cindex home directory shorthand
+  You can use @file{~/} in a file name to mean your home directory,
+or @file{~@var{user-id}/} to mean the home directory of a user whose
+login name is @code{user-id}@footnote{
+On MS-Windows and MS-DOS systems, where a user doesn't have a home
+directory, Emacs replaces @file{~/} with the value of the
+environment variable @code{HOME}; see @ref{General Variables}.  On
+these systems, the @file{~@var{user-id}/} construct is supported only
+for the current user, i.e., only if @var{user-id} is the current
+user's login name.}.
+
+@cindex environment variables in file names
+@cindex expansion of environment variables
+@cindex @code{$} in file names
+  @anchor{File Names with $}@samp{$} in a file name is used to
+substitute an environment variable.  The environment variable name
+consists of all the alphanumeric characters after the @samp{$};
+alternatively, it can be enclosed in braces after the @samp{$}.  For
+example, if you have used the shell command @command{export
+FOO=rms/hacks} to set up an environment variable named @env{FOO}, then
+you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an
+abbreviation for @file{/u/rms/hacks/test.c}.  If the environment
+variable is not defined, no substitution occurs: @file{/u/$notdefined}
+stands for itself (assuming the environment variable @env{notdefined}
+is not defined).
+
+  Note that shell commands to set environment variables affect Emacs
+only when done before Emacs is started.
+
+  To access a file with @samp{$} in its name, if the @samp{$} causes
+expansion, type @samp{$$}.  This pair is converted to a single
+@samp{$} at the same time as variable substitution is performed for a
+single @samp{$}.  Alternatively, quote the whole file name with
+@samp{/:} (@pxref{Quoted File Names}).  File names which begin with a
+literal @samp{~} should also be quoted with @samp{/:}.
+
+@findex substitute-in-file-name
+  The Lisp function that performs the @samp{$}-substitution is called
+@code{substitute-in-file-name}.  The substitution is performed only on
+file names read as such using the minibuffer.
+
+  You can include non-@acronym{ASCII} characters in file names if you set the
+variable @code{file-name-coding-system} to a non-@code{nil} value.
+@xref{File Name Coding}.
+
+@node Visiting
+@section Visiting Files
+@cindex visiting files
+@cindex open file
+
+@table @kbd
+@item C-x C-f
+Visit a file (@code{find-file}).
+@item C-x C-r
+Visit a file for viewing, without allowing changes to it
+(@code{find-file-read-only}).
+@item C-x C-v
+Visit a different file instead of the one visited last
+(@code{find-alternate-file}).
+@item C-x 4 f
+Visit a file, in another window (@code{find-file-other-window}).  Don't
+alter what is displayed in the selected window.
+@item C-x 5 f
+Visit a file, in a new frame (@code{find-file-other-frame}).  Don't
+alter what is displayed in the selected frame.
+@item M-x find-file-literally
+Visit a file with no conversion of the contents.
+@end table
+
+@cindex files, visiting and saving
+@cindex saving files
+  @dfn{Visiting} a file means reading its contents into an Emacs
+buffer so you can edit them.  Emacs makes a new buffer for each file
+that you visit.  We often say that this buffer ``is visiting'' that
+file, or that the buffer's ``visited file'' is that file.  Emacs
+constructs the buffer name from the file name by throwing away the
+directory, keeping just the name proper.  For example, a file named
+@file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}.
+If there is already a buffer with that name, Emacs constructs a unique
+name---the normal method is to append @samp{<2>}, @samp{<3>}, and so
+on, but you can select other methods (@pxref{Uniquify}).
+
+  Each window's mode line shows the name of the buffer that is being displayed
+in that window, so you can always tell what buffer you are editing.
+
+  The changes you make with editing commands are made in the Emacs
+buffer.  They do not take effect in the file that you visited, or any
+permanent place, until you @dfn{save} the buffer.  Saving the buffer
+means that Emacs writes the current contents of the buffer into its
+visited file.  @xref{Saving}.
+
+@cindex modified (buffer)
+  If a buffer contains changes that have not been saved, we say the
+buffer is @dfn{modified}.  This is important because it implies that
+some changes will be lost if the buffer is not saved.  The mode line
+displays two stars near the left margin to indicate that the buffer is
+modified.
+
+@kindex C-x C-f
+@findex find-file
+  To visit a file, use the command @kbd{C-x C-f} (@code{find-file}).  Follow
+the command with the name of the file you wish to visit, terminated by a
+@key{RET}.
+
+  The file name is read using the minibuffer (@pxref{Minibuffer}), with
+defaulting and completion in the standard manner (@pxref{File Names}).
+While in the minibuffer, you can abort @kbd{C-x C-f} by typing
+@kbd{C-g}.  File-name completion ignores certain file names; for more
+about this, see @ref{Completion Options}.
+
+  Your confirmation that @kbd{C-x C-f} has completed successfully is
+the appearance of new text on the screen and a new buffer name in the
+mode line.  If the specified file does not exist and you could not
+create it, or exists but you can't read it, then you get an error,
+with an error message displayed in the echo area.
+
+  If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
+another copy.  It selects the existing buffer containing that file.
+However, before doing so, it checks whether the file itself has changed
+since you visited or saved it last.  If the file has changed, Emacs offers
+to reread it.
+
+@vindex large-file-warning-threshold
+@cindex maximum buffer size exceeded, error message
+  If you try to visit a file larger than
+@code{large-file-warning-threshold} (the default is 10000000, which is
+about 10 megabytes), Emacs will ask you for confirmation first.  You
+can answer @kbd{y} to proceed with visiting the file.  Note, however,
+that Emacs cannot visit files that are larger than the maximum Emacs
+buffer size, which is around 256 megabytes on 32-bit machines
+(@pxref{Buffers}).  If you try, Emacs will display an error message
+saying that the maximum buffer size has been exceeded.
+
+@cindex file selection dialog
+  On graphical displays there are two additional methods for
+visiting files.  Firstly, when Emacs is built with a suitable GUI
+toolkit, commands invoked with the mouse (by clicking on the menu bar
+or tool bar) use the toolkit's standard File Selection dialog instead
+of prompting for the file name in the minibuffer.  On Unix and
+GNU/Linux platforms, Emacs does that when built with GTK, LessTif, and
+Motif toolkits; on MS-Windows and Mac, the GUI version does that by default.
+For information on how to customize this, see @ref{Dialog Boxes}.
+
+  Secondly, Emacs supports ``drag and drop''; dropping a file into an
+ordinary Emacs window visits the file using that window.  However,
+dropping a file into a window displaying a Dired buffer moves or
+copies the file into the displayed directory.  For details, see
+@ref{Drag and Drop}, and @ref{Misc Dired Features}.
+
+@cindex creating files
+  What if you want to create a new file?  Just visit it.  Emacs displays
+@samp{(New file)} in the echo area, but in other respects behaves as if
+you had visited an existing empty file.  If you make any changes and
+save them, the file is created.
+
+  Emacs recognizes from the contents of a file which end-of-line
+convention it uses to separate lines---newline (used on GNU/Linux and
+on Unix), carriage-return linefeed (used on Microsoft systems), or
+just carriage-return (used on the Macintosh)---and automatically
+converts the contents to the normal Emacs convention, which is that
+the newline character separates lines.  This is a part of the general
+feature of coding system conversion (@pxref{Coding Systems}), and
+makes it possible to edit files imported from different operating
+systems with equal convenience.  If you change the text and save the
+file, Emacs performs the inverse conversion, changing newlines back
+into carriage-return linefeed or just carriage-return if appropriate.
+
+@vindex find-file-run-dired
+  If the file you specify is actually a directory, @kbd{C-x C-f} invokes
+Dired, the Emacs directory browser, so that you can ``edit'' the contents
+of the directory (@pxref{Dired}).  Dired is a convenient way to view, delete,
+or operate on the files in the directory.  However, if the variable
+@code{find-file-run-dired} is @code{nil}, then it is an error to try
+to visit a directory.
+
+  Files which are actually collections of other files, or @dfn{file
+archives}, are visited in special modes which invoke a Dired-like
+environment to allow operations on archive members.  @xref{File
+Archives}, for more about these features.
+
+@cindex wildcard characters in file names
+@vindex find-file-wildcards
+  If the file name you specify contains shell-style wildcard
+characters, Emacs visits all the files that match it.  (On
+case-insensitive filesystems, Emacs matches the wildcards disregarding
+the letter case.)  Wildcards include @samp{?}, @samp{*}, and
+@samp{[@dots{}]} sequences.  To enter the wild card @samp{?} in a file
+name in the minibuffer, you need to type @kbd{C-q ?}.  @xref{Quoted
+File Names}, for information on how to visit a file whose name
+actually contains wildcard characters.  You can disable the wildcard
+feature by customizing @code{find-file-wildcards}.
+
+  If you visit a file that the operating system won't let you modify,
+or that is marked read-only, Emacs makes the buffer read-only too, so
+that you won't go ahead and make changes that you'll have trouble
+saving afterward.  You can make the buffer writable with @kbd{C-x C-q}
+(@code{toggle-read-only}).  @xref{Misc Buffer}.
+
+@kindex C-x C-r
+@findex find-file-read-only
+  If you want to visit a file as read-only in order to protect
+yourself from entering changes accidentally, visit it with the command
+@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}.
+
+@kindex C-x C-v
+@findex find-alternate-file
+  If you visit a nonexistent file unintentionally (because you typed the
+wrong file name), use the @kbd{C-x C-v} command
+(@code{find-alternate-file}) to visit the file you really wanted.
+@kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current
+buffer (after first offering to save it if it is modified).  When
+@kbd{C-x C-v} reads the file name to visit, it inserts the entire
+default file name in the buffer, with point just after the directory
+part; this is convenient if you made a slight error in typing the name.
+
+@kindex C-x 4 f
+@findex find-file-other-window
+  @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
+except that the buffer containing the specified file is selected in another
+window.  The window that was selected before @kbd{C-x 4 f} continues to
+show the same buffer it was already showing.  If this command is used when
+only one window is being displayed, that window is split in two, with one
+window showing the same buffer as before, and the other one showing the
+newly requested file.  @xref{Windows}.
+
+@kindex C-x 5 f
+@findex find-file-other-frame
+  @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
+new frame, or makes visible any existing frame showing the file you
+seek.  This feature is available only when you are using a window
+system.  @xref{Frames}.
+
+@findex find-file-literally
+  If you wish to edit a file as a sequence of @acronym{ASCII} characters with no special
+encoding or conversion, use the @kbd{M-x find-file-literally} command.
+It visits a file, like @kbd{C-x C-f}, but does not do format conversion
+(@pxref{Formatted Text}), character code conversion (@pxref{Coding
+Systems}), or automatic uncompression (@pxref{Compressed Files}), and
+does not add a final newline because of @code{require-final-newline}.
+If you already have visited the same file in the usual (non-literal)
+manner, this command asks you whether to visit it literally instead.
+
+@vindex find-file-hook
+@vindex find-file-not-found-functions
+  Two special hook variables allow extensions to modify the operation of
+visiting files.  Visiting a file that does not exist runs the functions
+in the list @code{find-file-not-found-functions}; this variable holds a list
+of functions, and the functions are called one by one (with no
+arguments) until one of them returns non-@code{nil}.  This is not a
+normal hook, and the name ends in @samp{-functions} rather than @samp{-hook}
+to indicate that fact.
+
+  Successful visiting of any file, whether existing or not, calls the
+functions in the list @code{find-file-hook}, with no arguments.
+This variable is a normal hook.  In the case of a nonexistent file, the
+@code{find-file-not-found-functions} are run first.  @xref{Hooks}.
+
+  There are several ways to specify automatically the major mode for
+editing the file (@pxref{Choosing Modes}), and to specify local
+variables defined for that file (@pxref{File Variables}).
+
+@node Saving
+@section Saving Files
+
+  @dfn{Saving} a buffer in Emacs means writing its contents back into the file
+that was visited in the buffer.
+
+@menu
+* Save Commands::       Commands for saving files.
+* Backup::              How Emacs saves the old version of your file.
+* Customize Save::      Customizing the saving of files.
+* Interlocking::        How Emacs protects against simultaneous editing
+                          of one file by two users.
+* Shadowing: File Shadowing.  Copying files to "shadows" automatically.
+* Time Stamps::         Emacs can update time stamps on saved files.
+@end menu
+
+@node Save Commands
+@subsection Commands for Saving Files
+
+  These are the commands that relate to saving and writing files.
+
+@table @kbd
+@item C-x C-s
+Save the current buffer in its visited file on disk (@code{save-buffer}).
+@item C-x s
+Save any or all buffers in their visited files (@code{save-some-buffers}).
+@item M-~
+Forget that the current buffer has been changed (@code{not-modified}).
+With prefix argument (@kbd{C-u}), mark the current buffer as changed.
+@item C-x C-w
+Save the current buffer with a specified file name (@code{write-file}).
+@item M-x set-visited-file-name
+Change the file name under which the current buffer will be saved.
+@end table
+
+@kindex C-x C-s
+@findex save-buffer
+  When you wish to save the file and make your changes permanent, type
+@kbd{C-x C-s} (@code{save-buffer}).  After saving is finished, @kbd{C-x C-s}
+displays a message like this:
+
+@example
+Wrote /u/rms/gnu/gnu.tasks
+@end example
+
+@noindent
+If the selected buffer is not modified (no changes have been made in it
+since the buffer was created or last saved), saving is not really done,
+because it would have no effect.  Instead, @kbd{C-x C-s} displays a message
+like this in the echo area:
+
+@example
+(No changes need to be saved)
+@end example
+
+@kindex C-x s
+@findex save-some-buffers
+  The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
+or all modified buffers.  It asks you what to do with each buffer.  The
+possible responses are analogous to those of @code{query-replace}:
+
+@table @kbd
+@item y
+Save this buffer and ask about the rest of the buffers.
+@item n
+Don't save this buffer, but ask about the rest of the buffers.
+@item !
+Save this buffer and all the rest with no more questions.
+@c following generates acceptable underfull hbox
+@item @key{RET}
+Terminate @code{save-some-buffers} without any more saving.
+@item .
+Save this buffer, then exit @code{save-some-buffers} without even asking
+about other buffers.
+@item C-r
+View the buffer that you are currently being asked about.  When you exit
+View mode, you get back to @code{save-some-buffers}, which asks the
+question again.
+@item d
+Diff the buffer against its corresponding file, so you can see
+what changes you would be saving.
+@item C-h
+Display a help message about these options.
+@end table
+
+  @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
+@code{save-some-buffers} and therefore asks the same questions.
+
+@kindex M-~
+@findex not-modified
+  If you have changed a buffer but you do not want to save the changes,
+you should take some action to prevent it.  Otherwise, each time you use
+@kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by
+mistake.  One thing you can do is type @kbd{M-~} (@code{not-modified}),
+which clears out the indication that the buffer is modified.  If you do
+this, none of the save commands will believe that the buffer needs to be
+saved.  (@samp{~} is often used as a mathematical symbol for `not'; thus
+@kbd{M-~} is `not', metafied.)  You could also use
+@code{set-visited-file-name} (see below) to mark the buffer as visiting
+a different file name, one which is not in use for anything important.
+Alternatively, you can cancel all the changes made since the file was
+visited or saved, by reading the text from the file again.  This is
+called @dfn{reverting}.  @xref{Reverting}.  (You could also undo all the
+changes by repeating the undo command @kbd{C-x u} until you have undone
+all the changes; but reverting is easier.)  You can also kill the buffer.
+
+@findex set-visited-file-name
+  @kbd{M-x set-visited-file-name} alters the name of the file that the
+current buffer is visiting.  It reads the new file name using the
+minibuffer.  Then it marks the buffer as visiting that file name, and
+changes the buffer name correspondingly.  @code{set-visited-file-name}
+does not save the buffer in the newly visited file; it just alters the
+records inside Emacs in case you do save later.  It also marks the
+buffer as ``modified'' so that @kbd{C-x C-s} in that buffer
+@emph{will} save.
+
+@kindex C-x C-w
+@findex write-file
+  If you wish to mark the buffer as visiting a different file and save it
+right away, use @kbd{C-x C-w} (@code{write-file}).  It is
+equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}
+(except that @kbd{C-x C-w} asks for confirmation if the file exists).
+@kbd{C-x C-s} used on a buffer that is not visiting a file has the
+same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
+buffer as visiting that file, and saves it there.  The default file name in
+a buffer that is not visiting a file is made by combining the buffer name
+with the buffer's default directory (@pxref{File Names}).
+
+  If the new file name implies a major mode, then @kbd{C-x C-w} switches
+to that major mode, in most cases.  The command
+@code{set-visited-file-name} also does this.  @xref{Choosing Modes}.
+
+  If Emacs is about to save a file and sees that the date of the latest
+version on disk does not match what Emacs last read or wrote, Emacs
+notifies you of this fact, because it probably indicates a problem caused
+by simultaneous editing and requires your immediate attention.
+@xref{Interlocking,, Simultaneous Editing}.
+
+@node Backup
+@subsection Backup Files
+@cindex backup file
+@vindex make-backup-files
+@vindex vc-make-backup-files
+
+  On most operating systems, rewriting a file automatically destroys all
+record of what the file used to contain.  Thus, saving a file from Emacs
+throws away the old contents of the file---or it would, except that
+Emacs carefully copies the old contents to another file, called the
+@dfn{backup} file, before actually saving.
+
+  For most files, the variable @code{make-backup-files} determines
+whether to make backup files.  On most operating systems, its default
+value is @code{t}, so that Emacs does write backup files.
+
+  For files managed by a version control system (@pxref{Version
+Control}), the variable @code{vc-make-backup-files} determines whether
+to make backup files.  By default it is @code{nil}, since backup files
+are redundant when you store all the previous versions in a version
+control system.
+@iftex
+@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}.
+@end iftex
+@ifnottex
+@xref{General VC Options}.
+@end ifnottex
+
+
+  At your option, Emacs can keep either a single backup for each file,
+or make a series of numbered backup files for each file that you edit.
+
+@vindex backup-enable-predicate
+@vindex temporary-file-directory
+@vindex small-temporary-file-directory
+  The default value of the @code{backup-enable-predicate} variable
+prevents backup files being written for files in the directories used
+for temporary files, specified by @code{temporary-file-directory} or
+@code{small-temporary-file-directory}.
+
+  Emacs makes a backup for a file only the first time the file is saved
+from one buffer.  No matter how many times you save a file, its backup file
+continues to contain the contents from before the file was visited.
+Normally this means that the backup file contains the contents from before
+the current editing session; however, if you kill the buffer and then visit
+the file again, a new backup file will be made by the next save.
+
+  You can also explicitly request making another backup file from a
+buffer even though it has already been saved at least once.  If you save
+the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
+into a backup file if you save the buffer again.  @kbd{C-u C-u C-x C-s}
+saves the buffer, but first makes the previous file contents into a new
+backup file.  @kbd{C-u C-u C-u C-x C-s} does both things: it makes a
+backup from the previous contents, and arranges to make another from the
+newly saved contents if you save again.
+
+@menu
+* One or Many: Numbered Backups. Whether to make one backup file or many.
+* Names: Backup Names.		How backup files are named.
+* Deletion: Backup Deletion.	Emacs deletes excess numbered backups.
+* Copying: Backup Copying.	Backups can be made by copying or renaming.
+@end menu
+
+@node Numbered Backups
+@subsubsection Numbered Backups
+
+@vindex version-control
+  The choice of single backup file or multiple numbered backup files
+is controlled by the variable @code{version-control}.  Its possible
+values are:
+
+@table @code
+@item t
+Make numbered backups.
+@item nil
+Make numbered backups for files that have numbered backups already.
+Otherwise, make single backups.
+@item never
+Never make numbered backups; always make single backups.
+@end table
+
+@noindent
+The usual way to set this variable is globally, through your
+@file{.emacs} file or the customization buffer.  However, you can set
+@code{version-control} locally in an individual buffer to control the
+making of backups for that buffer's file.  For example, Rmail mode
+locally sets @code{version-control} to @code{never} to make sure that
+there is only one backup for an Rmail file.  @xref{Locals}.
+
+@cindex @env{VERSION_CONTROL} environment variable
+  If you set the environment variable @env{VERSION_CONTROL}, to tell
+various GNU utilities what to do with backup files, Emacs also obeys the
+environment variable by setting the Lisp variable @code{version-control}
+accordingly at startup.  If the environment variable's value is @samp{t}
+or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
+value is @samp{nil} or @samp{existing}, then @code{version-control}
+becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
+@code{version-control} becomes @code{never}.
+
+@node Backup Names
+@subsubsection Single or Numbered Backups
+
+  When Emacs makes a single backup file, its name is normally
+constructed by appending @samp{~} to the file name being edited; thus,
+the backup file for @file{eval.c} would be @file{eval.c~}.
+
+@vindex make-backup-file-name-function
+@vindex backup-directory-alist
+  You can change this behavior by defining the variable
+@code{make-backup-file-name-function} to a suitable function.
+Alternatively you can customize the variable
+@code{backup-directory-alist} to specify that files matching certain
+patterns should be backed up in specific directories.
+
+  A typical use is to add an element @code{("." . @var{dir})} to make
+all backups in the directory with absolute name @var{dir}; Emacs
+modifies the backup file names to avoid clashes between files with the
+same names originating in different directories.  Alternatively,
+adding, say, @code{("." . ".~")} would make backups in the invisible
+subdirectory @file{.~} of the original file's directory.  Emacs
+creates the directory, if necessary, to make the backup.
+
+  If access control stops Emacs from writing backup files under the usual
+names, it writes the backup file as @file{%backup%~} in your home
+directory.  Only one such file can exist, so only the most recently
+made such backup is available.
+
+  If you choose to have a series of numbered backup files, backup file
+names contain @samp{.~}, the number, and another @samp{~} after the
+original file name.  Thus, the backup files of @file{eval.c} would be
+called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way
+through names like @file{eval.c.~259~} and beyond.  The variable
+@code{backup-directory-alist} applies to numbered backups just as
+usual.
+
+@node Backup Deletion
+@subsubsection Automatic Deletion of Backups
+
+  To prevent excessive consumption of disk space, Emacs can delete numbered
+backup versions automatically.  Generally Emacs keeps the first few backups
+and the latest few backups, deleting any in between.  This happens every
+time a new backup is made.
+
+@vindex kept-old-versions
+@vindex kept-new-versions
+  The two variables @code{kept-old-versions} and
+@code{kept-new-versions} control this deletion.  Their values are,
+respectively, the number of oldest (lowest-numbered) backups to keep
+and the number of newest (highest-numbered) ones to keep, each time a
+new backup is made.  The backups in the middle (excluding those oldest
+and newest) are the excess middle versions---those backups are
+deleted.  These variables' values are used when it is time to delete
+excess versions, just after a new backup version is made; the newly
+made backup is included in the count in @code{kept-new-versions}.  By
+default, both variables are 2.
+
+@vindex delete-old-versions
+  If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
+backup files silently.  If it is @code{nil}, the default, Emacs asks
+you whether it should delete the excess backup versions.  If it has
+any other value, then Emacs never automatically deletes backups.
+
+  Dired's @kbd{.} (Period) command can also be used to delete old versions.
+@xref{Dired Deletion}.
+
+@node Backup Copying
+@subsubsection Copying vs.@: Renaming
+
+  Backup files can be made by copying the old file or by renaming it.
+This makes a difference when the old file has multiple names (hard
+links).  If the old file is renamed into the backup file, then the
+alternate names become names for the backup file.  If the old file is
+copied instead, then the alternate names remain names for the file
+that you are editing, and the contents accessed by those names will be
+the new contents.
+
+  The method of making a backup file may also affect the file's owner
+and group.  If copying is used, these do not change.  If renaming is used,
+you become the file's owner, and the file's group becomes the default
+(different operating systems have different defaults for the group).
+
+  Having the owner change is usually a good idea, because then the owner
+always shows who last edited the file.  Also, the owners of the backups
+show who produced those versions.  Occasionally there is a file whose
+owner should not change; it is a good idea for such files to contain
+local variable lists to set @code{backup-by-copying-when-mismatch}
+locally (@pxref{File Variables}).
+
+@vindex backup-by-copying
+@vindex backup-by-copying-when-linked
+@vindex backup-by-copying-when-mismatch
+@vindex backup-by-copying-when-privileged-mismatch
+@cindex file ownership, and backup
+@cindex backup, and user-id
+  The choice of renaming or copying is controlled by four variables.
+Renaming is the default choice.  If the variable
+@code{backup-by-copying} is non-@code{nil}, copying is used.  Otherwise,
+if the variable @code{backup-by-copying-when-linked} is non-@code{nil},
+then copying is used for files that have multiple names, but renaming
+may still be used when the file being edited has only one name.  If the
+variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then
+copying is used if renaming would cause the file's owner or group to
+change.  @code{backup-by-copying-when-mismatch} is @code{t} by default
+if you start Emacs as the superuser.  The fourth variable,
+@code{backup-by-copying-when-privileged-mismatch}, gives the highest
+numeric user-id for which @code{backup-by-copying-when-mismatch} will be
+forced on.  This is useful when low-numbered user-ids are assigned to
+special system users, such as @code{root}, @code{bin}, @code{daemon},
+etc., which must maintain ownership of files.
+
+  When a file is managed with a version control system (@pxref{Version
+Control}), Emacs does not normally make backups in the usual way for
+that file.  But check-in and check-out are similar in some ways to
+making backups.  One unfortunate similarity is that these operations
+typically break hard links, disconnecting the file name you visited from
+any alternate names for the same file.  This has nothing to do with
+Emacs---the version control system does it.
+
+@node Customize Save
+@subsection Customizing Saving of Files
+
+@vindex require-final-newline
+  If the value of the variable @code{require-final-newline} is
+@code{t}, saving or writing a file silently puts a newline at the end
+if there isn't already one there.  If the value is @code{visit}, Emacs
+adds a newline at the end of any file that doesn't have one, just
+after it visits the file.  (This marks the buffer as modified, and you
+can undo it.)  If the value is @code{visit-save}, that means to add
+newlines both on visiting and on saving.  If the value is @code{nil},
+Emacs leaves the end of the file unchanged; if it's neither @code{nil}
+nor @code{t}, Emacs asks you whether to add a newline.  The default is
+@code{nil}.
+
+@vindex mode-require-final-newline
+  Many major modes are designed for specific kinds of files that are
+always supposed to end in newlines.  These major modes set the
+variable @code{require-final-newline} according to
+@code{mode-require-final-newline}.  By setting the latter variable,
+you can control how these modes handle final newlines.
+
+@vindex write-region-inhibit-fsync
+  When Emacs saves a file, it invokes the @code{fsync} system call to
+force the data immediately out to disk.  This is important for safety
+if the system crashes or in case of power outage.  However, it can be
+disruptive on laptops using power saving, because it requires the disk
+to spin up each time you save a file.  Setting
+@code{write-region-inhibit-fsync} to a non-@code{nil} value disables
+this synchronization.  Be careful---this means increased risk of data
+loss.
+
+@node Interlocking
+@subsection Protection against Simultaneous Editing
+
+@cindex file dates
+@cindex simultaneous editing
+  Simultaneous editing occurs when two users visit the same file, both
+make changes, and then both save them.  If nobody were informed that
+this was happening, whichever user saved first would later find that his
+changes were lost.
+
+  On some systems, Emacs notices immediately when the second user starts
+to change the file, and issues an immediate warning.  On all systems,
+Emacs checks when you save the file, and warns if you are about to
+overwrite another user's changes.  You can prevent loss of the other
+user's work by taking the proper corrective action instead of saving the
+file.
+
+@findex ask-user-about-lock
+@cindex locking files
+  When you make the first modification in an Emacs buffer that is
+visiting a file, Emacs records that the file is @dfn{locked} by you.
+(It does this by creating a symbolic link in the same directory with a
+different name.)  Emacs removes the lock when you save the changes.  The
+idea is that the file is locked whenever an Emacs buffer visiting it has
+unsaved changes.
+
+@cindex collision
+  If you begin to modify the buffer while the visited file is locked by
+someone else, this constitutes a @dfn{collision}.  When Emacs detects a
+collision, it asks you what to do, by calling the Lisp function
+@code{ask-user-about-lock}.  You can redefine this function for the sake
+of customization.  The standard definition of this function asks you a
+question and accepts three possible answers:
+
+@table @kbd
+@item s
+Steal the lock.  Whoever was already changing the file loses the lock,
+and you gain the lock.
+@item p
+Proceed.  Go ahead and edit the file despite its being locked by someone else.
+@item q
+Quit.  This causes an error (@code{file-locked}), and the buffer
+contents remain unchanged---the modification you were trying to make
+does not actually take place.
+@end table
+
+  Note that locking works on the basis of a file name; if a file has
+multiple names, Emacs does not realize that the two names are the same file
+and cannot prevent two users from editing it simultaneously under different
+names.  However, basing locking on names means that Emacs can interlock the
+editing of new files that will not really exist until they are saved.
+
+  Some systems are not configured to allow Emacs to make locks, and
+there are cases where lock files cannot be written.  In these cases,
+Emacs cannot detect trouble in advance, but it still can detect the
+collision when you try to save a file and overwrite someone else's
+changes.
+
+  If Emacs or the operating system crashes, this may leave behind lock
+files which are stale, so you may occasionally get warnings about
+spurious collisions.  When you determine that the collision is spurious,
+just use @kbd{p} to tell Emacs to go ahead anyway.
+
+  Every time Emacs saves a buffer, it first checks the last-modification
+date of the existing file on disk to verify that it has not changed since the
+file was last visited or saved.  If the date does not match, it implies
+that changes were made in the file in some other way, and these changes are
+about to be lost if Emacs actually does save.  To prevent this, Emacs
+displays a warning message and asks for confirmation before saving.
+Occasionally you will know why the file was changed and know that it does
+not matter; then you can answer @kbd{yes} and proceed.  Otherwise, you should
+cancel the save with @kbd{C-g} and investigate the situation.
+
+  The first thing you should do when notified that simultaneous editing
+has already taken place is to list the directory with @kbd{C-u C-x C-d}
+(@pxref{Directories}).  This shows the file's current author.  You
+should attempt to contact him to warn him not to continue editing.
+Often the next step is to save the contents of your Emacs buffer under a
+different name, and use @code{diff} to compare the two files.@refill
+
+@node File Shadowing
+@subsection Shadowing Files
+@cindex shadow files
+@cindex file shadows
+@findex shadow-initialize
+
+@table @kbd
+@item M-x shadow-initialize
+Set up file shadowing.
+@item M-x shadow-define-literal-group
+Declare a single file to be shared between sites.
+@item M-x shadow-define-regexp-group
+Make all files that match each of a group of files be shared between hosts.
+@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
+Define a shadow file cluster @var{name}.
+@item M-x shadow-copy-files
+Copy all pending shadow files.
+@item M-x shadow-cancel
+Cancel the instruction to shadow some files.
+@end table
+
+You can arrange to keep identical @dfn{shadow} copies of certain files
+in more than one place---possibly on different machines.  To do this,
+first you must set up a @dfn{shadow file group}, which is a set of
+identically-named files shared between a list of sites.  The file
+group is permanent and applies to further Emacs sessions as well as
+the current one.  Once the group is set up, every time you exit Emacs,
+it will copy the file you edited to the other files in its group.  You
+can also do the copying without exiting Emacs, by typing @kbd{M-x
+shadow-copy-files}.
+
+To set up a shadow file group, use @kbd{M-x
+shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}.
+See their documentation strings for further information.
+
+Before copying a file to its shadows, Emacs asks for confirmation.
+You can answer ``no'' to bypass copying of this file, this time.  If
+you want to cancel the shadowing permanently for a certain file, use
+@kbd{M-x shadow-cancel} to eliminate or change the shadow file group.
+
+A @dfn{shadow cluster} is a group of hosts that share directories, so
+that copying to or from one of them is sufficient to update the file
+on all of them.  Each shadow cluster has a name, and specifies the
+network address of a primary host (the one we copy files to), and a
+regular expression that matches the host names of all the other hosts
+in the cluster.  You can define a shadow cluster with @kbd{M-x
+shadow-define-cluster}.
+
+@node Time Stamps
+@subsection Updating Time Stamps Automatically
+@cindex time stamps
+@cindex modification dates
+@cindex locale, date format
+
+You can arrange to put a time stamp in a file, so that it will be updated
+automatically each time you edit and save the file.  The time stamp
+has to be in the first eight lines of the file, and you should
+insert it like this:
+
+@example
+Time-stamp: <>
+@end example
+
+@noindent
+or like this:
+
+@example
+Time-stamp: " "
+@end example
+
+@findex time-stamp
+  Then add the hook function @code{time-stamp} to the hook
+@code{before-save-hook}; that hook function will automatically update
+the time stamp, inserting the current date and time when you save the
+file.  You can also use the command @kbd{M-x time-stamp} to update the
+time stamp manually.  For other customizations, see the Custom group
+@code{time-stamp}.  Note that non-numeric fields in the time stamp are
+formatted according to your locale setting (@pxref{Environment}).
+
+@node Reverting
+@section Reverting a Buffer
+@findex revert-buffer
+@cindex drastic changes
+@cindex reread a file
+
+  If you have made extensive changes to a file and then change your mind
+about them, you can get rid of them by reading in the previous version
+of the file.  To do this, use @kbd{M-x revert-buffer}, which operates on
+the current buffer.  Since reverting a buffer unintentionally could lose
+a lot of work, you must confirm this command with @kbd{yes}.
+
+  @code{revert-buffer} tries to position point in such a way that, if
+the file was edited only slightly, you will be at approximately the
+same piece of text after reverting as before.  However, if you have made
+drastic changes, point may wind up in a totally different piece of text.
+
+  Reverting marks the buffer as ``not modified'' until another change is
+made.
+
+  Some kinds of buffers whose contents reflect data bases other than files,
+such as Dired buffers, can also be reverted.  For them, reverting means
+recalculating their contents from the appropriate data base.  Buffers
+created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
+reports an error when asked to do so.
+
+@vindex revert-without-query
+  When you edit a file that changes automatically and frequently---for
+example, a log of output from a process that continues to run---it may be
+useful for Emacs to revert the file without querying you, whenever you
+visit the file again with @kbd{C-x C-f}.
+
+  To request this behavior, set the variable @code{revert-without-query}
+to a list of regular expressions.  When a file name matches one of these
+regular expressions, @code{find-file} and @code{revert-buffer} will
+revert it automatically if it has changed---provided the buffer itself
+is not modified.  (If you have edited the text, it would be wrong to
+discard your changes.)
+
+@cindex Global Auto-Revert mode
+@cindex mode, Global Auto-Revert
+@cindex Auto-Revert mode
+@cindex mode, Auto-Revert
+@findex global-auto-revert-mode
+@findex auto-revert-mode
+@findex auto-revert-tail-mode
+
+  You may find it useful to have Emacs revert files automatically when
+they change.  Three minor modes are available to do this.
+
+  @kbd{M-x global-auto-revert-mode} enables Global Auto-Revert mode,
+which periodically checks all file buffers and reverts when the
+corresponding file has changed.  @kbd{M-x auto-revert-mode} enables a
+local version, Auto-Revert mode, which applies only to the current
+buffer.
+
+  You can use Auto-Revert mode to ``tail'' a file such as a system
+log, so that changes made to that file by other programs are
+continuously displayed.  To do this, just move the point to the end of
+the buffer, and it will stay there as the file contents change.
+However, if you are sure that the file will only change by growing at
+the end, use Auto-Revert Tail mode instead
+(@code{auto-revert-tail-mode}).  It is more efficient for this.
+
+@vindex auto-revert-interval
+  The variable @code{auto-revert-interval} controls how often to check
+for a changed file.  Since checking a remote file is too slow, these
+modes do not check or revert remote files.
+
+  @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that
+visit files under version control.
+
+@ifnottex
+@include arevert-xtra.texi
+@end ifnottex
+
+@node Auto Save
+@section Auto-Saving: Protection Against Disasters
+@cindex Auto Save mode
+@cindex mode, Auto Save
+@cindex crashes
+
+  Emacs saves all the visited files from time to time (based on counting
+your keystrokes) without being asked.  This is called @dfn{auto-saving}.
+It prevents you from losing more than a limited amount of work if the
+system crashes.
+
+  When Emacs determines that it is time for auto-saving, it considers
+each buffer, and each is auto-saved if auto-saving is enabled for it
+and it has been changed since the last time it was auto-saved.  The
+message @samp{Auto-saving...} is displayed in the echo area during
+auto-saving, if any files are actually auto-saved.  Errors occurring
+during auto-saving are caught so that they do not interfere with the
+execution of commands you have been typing.
+
+@menu
+* Files: Auto Save Files.       The file where auto-saved changes are
+                                  actually made until you save the file.
+* Control: Auto Save Control.   Controlling when and how often to auto-save.
+* Recover::		        Recovering text from auto-save files.
+@end menu
+
+@node Auto Save Files
+@subsection Auto-Save Files
+
+  Auto-saving does not normally save in the files that you visited, because
+it can be very undesirable to save a program that is in an inconsistent
+state when you have made half of a planned change.  Instead, auto-saving
+is done in a different file called the @dfn{auto-save file}, and the
+visited file is changed only when you request saving explicitly (such as
+with @kbd{C-x C-s}).
+
+  Normally, the auto-save file name is made by appending @samp{#} to the
+front and rear of the visited file name.  Thus, a buffer visiting file
+@file{foo.c} is auto-saved in a file @file{#foo.c#}.  Most buffers that
+are not visiting files are auto-saved only if you request it explicitly;
+when they are auto-saved, the auto-save file name is made by appending
+@samp{#} to the front and rear of buffer name, then
+adding digits and letters at the end for uniqueness.  For
+example, the @samp{*mail*} buffer in which you compose messages to be
+sent might be auto-saved in a file named @file{#*mail*#704juu}.  Auto-save file
+names are made this way unless you reprogram parts of Emacs to do
+something different (the functions @code{make-auto-save-file-name} and
+@code{auto-save-file-name-p}).  The file name to be used for auto-saving
+in a buffer is calculated when auto-saving is turned on in that buffer.
+
+@cindex auto-save for remote files
+@vindex auto-save-file-name-transforms
+  The variable @code{auto-save-file-name-transforms} allows a degree
+of control over the auto-save file name.  It lets you specify a series
+of regular expressions and replacements to transform the auto save
+file name.  The default value puts the auto-save files for remote
+files (@pxref{Remote Files}) into the temporary file directory on the
+local machine.
+
+  When you delete a substantial part of the text in a large buffer, auto
+save turns off temporarily in that buffer.  This is because if you
+deleted the text unintentionally, you might find the auto-save file more
+useful if it contains the deleted text.  To reenable auto-saving after
+this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
+auto-save-mode}.
+
+@vindex auto-save-visited-file-name
+  If you want auto-saving to be done in the visited file rather than
+in a separate auto-save file, set the variable
+@code{auto-save-visited-file-name} to a non-@code{nil} value.  In this
+mode, there is no real difference between auto-saving and explicit
+saving.
+
+@vindex delete-auto-save-files
+  A buffer's auto-save file is deleted when you save the buffer in its
+visited file.  (You can inhibit this by setting the variable
+@code{delete-auto-save-files} to @code{nil}.)  Changing the visited
+file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames
+any auto-save file to go with the new visited name.
+
+@node Auto Save Control
+@subsection Controlling Auto-Saving
+
+@vindex auto-save-default
+@findex auto-save-mode
+  Each time you visit a file, auto-saving is turned on for that file's
+buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
+in batch mode; @pxref{Entering Emacs}).  The default for this variable is
+@code{t}, so auto-saving is the usual practice for file-visiting buffers.
+Auto-saving can be turned on or off for any existing buffer with the
+command @kbd{M-x auto-save-mode}.  Like other minor mode commands, @kbd{M-x
+auto-save-mode} turns auto-saving on with a positive argument, off with a
+zero or negative argument; with no argument, it toggles.
+
+@vindex auto-save-interval
+  Emacs does auto-saving periodically based on counting how many characters
+you have typed since the last time auto-saving was done.  The variable
+@code{auto-save-interval} specifies how many characters there are between
+auto-saves.  By default, it is 300.  Emacs doesn't accept values that are
+too small: if you customize @code{auto-save-interval} to a value less
+than 20, Emacs will behave as if the value is 20.
+
+@vindex auto-save-timeout
+  Auto-saving also takes place when you stop typing for a while.  The
+variable @code{auto-save-timeout} says how many seconds Emacs should
+wait before it does an auto save (and perhaps also a garbage
+collection).  (The actual time period is longer if the current buffer is
+long; this is a heuristic which aims to keep out of your way when you
+are editing long buffers, in which auto-save takes an appreciable amount
+of time.)  Auto-saving during idle periods accomplishes two things:
+first, it makes sure all your work is saved if you go away from the
+terminal for a while; second, it may avoid some auto-saving while you
+are actually typing.
+
+  Emacs also does auto-saving whenever it gets a fatal error.  This
+includes killing the Emacs job with a shell command such as @samp{kill
+%emacs}, or disconnecting a phone line or network connection.
+
+@findex do-auto-save
+  You can request an auto-save explicitly with the command @kbd{M-x
+do-auto-save}.
+
+@node Recover
+@subsection Recovering Data from Auto-Saves
+
+@findex recover-file
+  You can use the contents of an auto-save file to recover from a loss
+of data with the command @kbd{M-x recover-file @key{RET} @var{file}
+@key{RET}}.  This visits @var{file} and then (after your confirmation)
+restores the contents from its auto-save file @file{#@var{file}#}.
+You can then save with @kbd{C-x C-s} to put the recovered text into
+@var{file} itself.  For example, to recover file @file{foo.c} from its
+auto-save file @file{#foo.c#}, do:@refill
+
+@example
+M-x recover-file @key{RET} foo.c @key{RET}
+yes @key{RET}
+C-x C-s
+@end example
+
+  Before asking for confirmation, @kbd{M-x recover-file} displays a
+directory listing describing the specified file and the auto-save file,
+so you can compare their sizes and dates.  If the auto-save file
+is older, @kbd{M-x recover-file} does not offer to read it.
+
+@findex recover-session
+  If Emacs or the computer crashes, you can recover all the files you
+were editing from their auto save files with the command @kbd{M-x
+recover-session}.  This first shows you a list of recorded interrupted
+sessions.  Move point to the one you choose, and type @kbd{C-c C-c}.
+
+  Then @code{recover-session} asks about each of the files that were
+being edited during that session, asking whether to recover that file.
+If you answer @kbd{y}, it calls @code{recover-file}, which works in its
+normal fashion.  It shows the dates of the original file and its
+auto-save file, and asks once again whether to recover that file.
+
+  When @code{recover-session} is done, the files you've chosen to
+recover are present in Emacs buffers.  You should then save them.  Only
+this---saving them---updates the files themselves.
+
+@vindex auto-save-list-file-prefix
+  Emacs records information about interrupted sessions for later
+recovery in files named
+@file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}.  All
+of this name except the @file{@var{pid}-@var{hostname}} part comes
+from the value of @code{auto-save-list-file-prefix}.  You can record
+sessions in a different place by customizing that variable.  If you
+set @code{auto-save-list-file-prefix} to @code{nil} in your
+@file{.emacs} file, sessions are not recorded for recovery.
+
+@node File Aliases
+@section File Name Aliases
+@cindex symbolic links (visiting)
+@cindex hard links (visiting)
+
+  Symbolic links and hard links both make it possible for several file
+names to refer to the same file.  Hard links are alternate names that
+refer directly to the file; all the names are equally valid, and no one
+of them is preferred.  By contrast, a symbolic link is a kind of defined
+alias: when @file{foo} is a symbolic link to @file{bar}, you can use
+either name to refer to the file, but @file{bar} is the real name, while
+@file{foo} is just an alias.  More complex cases occur when symbolic
+links point to directories.
+
+@vindex find-file-existing-other-name
+@vindex find-file-suppress-same-file-warnings
+
+  Normally, if you visit a file which Emacs is already visiting under
+a different name, Emacs displays a message in the echo area and uses
+the existing buffer visiting that file.  This can happen on systems
+that support hard or symbolic links, or if you use a long file name on
+a system that truncates long file names, or on a case-insensitive file
+system.  You can suppress the message by setting the variable
+@code{find-file-suppress-same-file-warnings} to a non-@code{nil}
+value.  You can disable this feature entirely by setting the variable
+@code{find-file-existing-other-name} to @code{nil}: then if you visit
+the same file under two different names, you get a separate buffer for
+each file name.
+
+@vindex find-file-visit-truename
+@cindex truenames of files
+@cindex file truenames
+  If the variable @code{find-file-visit-truename} is non-@code{nil},
+then the file name recorded for a buffer is the file's @dfn{truename}
+(made by replacing all symbolic links with their target names), rather
+than the name you specify.  Setting @code{find-file-visit-truename} also
+implies the effect of @code{find-file-existing-other-name}.
+
+@node Version Control
+@section Version Control
+@cindex version control
+
+  @dfn{Version control systems} are packages that can record multiple
+versions of a source file, usually storing the unchanged parts of the
+file just once.  Version control systems also record history information
+such as the creation time of each version, who created it, and a
+description of what was changed in that version.
+
+  The Emacs version control interface is called VC.  Its commands work
+with different version control systems---currently, it supports CVS,
+GNU Arch, RCS, Meta-CVS, Subversion, and SCCS.  Of these, the GNU
+project distributes CVS, GNU Arch, and RCS; we recommend that you use
+either CVS or GNU Arch for your projects, and RCS for individual
+files.  We also have free software to replace SCCS, known as CSSC; if
+you are using SCCS and don't want to make the incompatible change to
+RCS or CVS, you can switch to CSSC.
+
+  VC is enabled by default in Emacs.  To disable it, set the
+customizable variable @code{vc-handled-backends} to @code{nil}
+@iftex
+(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Customizing VC}).
+@end ifnottex
+
+
+@menu
+* Introduction to VC::  How version control works in general.
+* VC Mode Line::        How the mode line shows version control status.
+* Basic VC Editing::    How to edit a file under version control.
+* Old Versions::        Examining and comparing old versions.
+* Secondary VC Commands::    The commands used a little less frequently.
+* Branches::            Multiple lines of development.
+@ifnottex
+* Remote Repositories:: Efficient access to remote CVS servers.
+* Snapshots::           Sets of file versions treated as a unit.
+* Miscellaneous VC::    Various other commands and features of VC.
+* Customizing VC::      Variables that change VC's behavior.
+@end ifnottex
+@end menu
+
+@node Introduction to VC
+@subsection Introduction to Version Control
+
+  VC allows you to use a version control system from within Emacs,
+integrating the version control operations smoothly with editing.  VC
+provides a uniform interface to version control, so that regardless of
+which version control system is in use, you can use it the same way.
+
+  This section provides a general overview of version control, and
+describes the version control systems that VC supports.  You can skip
+this section if you are already familiar with the version control system
+you want to use.
+
+@menu
+* Why Version Control?:: Understanding the problems it addresses
+* Version Systems::  Supported version control back-end systems.
+* VC Concepts::      Words and concepts related to version control.
+* Types of Log File::    The per-file VC log in contrast to the ChangeLog.
+@end menu
+
+@node Why Version Control?
+@subsubsection Understanding the problems it addresses
+
+  Version control systems provide you with three important capabilities: 
+reversibility, concurrency, and history.
+
+  The most basic capability you get from a version-control system is
+reversibility, the ability to back up to a saved, known-good state when
+you discover that some modification you did was a mistake or a bad idea.
+
+  Version-control systems also support concurrency, the ability to
+have many people modifying the same collection of code or documents
+knowing that conflicting modifications can be detected and resolved.
+
+  Version-control systems give you the capability to attach a history
+to your data, explanatory comments about the intention behind each 
+change to it.  Even for a programmer working solo change histories
+are an important aid to memory; for a multi-person project they 
+become a vitally important form of communication among developers.
+
+@node Version Systems
+@subsubsection Supported Version Control Systems
+
+@cindex back end (version control)
+  VC currently works with six different version control systems or
+``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS.
+
+@cindex CVS
+  CVS is a free version control system that is used for the majority
+of free software projects today.  It allows concurrent multi-user
+development either locally or over the network.  Some of its
+shortcomings, corrected by newer systems such as GNU Arch, are that it
+lacks atomic commits or support for renaming files.  VC supports all
+basic editing operations under CVS, but for some less common tasks you
+still need to call CVS from the command line.  Note also that before
+using CVS you must set up a repository, which is a subject too complex
+to treat here.
+
+@cindex GNU Arch
+@cindex Arch
+  GNU Arch is a new version control system that is designed for
+distributed work.  It differs in many ways from old well-known
+systems, such as CVS and RCS.  It supports different transports for
+interoperating between users, offline operations, and it has good
+branching and merging features.  It also supports atomic commits, and
+history of file renaming and moving.  VC does not support all
+operations provided by GNU Arch, so you must sometimes invoke it from
+the command line, or use a specialized module.
+
+@cindex RCS
+  RCS is the free version control system around which VC was initially
+built.  The VC commands are therefore conceptually closest to RCS.
+Almost everything you can do with RCS can be done through VC.  You
+cannot use RCS over the network though, and it only works at the level
+of individual files, rather than projects.  You should use it if you
+want a simple, yet reliable tool for handling individual files.
+
+@cindex SVN
+@cindex Subversion
+  Subversion is a free version control system designed to be similar
+to CVS but without CVS's problems.  Subversion supports atomic commits,
+and versions directories, symbolic links, meta-data, renames, copies,
+and deletes.  It can be used via http or via its own protocol.
+
+@cindex MCVS
+@cindex Meta-CVS
+  Meta-CVS is another attempt to solve problems arising in CVS.  It
+supports directory structure versioning, improved branching and
+merging, and use of symbolic links and meta-data in repositories.
+
+@cindex SCCS
+  SCCS is a proprietary but widely used version control system.  In
+terms of capabilities, it is the weakest of the six that VC supports.
+VC compensates for certain features missing in SCCS (snapshots, for
+example) by implementing them itself, but some other VC features, such
+as multiple branches, are not available with SCCS.  Since SCCS is
+non-free, not respecting its users freedom, you should not use it;
+use its free replacement CSSC instead.  But you should use CSSC only
+if for some reason you cannot use RCS, or one of the higher-level
+systems such as CVS or GNU Arch.
+
+In the following, we discuss mainly RCS, SCCS and CVS.  Nearly
+everything said about CVS applies to GNU Arch, Subversion and Meta-CVS
+as well.
+
+@node VC Concepts
+@subsubsection Concepts of Version Control
+
+@cindex master file
+@cindex registered file
+   When a file is under version control, we also say that it is
+@dfn{registered} in the version control system.  Each registered file
+has a corresponding @dfn{master file} which represents the file's
+present state plus its change history---enough to reconstruct the
+current version or any earlier version.  Usually the master file also
+records a @dfn{log entry} for each version, describing in words what was
+changed in that version.
+
+@cindex work file
+@cindex checking out files
+  The file that is maintained under version control is sometimes called
+the @dfn{work file} corresponding to its master file.  You edit the work
+file and make changes in it, as you would with an ordinary file.  (With
+SCCS and RCS, you must @dfn{lock} the file before you start to edit it.)
+After you are done with a set of changes, you @dfn{check the file in},
+which records the changes in the master file, along with a log entry for
+them.
+
+  To go beyond these basic concepts, you will need to understand three
+ways in which version-control systems can differ from each other.  They
+can be locking or merging; they can be file-based or changeset-based;
+and they can be centralized or decentralized.  VC handles all these
+choices, but they lead to differing behaviors which you will need
+to understand as you use it.
+
+@cindex locking versus merging
+  A version control system typically has some mechanism to coordinate
+between users who want to change the same file.  One method is
+@dfn{locking} (analogous to the locking that Emacs uses to detect
+simultaneous editing of a file, but distinct from it).  In a locking
+system, such as SCCS, you must @dfn{lock} a file before you start to
+edit it.  The other method is @dfn{merging}; the system tries to 
+merge your changes with other people's changes when you check them in.
+
+  With version control locking, work files are normally read-only so
+that you cannot change them.  You ask the version control system to make
+a work file writable for you by locking it; only one user can do
+this at any given time.  When you check in your changes, that unlocks
+the file, making the work file read-only again.  This allows other users
+to lock the file to make further changes.
+
+  By contrast, a merging system lets each user check out and modify a
+work file at any time.  When you check in a a file, the system will
+attempt to merge your changes with any others checked into the
+repository since you checked out the file.
+
+  Both locking and merging systems can have problems when multiple users
+try to modify the same file at the same time.  Locking systems have
+@dfn{lock conflicts}; a user may try to check a file out and be unable
+to because it is locked.  In merging systems, @dfn{merge conflicts}
+happen when you check in a change to a file that conflicts with a change
+checked in by someone else after your checkout.  Both kinds of conflict
+have to be resolved by human judgment and communication.
+
+  SCCS always uses locking. RCS is lock-based by default but can be told
+to operate in a merging style.  CVS is merge-based by default but can
+be told to operate in a locking mode.  Most later version-control
+systems, such as Subversion and GNU Arch, have been fundamentally
+merging-based rather than locking-based.  This is because experience
+has shown that the merging-based approach is generally superior to
+the locking one, both in convenience to developers and in minimizing
+the number and severity of conflicts that actually occur.
+
+   While it is rather unlikely that anyone will ever again build a
+fundamentally locking-based rather than merging-based version-control
+system in the future, merging-based version-systems sometimes have locks
+retrofitted onto them for reasons having nothing to do with technology.
+@footnote{Usually the control-freak instincts of managers.}  For this
+reason, and to support older systems still in use, VC mode supports
+both locking and merging version control and tries to hide the differences
+between them as much as possible.
+
+@cindex files versus changesets.
+  On SCCS, RCS, CVS, and other early version-control systems, checkins
+and other operations are @dfn{file-based}; each file has its own
+@dfn{master file} with its own comment- and revision history separate
+from that of all other files in the system.  Later systems, beginning
+with Subversion, are @dfn{changeset-based}; a checkin may include
+changes to several files and that change set is treated as a unit by the
+system.  Any comment associated with the change doesn't belong to any
+one file, but is attached to the changeset itself.
+
+  Changeset-based version control is in general both more flexible and
+more powerful than file-based version control; usually, when a change to
+multiple files has to be backed out, it's good to be able to easily
+identify and remove all of it.
+
+@cindex centralized vs. decentralized
+  Early version-control systems were designed around a @dfn{centralized}
+model in which each project has only one repository used by all
+developers.  SCCS, RCS, CVS, and Subversion share this kind of model.
+It has two important problems. One is that a single repository is a
+single point of failure---if the repository server is down all work
+stops.  The other is that you need to be connected live to the server to
+do checkins and checkouts; if you're offline, you can't work.
+
+  Newer version-control systems like GNU Arch are @dfn{decentralized}.
+A project may have several different repositories, and these systems
+support a sort of super-merge between repositories that tries to
+reconcile their change histories.  At the limit, each developer has
+his/her own repository, and repository merges replace checkin/commit
+operations.
+
+  VC's job is to help you manage the traffic between your personal
+workfiles and a repository.  Whether that repository is a single master
+or one of a network of peer repositories is not something VC has to care
+about.  Thus, the difference between a centralized and a decentralized
+version-control system is invisible to VC mode.
+
+@iftex
+(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{CVS Options}).
+@end ifnottex
+
+
+@node Types of Log File
+@subsubsection Types of Log File
+@cindex types of log file
+@cindex log File, types of
+@cindex version control log
+
+  Projects that use a revision control system can have @emph{two}
+types of log for changes.  One is the per-file log maintained by the
+revision control system: each time you check in a change, you must
+fill out a @dfn{log entry} for the change (@pxref{Log Buffer}).  This
+kind of log is called the @dfn{version control log}, also the
+@dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS log}.
+
+  The other kind of log is the file @file{ChangeLog} (@pxref{Change
+Log}).  It provides a chronological record of all changes to a large
+portion of a program---typically one directory and its subdirectories.
+A small program would use one @file{ChangeLog} file; a large program
+may well merit a @file{ChangeLog} file in each major directory.
+@xref{Change Log}.
+
+  A project maintained with version control can use just the per-file
+log, or it can use both kinds of logs.  It can handle some files one
+way and some files the other way.  Each project has its policy, which
+you should follow.
+
+  When the policy is to use both, you typically want to write an entry
+for each change just once, then put it into both logs.  You can write
+the entry in @file{ChangeLog}, then copy it to the log buffer when you
+check in the change.  Or you can write the entry in the log buffer
+while checking in the change, and later use the @kbd{C-x v a} command
+to copy it to @file{ChangeLog}
+@iftex
+(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Change Logs and VC}).
+@end ifnottex
+
+
+@node VC Mode Line
+@subsection Version Control and the Mode Line
+
+  When you visit a file that is under version control, Emacs indicates
+this on the mode line.  For example, @samp{RCS-1.3} says that RCS is
+used for that file, and the current version is 1.3.
+
+  The character between the back-end name and the version number
+indicates the version control status of the file.  @samp{-} means that
+the work file is not locked (if locking is in use), or not modified (if
+locking is not in use).  @samp{:} indicates that the file is locked, or
+that it is modified.  If the file is locked by some other user (for
+instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
+
+@vindex auto-revert-check-vc-info
+  When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
+under version control, it updates the version control information in
+the mode line.  However, Auto Revert mode may not properly update this
+information if the version control status changes without changes to
+the work file, from outside the current Emacs session.  If you set
+@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
+the version control status information every
+@code{auto-revert-interval} seconds, even if the work file itself is
+unchanged.  The resulting CPU usage depends on the version control
+system, but is usually not excessive.
+
+@node Basic VC Editing
+@subsection Basic Editing under Version Control
+
+  The principal VC command is an all-purpose command that performs
+either locking or check-in, depending on the situation.
+
+@table @kbd
+@itemx C-x v v
+Perform the next logical version control operation on this file.
+@end table
+
+@findex vc-next-action
+@kindex C-x v v
+  The precise action of this command depends on the state of the file,
+and whether the version control system uses locking or not.  SCCS and
+RCS normally use locking; CVS normally does not use locking.
+
+@findex vc-toggle-read-only
+@kindex C-x C-q @r{(Version Control)}
+  As a special convenience that is particularly useful for files with
+locking, you can let Emacs check a file in or out whenever you change
+its read-only flag.  This means, for example, that you cannot
+accidentally edit a file without properly checking it out first.  To
+achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only}
+in your @file{~/.emacs} file.  (@xref{Init Rebinding}.)
+
+@menu
+* VC with Locking::     RCS in its default mode, SCCS, and optionally CVS.
+* Without Locking::     Without locking: default mode for CVS.
+* Advanced C-x v v::    Advanced features available with a prefix argument.
+* Log Buffer::          Features available in log entry buffers.
+@end menu
+
+@node VC with Locking
+@subsubsection Basic Version Control with Locking
+
+  If locking is used for the file (as with SCCS, and RCS in its default
+mode), @kbd{C-x v v} can either lock a file or check it in:
+
+@itemize @bullet
+@item
+If the file is not locked, @kbd{C-x v v} locks it, and
+makes it writable so that you can change it.
+
+@item
+If the file is locked by you, and contains changes, @kbd{C-x v v} checks
+in the changes.  In order to do this, it first reads the log entry
+for the new version.  @xref{Log Buffer}.
+
+@item
+If the file is locked by you, but you have not changed it since you
+locked it, @kbd{C-x v v} releases the lock and makes the file read-only
+again.
+
+@item
+If the file is locked by some other user, @kbd{C-x v v} asks you whether
+you want to ``steal the lock'' from that user.  If you say yes, the file
+becomes locked by you, but a message is sent to the person who had
+formerly locked the file, to inform him of what has happened.
+@end itemize
+
+  These rules also apply when you use CVS in locking mode, except
+that there is no such thing as stealing a lock.
+
+@node Without Locking
+@subsubsection Basic Version Control without Locking
+
+  When there is no locking---the default for CVS---work files are always
+writable; you do not need to do anything before you begin to edit a
+file.  The status indicator on the mode line is @samp{-} if the file is
+unmodified; it flips to @samp{:} as soon as you save any changes in the
+work file.
+
+  Here is what @kbd{C-x v v} does when using CVS:
+
+@itemize @bullet
+@item
+If some other user has checked in changes into the master file, Emacs
+asks you whether you want to merge those changes into your own work
+file.  You must do this before you can check in your own changes.  (To
+pick up any recent changes from the master file @emph{without} trying
+to commit your own changes, type @kbd{C-x v m @key{RET}}.)
+@xref{Merging}.
+
+@item
+If there are no new changes in the master file, but you have made
+modifications in your work file, @kbd{C-x v v} checks in your changes.
+In order to do this, it first reads the log entry for the new version.
+@xref{Log Buffer}.
+
+@item
+If the file is not modified, the @kbd{C-x v v} does nothing.
+@end itemize
+
+  These rules also apply when you use RCS in the mode that does not
+require locking, except that automatic merging of changes from the
+master file is not implemented.  Unfortunately, this means that nothing
+informs you if another user has checked in changes in the same file
+since you began editing it, and when this happens, his changes will be
+effectively removed when you check in your version (though they will
+remain in the master file, so they will not be entirely lost).  You must
+therefore verify that the current version is unchanged, before you
+check in your changes.  We hope to eliminate this risk and provide
+automatic merging with RCS in a future Emacs version.
+
+  In addition, locking is possible with RCS even in this mode, although
+it is not required; @kbd{C-x v v} with an unmodified file locks the
+file, just as it does with RCS in its normal (locking) mode.
+
+@node Advanced C-x v v
+@subsubsection Advanced Control in @kbd{C-x v v}
+
+@cindex version number to check in/out
+  When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
+C-x v v}), it still performs the next logical version control
+operation, but accepts additional arguments to specify precisely how
+to do the operation.
+
+@itemize @bullet
+@item
+If the file is modified (or locked), you can specify the version
+number to use for the new version that you check in.  This is one way
+to create a new branch (@pxref{Branches}).
+
+@item
+If the file is not modified (and unlocked), you can specify the
+version to select; this lets you start working from an older version,
+or on another branch.  If you do not enter any version, that takes you
+to the highest version on the current branch; therefore @kbd{C-u C-x
+v v @key{RET}} is a convenient way to get the latest version of a file from
+the repository.
+
+@item
+@cindex specific version control system
+Instead of the version number, you can also specify the name of a
+version control system.  This is useful when one file is being managed
+with two version control systems at the same time
+@iftex
+(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
+Features}).
+@end iftex
+@ifnottex
+(@pxref{Local Version Control}).
+@end ifnottex
+
+@end itemize
+
+@node Log Buffer
+@subsubsection Features of the Log Entry Buffer
+
+  When you check in changes, @kbd{C-x v v} first reads a log entry.  It
+pops up a buffer called @samp{*VC-Log*} for you to enter the log entry.
+
+  Sometimes the @samp{*VC-Log*} buffer contains default text when you enter it,
+typically the last log message entered.  If it does, mark and point
+are set around the entire contents of the buffer so that it is easy to
+kill the contents of the buffer with @kbd{C-w}.
+
+@findex log-edit-insert-changelog
+  If you work by writing entries in the @file{ChangeLog}
+(@pxref{Change Log}) and then commit the change under revision
+control, you can generate the Log Edit text from the ChangeLog using
+@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}).  This looks for
+entries for the file(s) concerned in the top entry in the ChangeLog
+and uses those paragraphs as the log text.  This text is only inserted
+if the top entry was made under your user name on the current date.
+@iftex
+@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features},
+@end iftex
+@ifnottex
+@xref{Change Logs and VC},
+@end ifnottex
+for the opposite way of working---generating ChangeLog entries from
+the revision control log.
+
+  In the @samp{*VC-Log*} buffer, @kbd{C-c C-f} (@kbd{M-x
+log-edit-show-files}) shows the list of files to be committed in case
+you need to check that.  (This can be a list of more than one file if
+you use VC Dired mode or PCL-CVS.
+@iftex
+@xref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features},
+@end iftex
+@ifnottex
+@xref{VC Dired Mode},
+@end ifnottex
+and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs
+Front-End to CVS}.)
+
+  When you have finished editing the log message, type @kbd{C-c C-c} to
+exit the buffer and commit the change.
+
+  To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that
+buffer.  You can switch buffers and do other editing.  As long as you
+don't try to check in another file, the entry you were editing remains
+in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any
+time to complete the check-in.
+
+  If you change several source files for the same reason, it is often
+convenient to specify the same log entry for many of the files.  To do
+this, use the history of previous log entries.  The commands @kbd{M-n},
+@kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the
+minibuffer history commands (except that these versions are used outside
+the minibuffer).
+
+@vindex vc-log-mode-hook
+  Each time you check in a file, the log entry buffer is put into VC Log
+mode, which involves running two hooks: @code{text-mode-hook} and
+@code{vc-log-mode-hook}.  @xref{Hooks}.
+
+@node Old Versions
+@subsection Examining And Comparing Old Versions
+
+  One of the convenient features of version control is the ability
+to examine any version of a file, or compare two versions.
+
+@table @kbd
+@item C-x v ~ @var{version} @key{RET}
+Examine version @var{version} of the visited file, in a buffer of its
+own.
+
+@item C-x v =
+Compare the current buffer contents with the master version from which
+you started editing.
+
+@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
+Compare the specified two versions of @var{file}.
+
+@item C-x v g
+Display the file with per-line version information and using colors.
+@end table
+
+@findex vc-version-other-window
+@kindex C-x v ~
+  To examine an old version in its entirety, visit the file and then type
+@kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}).
+This puts the text of version @var{version} in a file named
+@file{@var{filename}.~@var{version}~}, and visits it in its own buffer
+in a separate window.  (In RCS, you can also select an old version
+and create a branch from it.  @xref{Branches}.)
+
+@findex vc-diff
+@kindex C-x v =
+  It is usually more convenient to compare two versions of the file,
+with the command @kbd{C-x v =} (@code{vc-diff}).  Plain @kbd{C-x v =}
+compares the current buffer contents (saving them in the file if
+necessary) with the master version from which you started editing the
+file (this is not necessarily the latest version of the file).
+@kbd{C-u C-x v =}, with a numeric argument, reads a file name and two
+version numbers, then compares those versions of the specified file.
+Both forms display the output in a special buffer in another window.
+
+  You can specify a checked-in version by its number; an empty input
+specifies the current contents of the work file (which may be different
+from all the checked-in versions).  You can also specify a snapshot name
+@iftex
+(@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features})
+@end iftex
+@ifnottex
+(@pxref{Snapshots})
+@end ifnottex
+instead of one or both version numbers.
+
+  If you supply a directory name instead of the name of a registered
+file, this command compares the two specified versions of all registered
+files in that directory and its subdirectories.
+
+@vindex vc-diff-switches
+@vindex vc-rcs-diff-switches
+  @kbd{C-x v =} works by running a variant of the @code{diff} utility
+designed to work with the version control system in use.  When you
+invoke @code{diff} this way, in addition to the options specified by
+@code{diff-switches} (@pxref{Comparing Files}), it receives those
+specified by @code{vc-diff-switches}, plus those specified for the
+specific back end by @code{vc-@var{backend}-diff-switches}.  For
+instance, when the version control back end is RCS, @code{diff} uses
+the options in @code{vc-rcs-diff-switches}.  The
+@samp{vc@dots{}diff-switches} variables are @code{nil} by default.
+
+  The buffer produced by @kbd{C-x v =} supports the commands of
+Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
+@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always
+find the corresponding locations in the current work file.  (Older
+versions are not, in general, present as files on your disk.)
+
+@findex vc-annotate
+@kindex C-x v g
+  For some back ends, you can display the file @dfn{annotated} with
+per-line version information and using colors to enhance the visual
+appearance, with the command @kbd{M-x vc-annotate}.  It creates a new
+buffer (the ``annotate buffer'') displaying the file's text, with each
+part colored to show how old it is.  Text colored red is new, blue means
+old, and intermediate colors indicate intermediate ages.  By default,
+the color is scaled over the full range of ages, such that the oldest
+changes are blue, and the newest changes are red.
+
+  When you give a prefix argument to this command, it uses the
+minibuffer to read two arguments: which version number to display and
+annotate (instead of the current file contents), and the time span in
+days the color range should cover.  
+
+  From the annotate buffer, these and other color scaling options are
+available from the @samp{VC-Annotate} menu.  In this buffer, you can
+also use the following keys to browse the annotations of past revisions,
+view diffs, or view log entries:
+
+@table @kbd
+@item P
+Annotate the previous revision, that is to say, the revision before
+the one currently annotated.  A numeric prefix argument is a repeat
+count, so @kbd{C-u 10 P} would take you back 10 revisions.
+
+@item N
+Annotate the next revision---the one after the revision currently
+annotated.  A numeric prefix argument is a repeat count.
+
+@item J
+Annotate the revision indicated by the current line.
+
+@item A
+Annotate the revision before the one indicated by the current line.
+This is useful to see the state the file was in before the change on
+the current line was made.
+
+@item D
+Display the diff between the current line's revision and the previous
+revision.  This is useful to see what the current line's revision
+actually changed in the file.
+
+@item L
+Show the log of the current line's revision.  This is useful to see
+the author's description of the changes in the revision on the current
+line.
+
+@item W
+Annotate the workfile version--the one you are editing.  If you used
+@kbd{P} and @kbd{N} to browse to other revisions, use this key to
+return to your current version.
+@end table
+
+@node Secondary VC Commands
+@subsection The Secondary Commands of VC
+
+  This section explains the secondary commands of VC; those that you might
+use once a day.
+
+@menu
+* Registering::         Putting a file under version control.
+* VC Status::           Viewing the VC status of files.
+* VC Undo::             Canceling changes before or after check-in.
+@ifnottex
+* VC Dired Mode::       Listing files managed by version control.
+* VC Dired Commands::   Commands to use in a VC Dired buffer.
+@end ifnottex
+@end menu
+
+@node Registering
+@subsubsection Registering a File for Version Control
+
+@kindex C-x v i
+@findex vc-register
+  You can put any file under version control by simply visiting it, and
+then typing @w{@kbd{C-x v i}} (@code{vc-register}).
+
+@table @kbd
+@item C-x v i
+Register the visited file for version control.
+@end table
+
+  To register the file, Emacs must choose which version control system
+to use for it.  If the file's directory already contains files
+registered in a version control system, Emacs uses that system.  If
+there is more than one system in use for a directory, Emacs uses the
+one that appears first in @code{vc-handled-backends}
+@iftex
+(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Customizing VC}).
+@end ifnottex
+On the other hand, if there are no files already registered, Emacs uses
+the first system from @code{vc-handled-backends} that could register
+the file (for example, you cannot register a file under CVS if its
+directory is not already part of a CVS tree); with the default value
+of @code{vc-handled-backends}, this means that Emacs uses RCS in this
+situation.
+
+  If locking is in use, @kbd{C-x v i} leaves the file unlocked and
+read-only.  Type @kbd{C-x v v} if you wish to start editing it.  After
+registering a file with CVS, you must subsequently commit the initial
+version by typing @kbd{C-x v v}.  Until you do that, the version
+appears as @samp{@@@@} in the mode line.
+
+@vindex vc-default-init-version
+@cindex initial version number to register
+  The initial version number for a newly registered file is 1.1, by
+default.  You can specify a different default by setting the variable
+@code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric
+argument; then it reads the initial version number for this particular
+file using the minibuffer.
+
+@vindex vc-initial-comment
+  If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
+initial comment to describe the purpose of this source file.  Reading
+the initial comment works like reading a log entry (@pxref{Log Buffer}).
+
+@node VC Status
+@subsubsection VC Status Commands
+
+@table @kbd
+@item C-x v l
+Display version control state and change history.
+@end table
+
+@kindex C-x v l
+@findex vc-print-log
+  To view the detailed version control status and history of a file,
+type @kbd{C-x v l} (@code{vc-print-log}).  It displays the history of
+changes to the current file, including the text of the log entries.  The
+output appears in a separate window.  The point is centered at the
+revision of the file that is currently being visited.
+
+  In the change log buffer, you can use the following keys to move
+between the logs of revisions and of files, to view past revisions, and
+to view diffs:
+
+@table @kbd
+@item p
+Move to the previous revision-item in the buffer.  (Revision entries in the log
+buffer are usually in reverse-chronological order, so the previous
+revision-item usually corresponds to a newer revision.)  A numeric
+prefix argument is a repeat count.
+
+@item n
+Move to the next revision-item (which most often corresponds to the
+previous revision of the file).  A numeric prefix argument is a repeat
+count.
+
+@item P
+Move to the log of the previous file, when the logs of multiple files
+are in the log buffer
+@iftex
+(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{VC Dired Mode}).
+@end ifnottex
+Otherwise, just move to the beginning of the log.  A numeric prefix
+argument is a repeat count, so @kbd{C-u 10 P} would move backward 10
+files.
+
+@item N
+Move to the log of the next file, when the logs of multiple files are
+in the log buffer
+@iftex
+(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{VC Dired Mode}).
+@end ifnottex
+It also takes a numeric prefix argument as a repeat count.
+
+@item f
+Visit the revision indicated at the current line, like typing @kbd{C-x
+v ~} and specifying this revision's number (@pxref{Old Versions}).
+
+@item d
+Display the diff (@pxref{Comparing Files}) between the revision
+indicated at the current line and the next earlier revision.  This is
+useful to see what actually changed when the revision indicated on the
+current line was committed.
+@end table
+
+@node VC Undo
+@subsubsection Undoing Version Control Actions
+
+@table @kbd
+@item C-x v u
+Revert the buffer and the file to the version from which you started
+editing the file.
+
+@item C-x v c
+Remove the last-entered change from the master for the visited file.
+This undoes your last check-in.
+@end table
+
+@kindex C-x v u
+@findex vc-revert-buffer
+  If you want to discard your current set of changes and revert to the
+version from which you started editing the file, use @kbd{C-x v u}
+(@code{vc-revert-buffer}).  This leaves the file unlocked; if locking
+is in use, you must first lock the file again before you change it
+again.  @kbd{C-x v u} requires confirmation, unless it sees that you
+haven't made any changes with respect to the master version.
+
+  @kbd{C-x v u} is also the command to unlock a file if you lock it and
+then decide not to change it.
+
+@kindex C-x v c
+@findex vc-cancel-version
+  To cancel a change that you already checked in, use @kbd{C-x v c}
+(@code{vc-cancel-version}).  This command discards all record of the
+most recent checked-in version, but only if your work file corresponds
+to that version---you cannot use @kbd{C-x v c} to cancel a version
+that is not the latest on its branch.  @kbd{C-x v c} also offers to
+revert your work file and buffer to the previous version (the one that
+precedes the version that is deleted).
+
+  If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
+the file.  The no-revert option is useful when you have checked in a
+change and then discover a trivial error in it; you can cancel the
+erroneous check-in, fix the error, and check the file in again.
+
+  When @kbd{C-x v c} does not revert the buffer, it unexpands all
+version control headers in the buffer instead
+@iftex
+(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Version Headers}).
+@end ifnottex
+This is because the buffer no longer corresponds to any existing
+version.  If you check it in again, the check-in process will expand
+the headers properly for the new version number.
+
+  However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header
+automatically.  If you use that header feature, you have to unexpand it
+by hand---by deleting the entry for the version that you just canceled.
+
+  Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of
+work with it.  To help you be careful, this command always requires
+confirmation with @kbd{yes}.  Note also that this command is disabled
+under CVS, because canceling versions is very dangerous and discouraged
+with CVS.
+
+@ifnottex
+@c vc1-xtra.texi needs extra level of lowering.
+@lowersections
+@include vc1-xtra.texi
+@raisesections
+@end ifnottex
+
+@node Branches
+@subsection Multiple Branches of a File
+@cindex branch (version control)
+@cindex trunk (version control)
+
+  One use of version control is to maintain multiple ``current''
+versions of a file.  For example, you might have different versions of a
+program in which you are gradually adding various unfinished new
+features.  Each such independent line of development is called a
+@dfn{branch}.  VC allows you to create branches, switch between
+different branches, and merge changes from one branch to another.
+Please note, however, that branches are not supported for SCCS.
+
+  A file's main line of development is usually called the @dfn{trunk}.
+The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc.  At
+any such version, you can start an independent branch.  A branch
+starting at version 1.2 would have version number 1.2.1.1, and consecutive
+versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4,
+and so on.  If there is a second branch also starting at version 1.2, it
+would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
+
+@cindex head version
+  If you omit the final component of a version number, that is called a
+@dfn{branch number}.  It refers to the highest existing version on that
+branch---the @dfn{head version} of that branch.  The branches in the
+example above have branch numbers 1.2.1 and 1.2.2.
+
+@menu
+* Switching Branches::    How to get to another existing branch.
+* Creating Branches::     How to start a new branch.
+* Merging::               Transferring changes between branches.
+* Multi-User Branching::  Multiple users working at multiple branches
+                            in parallel.
+@end menu
+
+@node Switching Branches
+@subsubsection Switching between Branches
+
+  To switch between branches, type @kbd{C-u C-x v v} and specify the
+version number you want to select.  This version is then visited
+@emph{unlocked} (write-protected), so you can examine it before locking
+it.  Switching branches in this way is allowed only when the file is not
+locked.
+
+  You can omit the minor version number, thus giving only the branch
+number; this takes you to the head version on the chosen branch.  If you
+only type @key{RET}, Emacs goes to the highest version on the trunk.
+
+  After you have switched to any branch (including the main branch), you
+stay on it for subsequent VC commands, until you explicitly select some
+other branch.
+
+@node Creating Branches
+@subsubsection Creating New Branches
+
+  To create a new branch from a head version (one that is the latest in
+the branch that contains it), first select that version if necessary,
+lock it with @kbd{C-x v v}, and make whatever changes you want.  Then,
+when you check in the changes, use @kbd{C-u C-x v v}.  This lets you
+specify the version number for the new version.  You should specify a
+suitable branch number for a branch starting at the current version.
+For example, if the current version is 2.5, the branch number should be
+2.5.1, 2.5.2, and so on, depending on the number of existing branches at
+that point.
+
+  To create a new branch at an older version (one that is no longer the
+head of a branch), first select that version (@pxref{Switching
+Branches}), then lock it with @kbd{C-x v v}.  You'll be asked to
+confirm, when you lock the old version, that you really mean to create a
+new branch---if you say no, you'll be offered a chance to lock the
+latest version instead.
+
+  Then make your changes and type @kbd{C-x v v} again to check in a new
+version.  This automatically creates a new branch starting from the
+selected version.  You need not specially request a new branch, because
+that's the only way to add a new version at a point that is not the head
+of a branch.
+
+  After the branch is created, you ``stay'' on it.  That means that
+subsequent check-ins create new versions on that branch.  To leave the
+branch, you must explicitly select a different version with @kbd{C-u C-x
+v v}.  To transfer changes from one branch to another, use the merge
+command, described in the next section.
+
+@node Merging
+@subsubsection Merging Branches
+
+@cindex merging changes
+  When you have finished the changes on a certain branch, you will
+often want to incorporate them into the file's main line of development
+(the trunk).  This is not a trivial operation, because development might
+also have proceeded on the trunk, so that you must @dfn{merge} the
+changes into a file that has already been changed otherwise.  VC allows
+you to do this (and other things) with the @code{vc-merge} command.
+
+@table @kbd
+@item C-x v m (vc-merge)
+Merge changes into the work file.
+@end table
+
+@kindex C-x v m
+@findex vc-merge
+  @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
+into the current version of the work file.  It firsts asks you in the
+minibuffer where the changes should come from.  If you just type
+@key{RET}, Emacs merges any changes that were made on the same branch
+since you checked the file out (we call this @dfn{merging the news}).
+This is the common way to pick up recent changes from the repository,
+regardless of whether you have already changed the file yourself.
+
+  You can also enter a branch number or a pair of version numbers in
+the minibuffer.  Then @kbd{C-x v m} finds the changes from that
+branch, or the differences between the two versions you specified, and
+merges them into the current version of the current file.
+
+  As an example, suppose that you have finished a certain feature on
+branch 1.3.1.  In the meantime, development on the trunk has proceeded
+to version 1.5.  To merge the changes from the branch to the trunk,
+first go to the head version of the trunk, by typing @kbd{C-u C-x v v
+@key{RET}}.  Version 1.5 is now current.  If locking is used for the file,
+type @kbd{C-x v v} to lock version 1.5 so that you can change it.  Next,
+type @kbd{C-x v m 1.3.1 @key{RET}}.  This takes the entire set of changes on
+branch 1.3.1 (relative to version 1.3, where the branch started, up to
+the last version on the branch) and merges it into the current version
+of the work file.  You can now check in the changed file, thus creating
+version 1.6 containing the changes from the branch.
+
+  It is possible to do further editing after merging the branch, before
+the next check-in.  But it is usually wiser to check in the merged
+version, then lock it and make the further changes.  This will keep
+a better record of the history of changes.
+
+@cindex conflicts
+@cindex resolving conflicts
+  When you merge changes into a file that has itself been modified, the
+changes might overlap.  We call this situation a @dfn{conflict}, and
+reconciling the conflicting changes is called @dfn{resolving a
+conflict}.
+
+  Whenever conflicts occur during merging, VC detects them, tells you
+about them in the echo area, and asks whether you want help in merging.
+If you say yes, it starts an Ediff session (@pxref{Top,
+Ediff, Ediff, ediff, The Ediff Manual}).
+
+  If you say no, the conflicting changes are both inserted into the
+file, surrounded by @dfn{conflict markers}.  The example below shows how
+a conflict region looks; the file is called @samp{name} and the current
+master file version with user B's changes in it is 1.11.
+
+@c @w here is so CVS won't think this is a conflict.
+@smallexample
+@group
+@w{<}<<<<<< name
+  @var{User A's version}
+=======
+  @var{User B's version}
+@w{>}>>>>>> 1.11
+@end group
+@end smallexample
+
+@cindex vc-resolve-conflicts
+  Then you can resolve the conflicts by editing the file manually.  Or
+you can type @code{M-x vc-resolve-conflicts} after visiting the file.
+This starts an Ediff session, as described above.  Don't forget to
+check in the merged version afterwards.
+
+@node Multi-User Branching
+@subsubsection Multi-User Branching
+
+  It is often useful for multiple developers to work simultaneously on
+different branches of a file.  CVS allows this by default; for RCS, it
+is possible if you create multiple source directories.  Each source
+directory should have a link named @file{RCS} which points to a common
+directory of RCS master files.  Then each source directory can have its
+own choice of selected versions, but all share the same common RCS
+records.
+
+  This technique works reliably and automatically, provided that the
+source files contain RCS version headers
+@iftex
+(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Version Headers}).
+@end ifnottex
+The headers enable Emacs to be sure, at all times, which version
+number is present in the work file.
+
+  If the files do not have version headers, you must instead tell Emacs
+explicitly in each session which branch you are working on.  To do this,
+first find the file, then type @kbd{C-u C-x v v} and specify the correct
+branch number.  This ensures that Emacs knows which branch it is using
+during this particular editing session.
+
+@ifnottex
+@include vc2-xtra.texi
+@end ifnottex
+
+@node Directories
+@section File Directories
+
+@cindex file directory
+@cindex directory listing
+  The file system groups files into @dfn{directories}.  A @dfn{directory
+listing} is a list of all the files in a directory.  Emacs provides
+commands to create and delete directories, and to make directory
+listings in brief format (file names only) and verbose format (sizes,
+dates, and authors included).  Emacs also includes a directory browser
+feature called Dired; see @ref{Dired}.
+
+@table @kbd
+@item C-x C-d @var{dir-or-pattern} @key{RET}
+Display a brief directory listing (@code{list-directory}).
+@item C-u C-x C-d @var{dir-or-pattern} @key{RET}
+Display a verbose directory listing.
+@item M-x make-directory @key{RET} @var{dirname} @key{RET}
+Create a new directory named @var{dirname}.
+@item M-x delete-directory @key{RET} @var{dirname} @key{RET}
+Delete the directory named @var{dirname}.  It must be empty,
+or you get an error.
+@end table
+
+@findex list-directory
+@kindex C-x C-d
+  The command to display a directory listing is @kbd{C-x C-d}
+(@code{list-directory}).  It reads using the minibuffer a file name
+which is either a directory to be listed or a wildcard-containing
+pattern for the files to be listed.  For example,
+
+@example
+C-x C-d /u2/emacs/etc @key{RET}
+@end example
+
+@noindent
+lists all the files in directory @file{/u2/emacs/etc}.  Here is an
+example of specifying a file name pattern:
+
+@example
+C-x C-d /u2/emacs/src/*.c @key{RET}
+@end example
+
+  Normally, @kbd{C-x C-d} displays a brief directory listing containing
+just file names.  A numeric argument (regardless of value) tells it to
+make a verbose listing including sizes, dates, and owners (like
+@samp{ls -l}).
+
+@vindex list-directory-brief-switches
+@vindex list-directory-verbose-switches
+  The text of a directory listing is mostly obtained by running
+@code{ls} in an inferior process.  Two Emacs variables control the
+switches passed to @code{ls}: @code{list-directory-brief-switches} is
+a string giving the switches to use in brief listings (@code{"-CF"} by
+default), and @code{list-directory-verbose-switches} is a string
+giving the switches to use in a verbose listing (@code{"-l"} by
+default).
+
+@vindex directory-free-space-program
+@vindex directory-free-space-args
+  In verbose directory listings, Emacs adds information about the
+amount of free space on the disk that contains the directory.  To do
+this, it runs the program specified by
+@code{directory-free-space-program} with arguments
+@code{directory-free-space-args}.
+
+@node Comparing Files
+@section Comparing Files
+@cindex comparing files
+
+@findex diff
+@vindex diff-switches
+  The command @kbd{M-x diff} compares two files, displaying the
+differences in an Emacs buffer named @samp{*diff*}.  It works by
+running the @code{diff} program, using options taken from the variable
+@code{diff-switches}.  The value of @code{diff-switches} should be a
+string; the default is @code{"-c"} to specify a context diff.
+@xref{Top,, Diff, diff, Comparing and Merging Files}, for more
+information about @command{diff} output formats.
+
+@findex diff-backup
+  The command @kbd{M-x diff-backup} compares a specified file with its most
+recent backup.  If you specify the name of a backup file,
+@code{diff-backup} compares it with the source file that it is a backup
+of.
+
+@findex compare-windows
+  The command @kbd{M-x compare-windows} compares the text in the
+current window with that in the next window.  (For more information
+about windows in Emacs, @ref{Windows}.)  Comparison starts at point in
+each window, after pushing each initial point value on the mark ring
+in its respective buffer.  Then it moves point forward in each window,
+one character at a time, until it reaches characters that don't match.
+Then the command exits.
+
+  If point in the two windows is followed by non-matching text when
+the command starts, @kbd{M-x compare-windows} tries heuristically to
+advance up to matching text in the two windows, and then exits.  So if
+you use @kbd{M-x compare-windows} repeatedly, each time it either
+skips one matching range or finds the start of another.
+
+@vindex compare-ignore-case
+@vindex compare-ignore-whitespace
+  With a numeric argument, @code{compare-windows} ignores changes in
+whitespace.  If the variable @code{compare-ignore-case} is
+non-@code{nil}, the comparison ignores differences in case as well.
+If the variable @code{compare-ignore-whitespace} is non-@code{nil},
+@code{compare-windows} normally ignores changes in whitespace, and a
+prefix argument turns that off.
+
+@cindex Smerge mode
+@findex smerge-mode
+@cindex failed merges
+@cindex merges, failed
+@cindex comparing 3 files (@code{diff3})
+  You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor
+mode for editing output from the @command{diff3} program.  This is
+typically the result of a failed merge from a version control system
+``update'' outside VC, due to conflicting changes to a file.  Smerge
+mode provides commands to resolve conflicts by selecting specific
+changes.
+
+@iftex
+@xref{Emerge,,, emacs-xtra, Specialized Emacs Features},
+@end iftex
+@ifnottex
+@xref{Emerge},
+@end ifnottex
+for the Emerge facility, which provides a powerful interface for
+merging files.
+
+@node Diff Mode
+@section Diff Mode
+@cindex Diff mode
+@findex diff-mode
+@cindex patches, editing
+
+  Diff mode is used for the output of @kbd{M-x diff}; it is also
+useful for editing patches and comparisons produced by the
+@command{diff} program.  To select Diff mode manually, type @kbd{M-x
+diff-mode}.
+
+  One general feature of Diff mode is that manual edits to the patch
+automatically correct line numbers, including those in the hunk
+header, so that you can actually apply the edited patch.  Diff mode
+treats each hunk location as an ``error message,'' so that you can use
+commands such as @kbd{C-x '} to visit the corresponding source
+locations.  It also provides the following commands to navigate,
+manipulate and apply parts of patches:
+
+@table @kbd
+@item M-n
+Move to the next hunk-start (@code{diff-hunk-next}).
+
+@item M-p
+Move to the previous hunk-start (@code{diff-hunk-prev}).
+
+@item M-@}
+Move to the next file-start, in a multi-file patch
+(@code{diff-file-next}).
+
+@item M-@{
+Move to the previous file-start, in a multi-file patch
+(@code{diff-file-prev}).
+
+@item M-k
+Kill the hunk at point (@code{diff-hunk-kill}).
+
+@item M-K
+In a multi-file patch, kill the current file part.
+(@code{diff-file-kill}).
+
+@item C-c C-a
+Apply this hunk to its target file (@code{diff-apply-hunk}).  With a
+prefix argument of @kbd{C-u}, revert this hunk.
+
+@item C-c C-c
+Go to the source corresponding to this hunk (@code{diff-goto-source}).
+
+@item C-c C-e
+Start an Ediff session with the patch (@code{diff-ediff-patch}).
+@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
+
+@item C-c C-n
+Restrict the view to the current hunk (@code{diff-restrict-view}).
+@xref{Narrowing}.  With a prefix argument of @kbd{C-u}, restrict the
+view to the current patch of a multiple file patch.  To widen again,
+use @kbd{C-x n w}.
+
+@item C-c C-r
+Reverse the direction of comparison for the entire buffer
+(@code{diff-reverse-direction}).
+
+@item C-c C-s
+Split the hunk at point (@code{diff-split-hunk}).  This is for
+manually editing patches, and only works with the unified diff format.
+
+@item C-c C-u
+Convert the entire buffer to unified format
+(@code{diff-context->unified}).  With a prefix argument, convert
+unified format to context format.  In Transient Mark mode, when the
+mark is active, this command operates only on the region.
+
+@item C-c C-w
+Refine the current hunk so that it disregards changes in whitespace
+(@code{diff-refine-hunk}).
+@end table
+
+  @kbd{C-x 4 a} in Diff mode operates on behalf of the target file,
+but gets the function name from the patch itself.  @xref{Change Log}.
+This is useful for making log entries for functions that are deleted
+by the patch.
+
+@node Misc File Ops
+@section Miscellaneous File Operations
+
+  Emacs has commands for performing many other operations on files.
+All operate on one file; they do not accept wildcard file names.
+
+@findex view-file
+@cindex viewing
+@cindex View mode
+@cindex mode, View
+  @kbd{M-x view-file} allows you to scan or read a file by sequential
+screenfuls.  It reads a file name argument using the minibuffer.  After
+reading the file into an Emacs buffer, @code{view-file} displays the
+beginning.  You can then type @key{SPC} to scroll forward one windowful,
+or @key{DEL} to scroll backward.  Various other commands are provided
+for moving around in the file, but none for changing it; type @kbd{?}
+while viewing for a list of them.  They are mostly the same as normal
+Emacs cursor motion commands.  To exit from viewing, type @kbd{q}.
+The commands for viewing are defined by a special minor mode called View
+mode.
+
+  A related command, @kbd{M-x view-buffer}, views a buffer already present
+in Emacs.  @xref{Misc Buffer}.
+
+@kindex C-x i
+@findex insert-file
+  @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
+contents of the specified file into the current buffer at point,
+leaving point unchanged before the contents and the mark after them.
+
+@findex insert-file-literally
+  @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
+except the file is inserted ``literally'': it is treated as a sequence
+of @acronym{ASCII} characters with no special encoding or conversion,
+similar to the @kbd{M-x find-file-literally} command
+(@pxref{Visiting}).
+
+@findex write-region
+  @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
+copies the contents of the region into the specified file.  @kbd{M-x
+append-to-file} adds the text of the region to the end of the
+specified file.  @xref{Accumulating Text}.  The variable
+@code{write-region-inhibit-fsync} applies to these commands, as well
+as saving files; see @ref{Customize Save}.
+
+@findex delete-file
+@cindex deletion (of files)
+  @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
+command in the shell.  If you are deleting many files in one directory, it
+may be more convenient to use Dired (@pxref{Dired}).
+
+@findex rename-file
+  @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
+the minibuffer, then renames file @var{old} as @var{new}.  If the file name
+@var{new} already exists, you must confirm with @kbd{yes} or renaming is not
+done; this is because renaming causes the old meaning of the name @var{new}
+to be lost.  If @var{old} and @var{new} are on different file systems, the
+file @var{old} is copied and deleted.
+
+  If the argument @var{new} is just a directory name, the real new
+name is in that directory, with the same non-directory component as
+@var{old}.  For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET}
+renames @file{~/foo} to @file{/tmp/foo}.  The same rule applies to all
+the remaining commands in this section.  All of them ask for
+confirmation when the new file name already exists, too.
+
+@findex add-name-to-file
+@cindex hard links (creation)
+  The similar command @kbd{M-x add-name-to-file} is used to add an
+additional name to an existing file without removing its old name.
+The new name is created as a ``hard link'' to the existing file.
+The new name must belong on the same file system that the file is on.
+On MS-Windows, this command works only if the file resides in an NTFS
+file system.  On MS-DOS, it works by copying the file.
+
+@findex copy-file
+@cindex copying files
+  @kbd{M-x copy-file} reads the file @var{old} and writes a new file
+named @var{new} with the same contents.
+
+@findex make-symbolic-link
+@cindex symbolic links (creation)
+  @kbd{M-x make-symbolic-link} reads two file names @var{target} and
+@var{linkname}, then creates a symbolic link named @var{linkname},
+which points at @var{target}.  The effect is that future attempts to
+open file @var{linkname} will refer to whatever file is named
+@var{target} at the time the opening is done, or will get an error if
+the name @var{target} is nonexistent at that time.  This command does
+not expand the argument @var{target}, so that it allows you to specify
+a relative name as the target of the link.
+
+  Not all systems support symbolic links; on systems that don't
+support them, this command is not defined.
+
+@node Compressed Files
+@section Accessing Compressed Files
+@cindex compression
+@cindex uncompression
+@cindex Auto Compression mode
+@cindex mode, Auto Compression
+@pindex gzip
+
+  Emacs automatically uncompresses compressed files when you visit
+them, and automatically recompresses them if you alter them and save
+them.  Emacs recognizes compressed files by their file names.  File
+names ending in @samp{.gz} indicate a file compressed with
+@code{gzip}.  Other endings indicate other compression programs.
+
+  Automatic uncompression and compression apply to all the operations in
+which Emacs uses the contents of a file.  This includes visiting it,
+saving it, inserting its contents into a buffer, loading it, and byte
+compiling it.
+
+@findex auto-compression-mode
+@vindex auto-compression-mode
+  To disable this feature, type the command @kbd{M-x
+auto-compression-mode}.  You can disable it permanently by
+customizing the variable @code{auto-compression-mode}.
+
+@node File Archives
+@section File Archives
+@cindex mode, tar
+@cindex Tar mode
+@cindex file archives
+
+  A file whose name ends in @samp{.tar} is normally an @dfn{archive}
+made by the @code{tar} program.  Emacs views these files in a special
+mode called Tar mode which provides a Dired-like list of the contents
+(@pxref{Dired}).  You can move around through the list just as you
+would in Dired, and visit the subfiles contained in the archive.
+However, not all Dired commands are available in Tar mode.
+
+  If Auto Compression mode is enabled (@pxref{Compressed Files}), then
+Tar mode is used also for compressed archives---files with extensions
+@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}.
+
+  The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file
+into its own buffer.  You can edit it there, and if you save the
+buffer, the edited version will replace the version in the Tar buffer.
+@kbd{v} extracts a file into a buffer in View mode.  @kbd{o} extracts
+the file and displays it in another window, so you could edit the file
+and operate on the archive simultaneously.  @kbd{d} marks a file for
+deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in
+Dired.  @kbd{C} copies a file from the archive to disk and @kbd{R}
+renames a file within the archive.  @kbd{g} reverts the buffer from
+the archive on disk.
+
+  The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission
+bits, group, and owner, respectively.
+
+  If your display supports colors and the mouse, moving the mouse
+pointer across a file name highlights that file name, indicating that
+you can click on it.  Clicking @kbd{Mouse-2} on the highlighted file
+name extracts the file into a buffer and displays that buffer.
+
+  Saving the Tar buffer writes a new version of the archive to disk with
+the changes you made to the components.
+
+  You don't need the @code{tar} program to use Tar mode---Emacs reads
+the archives directly.  However, accessing compressed archives
+requires the appropriate uncompression program.
+
+@cindex Archive mode
+@cindex mode, archive
+@cindex @code{arc}
+@cindex @code{jar}
+@cindex @code{zip}
+@cindex @code{lzh}
+@cindex @code{zoo}
+@pindex arc
+@pindex jar
+@pindex zip
+@pindex lzh
+@pindex zoo
+@cindex Java class archives
+@cindex unzip archives
+  A separate but similar Archive mode is used for archives produced by
+the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and
+@code{zoo}, which have extensions corresponding to the program names.
+Archive mode also works for those @code{exe} files that are
+self-extracting executables.
+
+  The key bindings of Archive mode are similar to those in Tar mode,
+with the addition of the @kbd{m} key which marks a file for subsequent
+operations, and @kbd{M-@key{DEL}} which unmarks all the marked files.
+Also, the @kbd{a} key toggles the display of detailed file
+information, for those archive types where it won't fit in a single
+line.  Operations such as renaming a subfile, or changing its mode or
+owner, are supported only for some of the archive formats.
+
+  Unlike Tar mode, Archive mode runs the archiving program to unpack
+and repack archives.  Details of the program names and their options
+can be set in the @samp{Archive} Customize group.  However, you don't
+need these programs to look at the archive table of contents, only to
+extract or manipulate the subfiles in the archive.
+
+@node Remote Files
+@section Remote Files
+
+@cindex Tramp
+@cindex FTP
+@cindex remote file access
+  You can refer to files on other machines using a special file name
+syntax:
+
+@example
+@group
+/@var{host}:@var{filename}
+/@var{user}@@@var{host}:@var{filename}
+/@var{user}@@@var{host}#@var{port}:@var{filename}
+/@var{method}:@var{user}@@@var{host}:@var{filename}
+/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
+@end group
+@end example
+
+@noindent
+To carry out this request, Emacs uses either the FTP program or a
+remote-login program such as @command{ssh}, @command{rlogin}, or
+@command{telnet}.  You can always specify in the file name which
+method to use---for example,
+@file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas
+@file{/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}.
+When you don't specify a method in the file name, Emacs chooses
+the method as follows:
+
+@enumerate
+@item
+If the host name starts with @samp{ftp.} (with dot), then Emacs uses
+FTP.
+@item
+If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses
+FTP.
+@item
+Otherwise, Emacs uses @command{ssh}.
+@end enumerate
+
+@noindent
+Remote file access through FTP is handled by the Ange-FTP package, which
+is documented in the following.  Remote file access through the other
+methods is handled by the Tramp package, which has its own manual.
+@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}.
+
+When the Ange-FTP package is used, Emacs logs in through FTP using your
+user name or the name @var{user}.  It may ask you for a password from
+time to time; this is used for logging in on @var{host}.  The form using
+@var{port} allows you to access servers running on a non-default TCP
+port.
+
+@cindex backups for remote files
+@vindex ange-ftp-make-backup-files
+  If you want to disable backups for remote files, set the variable
+@code{ange-ftp-make-backup-files} to @code{nil}.
+
+  By default, the auto-save files (@pxref{Auto Save Files}) for remote
+files are made in the temporary file directory on the local machine.
+This is achieved using the variable @code{auto-save-file-name-transforms}.
+
+@cindex ange-ftp
+@vindex ange-ftp-default-user
+@cindex user name for remote file access
+  Normally, if you do not specify a user name in a remote file name,
+that means to use your own user name.  But if you set the variable
+@code{ange-ftp-default-user} to a string, that string is used instead.
+
+@cindex anonymous FTP
+@vindex ange-ftp-generate-anonymous-password
+  To visit files accessible by anonymous FTP, you use special user
+names @samp{anonymous} or @samp{ftp}.  Passwords for these user names
+are handled specially.  The variable
+@code{ange-ftp-generate-anonymous-password} controls what happens: if
+the value of this variable is a string, then that string is used as
+the password; if non-@code{nil} (the default), then the value of
+@code{user-mail-address} is used; if @code{nil}, then Emacs prompts
+you for a password as usual.
+
+@cindex firewall, and accessing remote files
+@cindex gateway, and remote file access with @code{ange-ftp}
+@vindex ange-ftp-smart-gateway
+@vindex ange-ftp-gateway-host
+  Sometimes you may be unable to access files on a remote machine
+because a @dfn{firewall} in between blocks the connection for security
+reasons.  If you can log in on a @dfn{gateway} machine from which the
+target files @emph{are} accessible, and whose FTP server supports
+gatewaying features, you can still use remote file names; all you have
+to do is specify the name of the gateway machine by setting the
+variable @code{ange-ftp-gateway-host}, and set
+@code{ange-ftp-smart-gateway} to @code{t}.  Otherwise you may be able
+to make remote file names work, but the procedure is complex.  You can
+read the instructions by typing @kbd{M-x finder-commentary @key{RET}
+ange-ftp @key{RET}}.
+
+@vindex file-name-handler-alist
+@cindex disabling remote files
+  You can entirely turn off the FTP file name feature by removing the
+entries @code{ange-ftp-completion-hook-function} and
+@code{ange-ftp-hook-function} from the variable
+@code{file-name-handler-alist}.  You can turn off the feature in
+individual cases by quoting the file name with @samp{/:} (@pxref{Quoted
+File Names}).
+
+@node Quoted File Names
+@section Quoted File Names
+
+@cindex quoting file names
+@cindex file names, quote special characters
+  You can @dfn{quote} an absolute file name to prevent special
+characters and syntax in it from having their special effects.
+The way to do this is to add @samp{/:} at the beginning.
+
+  For example, you can quote a local file name which appears remote, to
+prevent it from being treated as a remote file name.  Thus, if you have
+a directory named @file{/foo:} and a file named @file{bar} in it, you
+can refer to that file in Emacs as @samp{/:/foo:/bar}.
+
+  @samp{/:} can also prevent @samp{~} from being treated as a special
+character for a user's home directory.  For example, @file{/:/tmp/~hack}
+refers to a file whose name is @file{~hack} in directory @file{/tmp}.
+
+  Quoting with @samp{/:} is also a way to enter in the minibuffer a
+file name that contains @samp{$}.  In order for this to work, the
+@samp{/:} must be at the beginning of the minibuffer contents.  (You
+can also double each @samp{$}; see @ref{File Names with $}.)
+
+  You can also quote wildcard characters with @samp{/:}, for visiting.
+For example, @file{/:/tmp/foo*bar} visits the file
+@file{/tmp/foo*bar}.
+
+  Another method of getting the same result is to enter
+@file{/tmp/foo[*]bar}, which is a wildcard specification that matches
+only @file{/tmp/foo*bar}.  However, in many cases there is no need to
+quote the wildcard characters because even unquoted they give the
+right result.  For example, if the only file name in @file{/tmp} that
+starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar},
+then specifying @file{/tmp/foo*bar} will visit only
+@file{/tmp/foo*bar}.
+
+@node File Name Cache
+@section File Name Cache
+
+@cindex file name caching
+@cindex cache of file names
+@pindex find
+@kindex C-@key{TAB}
+@findex file-cache-minibuffer-complete
+  You can use the @dfn{file name cache} to make it easy to locate a
+file by name, without having to remember exactly where it is located.
+When typing a file name in the minibuffer, @kbd{C-@key{tab}}
+(@code{file-cache-minibuffer-complete}) completes it using the file
+name cache.  If you repeat @kbd{C-@key{tab}}, that cycles through the
+possible completions of what you had originally typed.  (However, note
+that the @kbd{C-@key{tab}} character cannot be typed on most text-only
+terminals.)
+
+  The file name cache does not fill up automatically.  Instead, you
+load file names into the cache using these commands:
+
+@findex file-cache-add-directory
+@table @kbd
+@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET}
+Add each file name in @var{directory} to the file name cache.
+@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET}
+Add each file name in @var{directory} and all of its nested
+subdirectories to the file name cache.
+@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET}
+Add each file name in @var{directory} and all of its nested
+subdirectories to the file name cache, using @command{locate} to find
+them all.
+@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET}
+Add each file name in each directory listed in @var{variable}
+to the file name cache.  @var{variable} should be a Lisp variable
+such as @code{load-path} or @code{exec-path}, whose value is a list
+of directory names.
+@item M-x file-cache-clear-cache @key{RET}
+Clear the cache; that is, remove all file names from it.
+@end table
+
+  The file name cache is not persistent: it is kept and maintained
+only for the duration of the Emacs session.  You can view the contents
+of the cache with the @code{file-cache-display} command.
+
+@node File Conveniences
+@section Convenience Features for Finding Files
+
+  In this section, we introduce some convenient facilities for finding
+recently-opened files, reading file names from a buffer, and viewing
+image files.
+
+@findex recentf-mode
+@vindex recentf-mode
+@findex recentf-save-list
+@findex recentf-edit-list
+  If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
+@samp{File} menu includes a submenu containing a list of recently
+opened files.  @kbd{M-x recentf-save-list} saves the current
+@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list}
+edits it.
+
+  The @kbd{M-x ffap} command generalizes @code{find-file} with more
+powerful heuristic defaults (@pxref{FFAP}), often based on the text at
+point.  Partial Completion mode offers other features extending
+@code{find-file}, which can be used with @code{ffap}.
+@xref{Completion Options}.
+
+@findex image-mode
+@findex image-toggle-display
+@cindex images, viewing
+  Visiting image files automatically selects Image mode.  This major
+mode allows you to toggle between displaying the file as an image in
+the Emacs buffer, and displaying its underlying text representation,
+using the command @kbd{C-c C-c} (@code{image-toggle-display}).  This
+works only when Emacs can display the specific image type.  If the
+displayed image is wider or taller than the frame, the usual point
+motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts
+of the image to be displayed.
+
+@findex thumbs-mode
+@findex mode, thumbs
+  See also the Image-Dired package (@pxref{Image-Dired}) for viewing
+images as thumbnails.
+
+@node Filesets
+@section Filesets
+@cindex filesets
+
+@findex filesets-init
+  If you regularly edit a certain group of files, you can define them
+as a @dfn{fileset}.  This lets you perform certain operations, such as
+visiting, @code{query-replace}, and shell commands on all the files
+at once.  To make use of filesets, you must first add the expression
+@code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}).
+This adds a @samp{Filesets} menu to the menu bar.
+
+@findex filesets-add-buffer
+@findex filesets-remove-buffer
+  The simplest way to define a fileset is by adding files to it one
+at a time.  To add a file to fileset @var{name}, visit the file and
+type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}.  If
+there is no fileset @var{name}, this creates a new one, which
+initially creates only the current file.  The command @kbd{M-x
+filesets-remove-buffer} removes the current file from a fileset.
+
+  You can also edit the list of filesets directly, with @kbd{M-x
+filesets-edit} (or by choosing @samp{Edit Filesets} from the
+@samp{Filesets} menu).  The editing is performed in a Customize buffer
+(@pxref{Easy Customization}).  Filesets need not be a simple list of
+files---you can also define filesets using regular expression matching
+file names.  Some examples of these more complicated filesets are
+shown in the Customize buffer.  Remember to select @samp{Save for
+future sessions} if you want to use the same filesets in future Emacs
+sessions.
+
+  You can use the command @kbd{M-x filesets-open} to visit all the
+files in a fileset, and @kbd{M-x filesets-close} to close them.  Use
+@kbd{M-x filesets-run-cmd} to run a shell command on all the files in
+a fileset.  These commands are also available from the @samp{Filesets}
+menu, where each existing fileset is represented by a submenu.
+
+@ignore
+   arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250
+@end ignore