[Emacs-diffs] Changes to emacs/man/files.texi [gnus-5_10-branch]

[Miles Bader]

Index: emacs/man/files.texi
diff -c /dev/null emacs/man/files.texi:1.89.2.1
*** /dev/null   Sat Sep  4 12:02:58 2004
--- emacs/man/files.texi        Sat Sep  4 12:01:15 2004
***************
*** 0 ****
--- 1,3241 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985,86,87,93,94,95,97,99, 2000, 2001, 2004
+ @c   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.
+ * 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.
+ * 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.
+ @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.
+ 
+   For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
+ the default directory is @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}.
+ 
+ @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 that is visited in that buffer.  
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.
+ 
+ @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 environment variables in file names
+ @cindex expansion of environment variables
+ @cindex @code{$} in file names
+   @anchor{File Names with address@hidden 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/address@hidden@}/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.
+ 
+ @cindex home directory shorthand
+   You can use the @file{~/} in a file name to mean your home directory,
+ or @address@hidden/} to mean the home directory of a user whose
+ login name is @code{user-id}.  (On DOS and Windows systems, where a user
+ doesn't have a home directory, Emacs substitutes @file{~/} with the
+ value of the environment variable @code{HOME}; see @ref{General
+ Variables}.)
+ 
+   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 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 address@hidden characters in file names if you set the
+ variable @code{file-name-coding-system} to a address@hidden value.
+ @xref{Specify Coding}.
+ 
+ @node Visiting
+ @section Visiting Files
+ @cindex visiting files
+ 
+ @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 copying 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
+ place permanent, 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 filenames; for more
+ about this, see @ref{Completion Options}.
+ 
+ @cindex file selection dialog
+   When Emacs is built with a suitable GUI toolkit, it pops up the
+ standard File Selection dialog of that toolkit instead of prompting for
+ the file name in the minibuffer.  On Unix and GNU/Linux platforms, Emacs
+ does that when built with LessTif and Motif toolkits; on MS-Windows, the
+ GUI version does that by default.
+ 
+   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 could not be created, or
+ cannot be read, 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 that the file itself has not changed
+ since you visited or saved it last.  If the file has changed, a warning
+ message is shown.  @xref{Interlocking,,Simultaneous Editing}.
+ 
+ @cindex maximum buffer size exceeded, error message
+   Since Emacs reads the visited file in its entirety, files whose size
+ is larger than the maximum Emacs buffer size (@pxref{Buffers}) cannot be
+ visited; if you try, Emacs will display an error message saying that the
+ maximum buffer size has been exceeded.
+ 
+ @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 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 delete,
+ look at, 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.  Wildcards include @samp{?},
+ @samp{*}, and @address@hidden sequences.  @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.
+ 
+   If you find a file which exists but cannot be read, @kbd{C-x C-f}
+ signals an error.
+ 
+ @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 address@hidden  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.
+ 
+ @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 as 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 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.
+ 
+ @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 precisely
+ equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
+ @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}.
+ 
+ @vindex require-final-newline
+   If the value of the variable @code{require-final-newline} is @code{t},
+ Emacs silently puts a newline at the end of any file that doesn't
+ already end in one, every time a file is saved or written.  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}.
+ 
+ @menu
+ * Backup::              How Emacs saves the old version of your file.
+ * 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 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.  @xref{General VC Options}.
+ 
+ @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}.
+ 
+   At your option, Emacs can keep either a single backup file or a series of
+ numbered backup files for each file that you edit.
+ 
+   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
+ * Names: Backup Names.                How backup files are named;
+                                 choosing single or numbered backup files.
+ * Deletion: Backup Deletion.  Emacs deletes excess numbered backups.
+ * Copying: Backup Copying.    Backups can be made by copying or renaming.
+ @end menu
+ 
+ @node Backup Names
+ @subsubsection Single or Numbered Backups
+ 
+   If you choose to have a single backup file (this is the default),
+ the backup file's 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.
+ 
+ @vindex version-control
+   The choice of single backup or numbered backups 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
+ 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 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 address@hidden, copying is used.  Otherwise,
+ if the variable @code{backup-by-copying-when-linked} is address@hidden,
+ 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 address@hidden, 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 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 address@hidden
+ 
+ @node File Shadowing
+ @subsection Shadowing Files
+ @cindex shadow files
+ @cindex file shadows
+ 
+ @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
+ @findex time-stamp
+ @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
+ 
+   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
+ @vindex auto-revert-interval
+ You may find it useful to have Emacs revert files automatically when
+ they change.  Two minor modes are available to do this.  In Global
+ Auto-Revert mode, Emacs periodically checks all file buffers and
+ reverts any when the corresponding file has changed.  The local
+ variant, Auto-Revert mode, applies only to buffers in which it was
+ activated.  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.
+ 
+ @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, each buffer is
+ considered, and is auto-saved if auto-saving is turned on 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 address@hidden 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.  To inhibit this, set 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 address@hidden (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 @address@hidden
+ 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 interrupted sessions for later recovery in files named
+ @file{~/.emacs.d/auto-save-list/address@hidden@var{hostname}}.  All
+ of this name except @address@hidden@var{hostname}} 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.
+ 
+   If you visit two names for the same file, normally Emacs makes
+ two different buffers, but it warns you about the situation.
+ 
+ @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 symbolic links, or if you use a long file name on a
+ system that truncates long file names.  You can suppress the message by
+ setting the variable @code{find-file-suppress-same-file-warnings} to a
+ address@hidden 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 address@hidden,
+ 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 three version control systems---RCS, CVS, and SCCS.  The GNU
+ project recommends RCS and CVS, which are free software and available
+ from the Free Software Foundation.  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}
+ (@pxref{Customizing VC}).
+ 
+ @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.
+ * 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 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
+ * 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 Version Systems
+ @subsubsection Supported Version Control Systems
+ 
+ @cindex RCS
+ @cindex back end (version control)
+   VC currently works with three different version control systems or
+ ``back ends'': RCS, CVS, and SCCS.
+ 
+   RCS is a free version control system that is available from the Free
+ Software Foundation.  It is perhaps the most mature of the supported
+ back ends, and the VC commands are conceptually closest to RCS.  Almost
+ everything you can do with RCS can be done through VC.
+ 
+ @cindex CVS
+   CVS is built on top of RCS, and extends the features of RCS, allowing
+ for more sophisticated release management, and concurrent multi-user
+ development.  VC supports 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 SCCS
+   SCCS is a proprietary but widely used version control system.  In
+ terms of capabilities, it is the weakest of the three 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.  You
+ should use SCCS only if for some reason you cannot use RCS.
+ 
+ @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.
+ 
+   With CVS, there are usually multiple work files corresponding to a
+ single master file---often each user has his own copy.  It is also
+ possible to use RCS in this way, but this is not the usual way to use
+ RCS.
+ 
+ @cindex locking and version control
+   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).  The other method
+ is 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.  SCCS always uses locking, and
+ RCS normally does.
+ 
+   The other alternative for RCS is to let each user modify the work file
+ at any time.  In this mode, locking is not required, but it is
+ permitted; check-in is still the way to record a new version.
+ 
+   CVS normally allows each user to modify his own copy of the work file
+ at any time, but requires merging with changes from other users at
+ check-in time.  However, CVS can also be set up to require locking.
+ (@pxref{CVS Options}).
+ 
+ @node Types of Log File
+ @subsubsection Types of Log File
+ @cindex types of log file
+ @cindex log File, types of
+ @cindex version control log
+ 
+ GNU projects under a revision control system generally possess
+ @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 change log file, typically a file called
+ @file{ChangeLog}.  It provides a chronological record of all changes
+ to a large portion of a program---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}.
+ 
+ When you use version control, you can use just the per-file log if you
+ wish, or you can use both kinds of logs.  When you use both, you
+ typically want to write just one entry for each change.  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} (@pxref{Change Logs and VC}).
+ 
+ @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}.
+ 
+ @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 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 (@pxref{Local
+ Version Control}).
+ @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.
+ When you are finished, type @kbd{C-c C-c} in the @samp{*VC-Log*} buffer.
+ That is when check-in really happens.
+ 
+   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 latest checked-in version
+ of the file.
+ 
+ @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 result of the CVS annotate command 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
+ @address@hidden@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 last checked-in 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
+ (@pxref{Snapshots}) 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 @address@hidden  For
+ instance, when the version control back end is RCS, @code{diff} uses
+ the options in @code{vc-rcs-diff-switches}.  The
+ @address@hidden variables are @code{nil} by default.
+ 
+   Unlike the @kbd{M-x diff} command, @kbd{C-x v =} does not try to
+ locate the changes in the old and new versions.  This is because
+ normally one or both versions do not exist as files when you compare
+ them; they exist only in the records of the master file.
+ @xref{Comparing Files}, for more information about @kbd{M-x diff}.
+ 
+ @findex vc-annotate
+ @kindex C-x v g
+   For CVS-controlled files, you can display the result of the CVS
+ annotate command, using colors to enhance the visual appearance.  Use
+ the command @kbd{M-x vc-annotate} to do this.  It creates a new buffer
+ to display file's text, colored to show how old each part is.  Text
+ colored red is new, blue means old, and intermediate colors indicate
+ intermediate ages.  By default, the time scale is 360 days, so that
+ everything more than one year old is shown in blue.
+ 
+   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 a stretch factor
+ for the time scale.  A stretch factor of 0.1 means that the color
+ range from red to blue spans the past 36 days instead of 360 days.  A
+ stretch factor greater than 1 means the color range spans more than a
+ year.
+ 
+ From the annotate buffer, you can use the following keys to browse the
+ annotations of past revisions, view diffs, or view log entries:
+ 
+ @itemize @bullet
+ 
+ @item
+ Pressing @kbd{P} annotates the previous revision.  It also takes a
+ numeric prefix argument, so for example @kbd{C-u 10 P} would take you
+ back 10 revisions.
+ 
+ @item
+ Pressing @kbd{N} annotates the next revision.  It also takes a numeric
+ prefix argument, so for example @kbd{C-u 10 N} would take you forward
+ 10 revisions.
+ 
+ @item
+ Pressing @kbd{J} annotates the revision at line (as denoted by the
+ version number on the same line).
+ 
+ @item
+ Pressing @kbd{A} annotates the revision previous to line (as denoted
+ by the version number on the same line).  This is useful to see the
+ state the file was in before the change on the current line was made.
+ 
+ @item
+ Pressing @kbd{D} shows the diff of the revision at line with its
+ previous revision.  This is useful to see what actually changed when
+ the revision denoted on the current line was committed.
+ 
+ @item
+ Pressing @kbd{L} shows the log of the revision at line.  This is
+ useful to see the author's description of the changes that occurred
+ when the revision denoted on the current line was committed.
+ 
+ @item
+ Pressing @kbd{W} annotates the workfile (most up to date) version.  If
+ you used @kbd{P} and @kbd{N} to browse to other revisions, use this
+ key to return to the latest version.
+ @end itemize
+ 
+ @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.
+ * VC Dired Mode::       Listing files managed by version control.
+ * VC Dired Commands::   Commands to use in a VC Dired buffer.
+ @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 @address@hidden 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} (@pxref{Customizing VC}).
+ 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 if there are any files under RCS control, CVS if
+ there are any files under CVS, SCCS if any files are under SCCS, or
+ RCS as the ultimate default.
+ 
+   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}.
+ 
+ @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 address@hidden, @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.
+ 
+ @node VC Undo
+ @subsubsection Undoing Version Control Actions
+ 
+ @table @kbd
+ @item C-x v u
+ Revert the buffer and the file to the last checked-in version.
+ 
+ @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
+ last version checked in, 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 since the
+ last checked-in 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.  @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 (@pxref{Version Headers}).
+ 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 @address@hidden 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.
+ 
+ @node VC Dired Mode
+ @subsubsection Dired under VC
+ 
+ @cindex PCL-CVS
+ @pindex cvs
+ @cindex CVS Dired Mode
+   The VC Dired Mode described here works with all the version control
+ systems that VC supports.  Another more powerful facility, designed
+ specifically for CVS, is called PCL-CVS.  @xref{Top, , About PCL-CVS,
+ pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
+ 
+ @kindex C-x v d
+ @findex vc-directory
+   When you are working on a large program, it is often useful to find
+ out which files have changed within an entire directory tree, or to view
+ the status of all files under version control at once, and to perform
+ version control operations on collections of files.  You can use the
+ command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing
+ that includes only files relevant for version control.
+ 
+ @vindex vc-dired-terse-display
+   @kbd{C-x v d} creates a buffer which uses VC Dired Mode.  This looks
+ much like an ordinary Dired buffer (@pxref{Dired}); however, normally it
+ shows only the noteworthy files (those locked or not up-to-date).  This
+ is called @dfn{terse display}.  If you set the variable
+ @code{vc-dired-terse-display} to @code{nil}, then VC Dired shows all
+ relevant files---those managed under version control, plus all
+ subdirectories (@dfn{full display}).  The command @kbd{v t} in a VC
+ Dired buffer toggles between terse display and full display (@pxref{VC
+ Dired Commands}).
+ 
+ @vindex vc-dired-recurse
+   By default, VC Dired produces a recursive listing of noteworthy or
+ relevant files at or below the given directory.  You can change this by
+ setting the variable @code{vc-dired-recurse} to @code{nil}; then VC
+ Dired shows only the files in the given directory.
+ 
+   The line for an individual file shows the version control state in the
+ place of the hard link count, owner, group, and size of the file.  If
+ the file is unmodified, in sync with the master file, the version
+ control state shown is blank.  Otherwise it consists of text in
+ parentheses.  Under RCS and SCCS, the name of the user locking the file
+ is shown; under CVS, an abbreviated version of the @samp{cvs status}
+ output is used.  Here is an example using RCS:
+ 
+ @smallexample
+ @group
+   /home/jim/project:
+ 
+   -rw-r--r-- (jim)      Apr  2 23:39 file1
+   -r--r--r--            Apr  5 20:21 file2
+ @end group
+ @end smallexample
+ 
+ @noindent
+ The files @samp{file1} and @samp{file2} are under version control,
+ @samp{file1} is locked by user jim, and @samp{file2} is unlocked.
+ 
+   Here is an example using CVS:
+ 
+ @smallexample
+ @group
+   /home/joe/develop:
+ 
+   -rw-r--r-- (modified) Aug  2  1997 file1.c
+   -rw-r--r--            Apr  4 20:09 file2.c
+   -rw-r--r-- (merge)    Sep 13  1996 file3.c
+ @end group
+ @end smallexample
+ 
+   Here @samp{file1.c} is modified with respect to the repository, and
+ @samp{file2.c} is not.  @samp{file3.c} is modified, but other changes
+ have also been checked in to the repository---you need to merge them
+ with the work file before you can check it in.
+ 
+ @vindex vc-directory-exclusion-list
+   When VC Dired displays subdirectories (in the ``full'' display mode),
+ it omits some that should never contain any files under version control.
+ By default, this includes Version Control subdirectories such as
+ @samp{RCS} and @samp{CVS}; you can customize this by setting the
+ variable @code{vc-directory-exclusion-list}.
+ 
+   You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in
+ ordinary Dired, that allows you to specify additional switches for the
+ @samp{ls} command.
+ 
+ @node VC Dired Commands
+ @subsubsection VC Dired Commands
+ 
+   All the usual Dired commands work normally in VC Dired mode, except
+ for @kbd{v}, which is redefined as the version control prefix.  You can
+ invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by
+ typing @kbd{v =}, or @kbd{v l}, and so on.  Most of these commands apply
+ to the file name on the current line.
+ 
+   The command @kbd{v v} (@code{vc-next-action}) operates on all the
+ marked files, so that you can lock or check in several files at once.
+ If it operates on more than one file, it handles each file according to
+ its current state; thus, it might lock one file, but check in another
+ file.  This could be confusing; it is up to you to avoid confusing
+ behavior by marking a set of files that are in a similar state.
+ 
+   If any files call for check-in, @kbd{v v} reads a single log entry,
+ then uses it for all the files being checked in.  This is convenient for
+ registering or checking in several files at once, as part of the same
+ change.
+ 
+ @findex vc-dired-toggle-terse-mode
+ @findex vc-dired-mark-locked
+   You can toggle between terse display (only locked files, or files not
+ up-to-date) and full display at any time by typing @kbd{v t}
+ (@code{vc-dired-toggle-terse-mode}).  There is also a special command
+ @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently
+ locked (or, with CVS, all files not up-to-date).  Thus, typing @kbd{* l
+ t k} is another way to delete from the buffer all files except those
+ currently locked.
+ 
+ @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 only supported for RCS at the
+ moment.
+ 
+   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 (@pxref{Version Headers}).  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.
+ 
+ @node Remote Repositories
+ @subsection Remote Repositories
+ @cindex remote repositories (CVS)
+ 
+   A common way of using CVS is to set up a central CVS repository on
+ some Internet host, then have each developer check out a personal
+ working copy of the files on his local machine.  Committing changes to
+ the repository, and picking up changes from other users into one's own
+ working area, then works by direct interactions with the CVS server.
+ 
+   One difficulty is that access to the CVS server is often slow, and
+ that developers might need to work off-line as well.  VC is designed
+ to reduce the amount of network interaction necessary.
+ 
+ @menu
+ * Version Backups::        Keeping local copies of repository versions.
+ * Local Version Control::  Using another version system for local editing.
+ @end menu
+ 
+ @node Version Backups
+ @subsubsection Version Backups
+ @cindex version backups
+ 
+ @cindex automatic version backups
+   When VC sees that the CVS repository for a file is on a remote
+ machine, it automatically makes local backups of unmodified versions
+ of the address@hidden version backups}.  This means that you
+ can compare the file to the repository version (@kbd{C-x v =}), or
+ revert to that version (@kbd{C-x v u}), without any network
+ interactions.
+ 
+   The local copy of the unmodified file is called a @dfn{version
+ backup} to indicate that it corresponds exactly to a version that is
+ stored in the repository.  Note that version backups are not the same
+ as ordinary Emacs backup files (@pxref{Backup}).  But they follow a
+ similar naming convention.
+ 
+   For a file that comes from a remote CVS repository, VC makes a
+ version backup whenever you save the first changes to the file, and
+ removes it after you have committed your modified version to the
+ repository. You can disable the making of automatic version backups by
+ setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}).
+ 
+ @cindex manual version backups
+   The name of the automatic version backup for version @var{version}
+ of file @var{file} is @address@hidden@var{version}.~}.  This is
+ almost the same as the name used by @kbd{C-x v ~} (@pxref{Old
+ Versions}), the only difference being the additional dot (@samp{.})
+ after the version number.  This similarity is intentional, because
+ both kinds of files store the same kind of information.  The file made
+ by @kbd{C-x v ~} acts as a @dfn{manual version backup}.
+ 
+   All the VC commands that operate on old versions of a file can use
+ both kinds of version backups.  For instance, @kbd{C-x v ~} uses
+ either an automatic or a manual version backup, if possible, to get
+ the contents of the version you request.  Likewise, @kbd{C-x v =} and
+ @kbd{C-x v u} use either an automatic or a manual version backup, if
+ one of them exists, to get the contents of a version to compare or
+ revert to.  If you changed a file outside of Emacs, so that no
+ automatic version backup was created for the previous text, you can
+ create a manual backup of that version using @kbd{C-x v ~}, and thus
+ obtain the benefit of the local copy for Emacs commands.
+ 
+   The only difference in Emacs's handling of manual and automatic
+ version backups, once they exist, is that Emacs deletes automatic
+ version backups when you commit to the repository.  By contrast,
+ manual version backups remain until you delete them.
+ 
+ @node Local Version Control
+ @subsubsection Local Version Control
+ @cindex local version control
+ @cindex local back end (version control)
+ 
+ When you make many changes to a file that comes from a remote
+ repository, it can be convenient to have version control on your local
+ machine as well.  You can then record intermediate versions, revert to
+ a previous state, etc., before you actually commit your changes to the
+ remote server.
+ 
+ VC lets you do this by putting a file under a second, local version
+ control system, so that the file is effectively registered in two
+ systems at the same time.  For the description here, we will assume
+ that the remote system is CVS, and you use RCS locally, although the
+ mechanism works with any combination of version control systems
+ (@dfn{back ends}).
+ 
+ To make it work with other back ends, you must make sure that the
+ ``more local'' back end comes before the ``more remote'' back end in
+ the setting of @code{vc-handled-backends} (@pxref{Customizing VC}).  By
+ default, this variable is set up so that you can use remote CVS and
+ local RCS as described here.
+ 
+ To start using local RCS for a file that comes from a remote CVS
+ server, you must @emph{register the file in RCS}, by typing @kbd{C-u
+ C-x v v rcs @key{RET}}.  (In other words, use @code{vc-next-action} with a
+ prefix argument, and specify RCS as the back end.)
+ 
+ You can do this at any time; it does not matter whether you have
+ already modified the file with respect to the version in the CVS
+ repository.  If possible, VC tries to make the RCS master start with
+ the unmodified repository version, then checks in any local changes
+ as a new version.  This works if you have not made any changes yet, or
+ if the unmodified repository version exists locally as a version
+ backup (@pxref{Version Backups}).  If the unmodified version is not
+ available locally, the RCS master starts with the modified version;
+ the only drawback to this is that you cannot compare your changes
+ locally to what is stored in the repository.
+ 
+ The version number of the RCS master is derived from the current CVS
+ version, starting a branch from it.  For example, if the current CVS
+ version is 1.23, the local RCS branch will be 1.23.1.  Version 1.23 in
+ the RCS master will be identical to version 1.23 under CVS; your first
+ changes are checked in as 1.23.1.1.  (If the unmodified file is not
+ available locally, VC will check in the modified file twice, both as
+ 1.23 and 1.23.1.1, to make the revision numbers consistent.)
+ 
+ If you do not use locking under CVS (the default), locking is also
+ disabled for RCS, so that editing under RCS works exactly as under
+ CVS.
+ 
+ When you are done with local editing, you can commit the final version
+ back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}.
+ This initializes the log entry buffer (@pxref{Log Buffer}) to contain
+ all the log entries you have recorded in the RCS master; you can edit
+ them as you wish, and then commit in CVS by typing @kbd{C-c C-c}.  If
+ the commit is successful, VC removes the RCS master, so that the file
+ is once again registered under CVS only.  (The RCS master is not
+ actually deleted, just renamed by appending @samp{~} to the name, so
+ that you can refer to it later if you wish.)
+ 
+ While using local RCS, you can pick up recent changes from the CVS
+ repository into your local file, or commit some of your changes back
+ to CVS, without terminating local RCS version control.  To do this,
+ switch to the CVS back end temporarily, with the @kbd{C-x v b} command:
+ 
+ @table @kbd
+ @item C-x v b
+ Switch to another back end that the current file is registered
+ under (@code{vc-switch-backend}).
+ 
+ @item C-u C-x v b @var{backend} @key{RET}
+ Switch to @var{backend} for the current file.
+ @end table
+ 
+ @kindex C-x v b
+ @findex vc-switch-backend
+ @kbd{C-x v b} does not change the buffer contents, or any files; it
+ only changes VC's perspective on how to handle the file.  Any
+ subsequent VC commands for that file will operate on the back end that
+ is currently selected.
+ 
+ If the current file is registered in more than one back end, typing
+ @kbd{C-x v b} ``cycles'' through all of these back ends.  With a
+ prefix argument, it asks for the back end to use in the minibuffer.
+ 
+ Thus, if you are using local RCS, and you want to pick up some recent
+ changes in the file from remote CVS, first visit the file, then type
+ @kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m
+ @key{RET}} to merge the news (@pxref{Merging}).  You can then switch
+ back to RCS by typing @kbd{C-x v b} again, and continue to edit
+ locally.
+ 
+ But if you do this, the revision numbers in the RCS master no longer
+ correspond to those of CVS.  Technically, this is not a problem, but
+ it can become difficult to keep track of what is in the CVS repository
+ and what is not.  So we suggest that you return from time to time to
+ CVS-only operation, using @kbd{C-u C-x v v cvs @key{RET}}.
+ 
+ @node Snapshots
+ @subsection Snapshots
+ @cindex snapshots and version control
+ 
+   A @dfn{snapshot} is a named set of file versions (one for each
+ registered file) that you can treat as a unit.  One important kind of
+ snapshot is a @dfn{release}, a (theoretically) stable version of the
+ system that is ready for distribution to users.
+ 
+ @menu
+ * Making Snapshots::          The snapshot facilities.
+ * Snapshot Caveats::          Things to be careful of when using snapshots.
+ @end menu
+ 
+ @node Making Snapshots
+ @subsubsection Making and Using Snapshots
+ 
+   There are two basic commands for snapshots; one makes a
+ snapshot with a given name, the other retrieves a named snapshot.
+ 
+ @table @code
+ @kindex C-x v s
+ @findex vc-create-snapshot
+ @item C-x v s @var{name} @key{RET}
+ Define the last saved versions of every registered file in or under the
+ current directory as a snapshot named @var{name}
+ (@code{vc-create-snapshot}).
+ 
+ @kindex C-x v r
+ @findex vc-retrieve-snapshot
+ @item C-x v r @var{name} @key{RET}
+ For all registered files at or below the current directory level, select
+ whatever versions correspond to the snapshot @var{name}
+ (@code{vc-retrieve-snapshot}).
+ 
+ This command reports an error if any files are locked at or below the
+ current directory, without changing anything; this is to avoid
+ overwriting work in progress.
+ @end table
+ 
+   A snapshot uses a very small amount of resources---just enough to record
+ the list of file names and which version belongs to the snapshot.  Thus,
+ you need not hesitate to create snapshots whenever they are useful.
+ 
+   You can give a snapshot name as an argument to @kbd{C-x v =} or
+ @kbd{C-x v ~} (@pxref{Old Versions}).  Thus, you can use it to compare a
+ snapshot against the current files, or two snapshots against each other,
+ or a snapshot against a named version.
+ 
+ @node Snapshot Caveats
+ @subsubsection Snapshot Caveats
+ 
+ @cindex named configurations (RCS)
+   VC's snapshot facilities are modeled on RCS's named-configuration
+ support.  They use RCS's native facilities for this, so under VC
+ snapshots made using RCS are visible even when you bypass VC.
+ 
+ @c worded verbosely to avoid overfull hbox.
+   For SCCS, VC implements snapshots itself.  The files it uses contain
+ name/file/version-number triples.  These snapshots are visible only
+ through VC.
+ 
+   A snapshot is a set of checked-in versions.  So make sure that all the
+ files are checked in and not locked when you make a snapshot.
+ 
+   File renaming and deletion can create some difficulties with snapshots.
+ This is not a VC-specific problem, but a general design issue in version
+ control systems that no one has solved very well yet.
+ 
+   If you rename a registered file, you need to rename its master along
+ with it (the command @code{vc-rename-file} does this automatically).  If
+ you are using SCCS, you must also update the records of the snapshot, to
+ mention the file by its new name (@code{vc-rename-file} does this,
+ too).  An old snapshot that refers to a master file that no longer
+ exists under the recorded name is invalid; VC can no longer retrieve
+ it.  It would be beyond the scope of this manual to explain enough about
+ RCS and SCCS to explain how to update the snapshots by hand.
+ 
+   Using @code{vc-rename-file} makes the snapshot remain valid for
+ retrieval, but it does not solve all problems.  For example, some of the
+ files in your program probably refer to others by name.  At the very
+ least, the makefile probably mentions the file that you renamed.  If you
+ retrieve an old snapshot, the renamed file is retrieved under its new
+ name, which is not the name that the makefile expects.  So the program
+ won't really work as retrieved.
+ 
+ @node Miscellaneous VC
+ @subsection Miscellaneous Commands and Features of VC
+ 
+   This section explains the less-frequently-used features of VC.
+ 
+ @menu
+ * Change Logs and VC::  Generating a change log file from log entries.
+ * Renaming and VC::     A command to rename both the source and master
+                           file correctly.
+ * Version Headers::     Inserting version control headers into working files.
+ @end menu
+ 
+ @node Change Logs and VC
+ @subsubsection Change Logs and VC
+ 
+   If you use RCS or CVS for a program and also maintain a change log
+ file for it (@pxref{Change Log}), you can generate change log entries
+ automatically from the version control log entries:
+ 
+ @table @kbd
+ @item C-x v a
+ @kindex C-x v a
+ @findex vc-update-change-log
+ Visit the current directory's change log file and, for registered files
+ in that directory, create new entries for versions checked in since the
+ most recent entry in the change log file.
+ (@code{vc-update-change-log}).
+ 
+ This command works with RCS or CVS only, not with SCCS.
+ 
+ @item C-u C-x v a
+ As above, but only find entries for the current buffer's file.
+ 
+ @item M-1 C-x v a
+ As above, but find entries for all the currently visited files that are
+ maintained with version control.  This works only with RCS, and it puts
+ all entries in the log for the default directory, which may not be
+ appropriate.
+ @end table
+ 
+   For example, suppose the first line of @file{ChangeLog} is dated
+ 1999-04-10, and that the only check-in since then was by Nathaniel
+ Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log
+ messages that start with `#'.}.  Then @kbd{C-x v a} visits
+ @file{ChangeLog} and inserts text like this:
+ 
+ @iftex
+ @medbreak
+ @end iftex
+ @smallexample
+ @group
+ 1999-05-22  Nathaniel Bowditch  <nat@@apn.org>
+ 
+         * rcs2log: Ignore log messages that start with `#'.
+ @end group
+ @end smallexample
+ @iftex
+ @medbreak
+ @end iftex
+ 
+ @noindent
+ You can then edit the new change log entry further as you wish.
+ 
+   Some of the new change log entries may duplicate what's already in
+ ChangeLog.  You will have to remove these duplicates by hand.
+ 
+   Normally, the log entry for file @file{foo} is displayed as @samp{*
+ foo: @var{text of log entry}}.  The @samp{:} after @file{foo} is omitted
+ if the text of the log entry starts with @address@hidden(@var{functionname}):
+ }}.  For example, if the log entry for @file{vc.el} is
+ @samp{(vc-do-command): Check call-process status.}, then the text in
+ @file{ChangeLog} looks like this:
+ 
+ @iftex
+ @medbreak
+ @end iftex
+ @smallexample
+ @group
+ 1999-05-06  Nathaniel Bowditch  <nat@@apn.org>
+ 
+         * vc.el (vc-do-command): Check call-process status.
+ @end group
+ @end smallexample
+ @iftex
+ @medbreak
+ @end iftex
+ 
+   When @kbd{C-x v a} adds several change log entries at once, it groups
+ related log entries together if they all are checked in by the same
+ author at nearly the same time.  If the log entries for several such
+ files all have the same text, it coalesces them into a single entry.
+ For example, suppose the most recent check-ins have the following log
+ entries:
+ 
+ @flushleft
+ @bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.}
+ @bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.}
+ @bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.}
+ @end flushleft
+ 
+ @noindent
+ They appear like this in @file{ChangeLog}:
+ 
+ @iftex
+ @medbreak
+ @end iftex
+ @smallexample
+ @group
+ 1999-04-01  Nathaniel Bowditch  <nat@@apn.org>
+ 
+         * vc.texinfo: Fix expansion typos.
+ 
+         * vc.el, vc-hooks.el: Don't call expand-file-name.
+ @end group
+ @end smallexample
+ @iftex
+ @medbreak
+ @end iftex
+ 
+   Normally, @kbd{C-x v a} separates log entries by a blank line, but you
+ can mark several related log entries to be clumped together (without an
+ intervening blank line) by starting the text of each related log entry
+ with a label of the form @address@hidden@address@hidden@} }}.  The label
+ itself is not copied to @file{ChangeLog}.  For example, suppose the log
+ entries are:
+ 
+ @flushleft
+ @bullet{} For @file{vc.texinfo}: @address@hidden@} Fix expansion typos.}
+ @bullet{} For @file{vc.el}: @address@hidden@} Don't call expand-file-name.}
+ @bullet{} For @file{vc-hooks.el}: @address@hidden@} Don't call 
expand-file-name.}
+ @end flushleft
+ 
+ @noindent
+ Then the text in @file{ChangeLog} looks like this:
+ 
+ @iftex
+ @medbreak
+ @end iftex
+ @smallexample
+ @group
+ 1999-04-01  Nathaniel Bowditch  <nat@@apn.org>
+ 
+         * vc.texinfo: Fix expansion typos.
+         * vc.el, vc-hooks.el: Don't call expand-file-name.
+ @end group
+ @end smallexample
+ @iftex
+ @medbreak
+ @end iftex
+ 
+   A log entry whose text begins with @samp{#} is not copied to
+ @file{ChangeLog}.  For example, if you merely fix some misspellings in
+ comments, you can log the change with an entry beginning with @samp{#}
+ to avoid putting such trivia into @file{ChangeLog}.
+ 
+ @node Renaming and VC
+ @subsubsection Renaming VC Work Files and Master Files
+ 
+ @findex vc-rename-file
+   When you rename a registered file, you must also rename its master
+ file correspondingly to get proper results.  Use @code{vc-rename-file}
+ to rename the source file as you specify, and rename its master file
+ accordingly.  It also updates any snapshots (@pxref{Snapshots}) that
+ mention the file, so that they use the new name; despite this, the
+ snapshot thus modified may not completely work (@pxref{Snapshot
+ Caveats}).
+ 
+   You cannot use @code{vc-rename-file} on a file that is locked by
+ someone else.
+ 
+ @node Version Headers
+ @subsubsection Inserting Version Control Headers
+ 
+    Sometimes it is convenient to put version identification strings
+ directly into working files.  Certain special strings called
+ @dfn{version headers} are replaced in each successive version by the
+ number of that version.
+ 
+   If you are using RCS, and version headers are present in your working
+ files, Emacs can use them to determine the current version and the
+ locking state of the files.  This is more reliable than referring to the
+ master files, which is done when there are no version headers.  Note
+ that in a multi-branch environment, version headers are necessary to
+ make VC behave correctly (@pxref{Multi-User Branching}).
+ 
+   Searching for version headers is controlled by the variable
+ @code{vc-consult-headers}.  If it is address@hidden (the default),
+ Emacs searches for headers to determine the version number you are
+ editing.  Setting it to @code{nil} disables this feature.
+ 
+ @kindex C-x v h
+ @findex vc-insert-headers
+   You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
+ insert a suitable header string.
+ 
+ @table @kbd
+ @item C-x v h
+ Insert headers in a file for use with your version-control system.
+ @end table
+ 
+ @vindex vc-header-alist
+   The default header string is @address@hidden for RCS and
+ @address@hidden for SCCS.  You can specify other headers to insert by
+ setting the variable @code{vc-header-alist}.  Its value is a list of
+ elements of the form @code{(@var{program} . @var{string})} where
+ @var{program} is @code{RCS} or @code{SCCS} and @var{string} is the
+ string to use.
+ 
+   Instead of a single string, you can specify a list of strings; then
+ each string in the list is inserted as a separate header on a line of
+ its own.
+ 
+   It is often necessary to use ``superfluous'' backslashes when
+ writing the strings that you put in this variable.  For instance, you
+ might write @code{"$Id\$"} rather than @code{"address@hidden"}.  The extra
+ backslash prevents the string constant from being interpreted as a
+ header, if the Emacs Lisp file containing it is maintained with
+ version control.
+ 
+ @vindex vc-comment-alist
+   Each header is inserted surrounded by tabs, inside comment delimiters,
+ on a new line at point.  Normally the ordinary comment
+ start and comment end strings of the current mode are used, but for
+ certain modes, there are special comment delimiters for this purpose;
+ the variable @code{vc-comment-alist} specifies them.  Each element of
+ this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
+ 
+ @vindex vc-static-header-alist
+   The variable @code{vc-static-header-alist} specifies further strings
+ to add based on the name of the buffer.  Its value should be a list of
+ elements of the form @code{(@var{regexp} . @var{format})}.  Whenever
+ @var{regexp} matches the buffer name, @var{format} is inserted as part
+ of the header.  A header line is inserted for each element that matches
+ the buffer name, and for each string specified by
+ @code{vc-header-alist}.  The header line is made by processing the
+ string from @code{vc-header-alist} with the format taken from the
+ element.  The default value for @code{vc-static-header-alist} is as follows:
+ 
+ @example
+ @group
+ (("\\.c$" .
+   "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
+ #endif /* lint */\n"))
+ @end group
+ @end example
+ 
+ @noindent
+ It specifies insertion of text of this form:
+ 
+ @example
+ @group
+ 
+ #ifndef lint
+ static char vcid[] = "@var{string}";
+ #endif /* lint */
+ @end group
+ @end example
+ 
+ @noindent
+ Note that the text above starts with a blank line.
+ 
+   If you use more than one version header in a file, put them close
+ together in the file.  The mechanism in @code{revert-buffer} that
+ preserves markers may not handle markers positioned between two version
+ headers.
+ 
+ @node Customizing VC
+ @subsection Customizing VC
+ 
+ @vindex vc-handled-backends
+ The variable @code{vc-handled-backends} determines which version
+ control systems VC should handle.  The default value is @code{(RCS CVS
+ SCCS)}, so it contains all three version systems that are currently
+ supported.  If you want VC to ignore one or more of these systems,
+ exclude its name from the list.  To disable VC entirely, set this
+ variable to @code{nil}.
+ 
+ The order of systems in the list is significant: when you visit a file
+ registered in more than one system (@pxref{Local Version Control}),
+ VC uses the system that comes first in @code{vc-handled-backends} by
+ default.  The order is also significant when you register a file for
+ the first time, @pxref{Registering} for details.
+ 
+ @menu
+ * General VC Options::  Options that apply to multiple back ends.
+ * RCS and SCCS::        Options for RCS and SCCS.
+ * CVS Options::         Options for CVS.
+ @end menu
+ 
+ @node General VC Options
+ @subsubsection General Options
+ 
+ @vindex vc-make-backup-files
+   Emacs normally does not save backup files for source files that are
+ maintained with version control.  If you want to make backup files even
+ for files that use version control, set the variable
+ @code{vc-make-backup-files} to a address@hidden value.
+ 
+ @vindex vc-keep-workfiles
+   Normally the work file exists all the time, whether it is locked or
+ not.  If you set @code{vc-keep-workfiles} to @code{nil}, then checking
+ in a new version with @kbd{C-x v v} deletes the work file; but any
+ attempt to visit the file with Emacs creates it again.  (With CVS, work
+ files are always kept.)
+ 
+ @vindex vc-follow-symlinks
+   Editing a version-controlled file through a symbolic link can be
+ dangerous.  It bypasses the version control system---you can edit the
+ file without locking it, and fail to check your changes in.  Also,
+ your changes might overwrite those of another user.  To protect against
+ this, VC checks each symbolic link that you visit, to see if it points
+ to a file under version control.
+ 
+   The variable @code{vc-follow-symlinks} controls what to do when a
+ symbolic link points to a version-controlled file.  If it is @code{nil},
+ VC only displays a warning message.  If it is @code{t}, VC automatically
+ follows the link, and visits the real file instead, telling you about
+ this in the echo area.  If the value is @code{ask} (the default), VC
+ asks you each time whether to follow the link.
+ 
+ @vindex vc-suppress-confirm
+   If @code{vc-suppress-confirm} is address@hidden, then @kbd{C-x v v}
+ and @kbd{C-x v i} can save the current buffer without asking, and
+ @kbd{C-x v u} also operates without asking for confirmation.  (This
+ variable does not affect @kbd{C-x v c}; that operation is so drastic
+ that it should always ask for confirmation.)
+ 
+ @vindex vc-command-messages
+   VC mode does much of its work by running the shell commands for RCS,
+ CVS and SCCS.  If @code{vc-command-messages} is address@hidden, VC
+ displays messages to indicate which shell commands it runs, and
+ additional messages when the commands finish.
+ 
+ @vindex vc-path
+   You can specify additional directories to search for version control
+ programs by setting the variable @code{vc-path}.  These directories
+ are searched before the usual search path.  It is rarely necessary to
+ set this variable, because VC normally finds the proper files
+ automatically.
+ 
+ @node RCS and SCCS
+ @subsubsection Options for RCS and SCCS
+ 
+ @cindex non-strict locking (RCS)
+ @cindex locking, non-strict (RCS)
+   By default, RCS uses locking to coordinate the activities of several
+ users, but there is a mode called @dfn{non-strict locking} in which
+ you can check-in changes without locking the file first.  Use
+ @samp{rcs -U} to switch to non-strict locking for a particular file,
+ see the @code{rcs} manual page for details.
+ 
+   When deducing the version control state of an RCS file, VC first
+ looks for an RCS version header string in the file (@pxref{Version
+ Headers}).  If there is no header string, VC normally looks at the
+ file permissions of the work file; this is fast.  But there might be
+ situations when the file permissions cannot be trusted.  In this case
+ the master file has to be consulted, which is rather expensive.  Also
+ the master file can only tell you @emph{if} there's any lock on the
+ file, but not whether your work file really contains that locked
+ version.
+ 
+ @vindex vc-consult-headers
+   You can tell VC not to use version headers to determine the file
+ status by setting @code{vc-consult-headers} to @code{nil}.  VC then
+ always uses the file permissions (if it is supposed to trust them), or
+ else checks the master file.
+ 
+ @vindex vc-mistrust-permissions
+   You can specify the criterion for whether to trust the file
+ permissions by setting the variable @code{vc-mistrust-permissions}.
+ Its value can be @code{t} (always mistrust the file permissions and
+ check the master file), @code{nil} (always trust the file
+ permissions), or a function of one argument which makes the decision.
+ The argument is the directory name of the @file{RCS} subdirectory.  A
+ address@hidden value from the function says to mistrust the file
+ permissions.  If you find that the file permissions of work files are
+ changed erroneously, set @code{vc-mistrust-permissions} to @code{t}.
+ Then VC always checks the master file to determine the file's status.
+ 
+   VC determines the version control state of files under SCCS much as
+ with RCS.  It does not consider SCCS version headers, though.  Thus,
+ the variable @code{vc-mistrust-permissions} affects SCCS use, but
+ @code{vc-consult-headers} does not.
+ 
+ @node CVS Options
+ @subsubsection Options specific for CVS
+ 
+ @cindex locking (CVS)
+   By default, CVS does not use locking to coordinate the activities of
+ several users; anyone can change a work file at any time.  However,
+ there are ways to restrict this, resulting in behavior that resembles
+ locking.
+ 
+ @cindex CVSREAD environment variable (CVS)
+   For one thing, you can set the @env{CVSREAD} environment variable
+ (the value you use makes no difference).  If this variable is defined,
+ CVS makes your work files read-only by default.  In Emacs, you must
+ type @kbd{C-x v v} to make the file writable, so that editing works
+ in fact similar as if locking was used.  Note however, that no actual
+ locking is performed, so several users can make their files writable
+ at the same time.  When setting @env{CVSREAD} for the first time, make
+ sure to check out all your modules anew, so that the file protections
+ are set correctly.
+ 
+ @cindex cvs watch feature
+ @cindex watching files (CVS)
+   Another way to achieve something similar to locking is to use the
+ @dfn{watch} feature of CVS.  If a file is being watched, CVS makes it
+ read-only by default, and you must also use @kbd{C-x v v} in Emacs to
+ make it writable.  VC calls @code{cvs edit} to make the file writable,
+ and CVS takes care to notify other developers of the fact that you
+ intend to change the file.  See the CVS documentation for details on
+ using the watch feature.
+ 
+ @vindex vc-cvs-stay-local
+ @cindex remote repositories (CVS)
+   When a file's repository is on a remote machine, VC tries to keep
+ network interactions to a minimum.  This is controlled by the variable
+ @code{vc-cvs-stay-local}.  If it is @code{t} (the default), then VC uses
+ only the entry in the local CVS subdirectory to determine the file's
+ state (and possibly information returned by previous CVS commands).  One
+ consequence of this is that when you have modified a file, and somebody
+ else has already checked in other changes to the file, you are not
+ notified of it until you actually try to commit.  (But you can try to
+ pick up any recent changes from the repository first, using @kbd{C-x v m
+ @key{RET}}, @pxref{Merging}).
+ 
+ @vindex vc-cvs-global-switches
+   The variable @code{vc-cvs-global-switches} should be a string
+ specifying switches to pass to CVS for all CVS operations.
+ 
+   When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
+ version backups, so that simple diff and revert operations are
+ completely local (@pxref{Version Backups}).
+ 
+   On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil},
+ then VC queries the remote repository @emph{before} it decides what to
+ do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local
+ repositories.  It also does not make any version backups.
+ 
+   You can also set @code{vc-cvs-stay-local} to a regular expression
+ that is matched against the repository host name; VC then stays local
+ only for repositories from hosts that match the pattern.
+ 
+ @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).  There is also a directory browser 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
+   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.
+ 
+   The buffer @samp{*diff*} has Compilation mode as its major mode, so
+ you can use @kbd{C-x `} to visit successive changed locations in the two
+ source files.  You can also move to a particular hunk of changes and
+ type @key{RET} or @kbd{C-c C-c}, or click @kbd{Mouse-2} on it, to move
+ to the corresponding source location.  You can also use the other
+ special commands of Compilation mode: @key{SPC} and @key{DEL} for
+ scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion.
+ @xref{Compilation}.
+ 
+ @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.  Comparison starts at point in each
+ window, and each starting position is pushed on the mark ring in its
+ respective buffer.  Then point moves forward in each window, a character
+ at a time, until a mismatch between the two windows is reached.  Then
+ the command is finished.  For more information about windows in Emacs,
+ @ref{Windows}.
+ 
+ @vindex compare-ignore-case
+   With a numeric argument, @code{compare-windows} ignores changes in
+ whitespace.  If the variable @code{compare-ignore-case} is
+ address@hidden, it ignores differences in case as well.
+ 
+ @findex diff-mode
+ @cindex diffs
+ @cindex patches
+ @cindex Diff mode
+   Differences between versions of files are often distributed as
+ @dfn{patches}, which are the output from @command{diff} or a version
+ control system that uses @command{diff}.  @kbd{M-x diff-mode} turns on
+ Diff mode, a major mode for viewing and editing patches, either as
+ ``unified diffs'' or ``context diffs.''
+ 
+ @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.
+ 
+   See also @ref{Emerge}, and @ref{Top,,, ediff, The Ediff Manual}, for
+ convenient facilities for merging two similar files.
+ 
+ @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 major 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 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}.
+ 
+ @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.
+ 
+ @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 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.  Confirmation is required if a file named
+ @var{new} already exists, because copying has the consequence of overwriting
+ the old contents of the file @var{new}.
+ 
+ @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
+ not in use 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.
+ 
+   Confirmation is required when creating the link if @var{linkname} is
+ in use.  Note that 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
+ 
+ @findex auto-compression-mode
+ @vindex auto-compression-mode
+   Emacs comes with a library that can automatically uncompress
+ compressed files when you visit them, and automatically recompress them
+ if you alter them and save them.  To enable this feature, type the
+ command @kbd{M-x auto-compression-mode}.  You can enable it permanently
+ by customizing the option @code{auto-compression-mode}.
+ 
+   When automatic compression (which implies automatic uncompression as
+ well) is enabled, 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.
+ 
+ @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 you enable Auto Compression mode (@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 when 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.  @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.
+ 
+   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 @address@hidden 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}@@@address@hidden:@var{filename}
+ /@var{method}:@var{user}@@@var{host}:@var{filename}
+ /@var{method}:@var{user}@@@address@hidden:@var{filename}
+ @end group
+ @end example
+ 
+ @noindent
+ When you do this, Emacs may use the FTP program to access files on the
+ remote host, or Emacs may use a remote-login program (such as
+ @command{ssh}, @command{rlogin}, or @command{telnet}) to do this.
+ 
+ You can always specify in the file name which method should be used to
+ access the remote files, 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 determines a
+ default method according to the following rules:
+ 
+ @enumerate
+ @item
+ If the host name starts with @samp{ftp.} (with dot), then Emacs assumes
+ the @command{ftp} method.
+ @item
+ If the user name is @samp{ftp} or @samp{anonymous}, then Emacs assumes
+ the @command{ftp} method.
+ @item
+ Otherwise, Emacs assumes the @command{ssh} method.
+ @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.
+ (The Emacs package that implements FTP file access is called
+ @code{ange-ftp}.)
+ 
+ @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 address@hidden (the default), then the value of
+ @code{user-mail-address} is used; if @code{nil}, the user is prompted
+ for a password as normal.
+ 
+ @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
+   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 address@hidden
+ @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, @address@hidden
+ (@code{file-cache-minibuffer-complete}) completes it using the file
+ name cache.  If you repeat @address@hidden, that cycles through the
+ possible completions of what you had originally typed.  Note that the
+ @address@hidden 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
+ 
+ @node File Conveniences
+ @section Convenience Features for Finding 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.
+ 
+ @findex auto-image-file-mode
+ @findex mode, auto-image-file
+ @cindex images, visiting
+ @cindex visiting image files
+ @vindex image-file-name-regexps
+ @vindex image-file-name-extensions
+   When Auto-image-file minor mode is enabled, visiting an image file
+ displays it as an image, not as text.  Likewise, inserting an image
+ file into a buffer inserts it as an image.  This works only when Emacs
+ can display the relevant image type.  The variables
+ @code{image-file-name-extensions} or @code{image-file-name-regexps}
+ control which file names are recognized as containing images.
+ 
+   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}.
+ 
+ @ignore
+    arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250
+ @end ignore