+File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup
+
+Automatic Deletion of Backups
+.............................
+
+ To prevent unlimited 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. The two variables that
+control the deletion are `kept-old-versions' and `kept-new-versions'.
+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 values are used just after a
+new backup version is made; that newly made backup is included in the
+count in `kept-new-versions'. By default, both variables are 2.
+
+ If `delete-old-versions' is non-`nil', excess middle versions are
+deleted without notification. If it is `nil', the default, you are
+asked whether the excess middle versions should really be deleted.
+
+ You can also use Dired's `.' (Period) command to delete old versions.
+*Note Dired::.
+
+\1f
+File: xemacs.info, Node: Backup Copying, Prev: Backup Deletion, Up: Backup
+
+Copying vs. Renaming
+....................
+
+ You can make backup files by copying the old file or by renaming it.
+This makes a difference when the old file has multiple names. If you
+rename the old file into the backup file, the alternate names become
+names for the backup file. If you copy the old file instead, the
+alternate names remain names for the file that you are editing, and the
+contents accessed by those names will be the new contents.
+
+ How you make a backup file may also affect the file's owner and
+group. If you use copying, they 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 is always the person who last edited the file. Occasionally
+there is a file whose owner should not change. Since most files should
+change owners, it is a good idea to use local variable lists to set
+`backup-by-copying-when-mismatch' for the special cases where the owner
+should not change (*note File Variables::).
+
+ Three variables control the choice of renaming or copying.
+Normally, renaming is done. If the variable `backup-by-copying' is
+non-`nil', copying is used. Otherwise, if the variable
+`backup-by-copying-when-linked' is non-`nil', copying is done for files
+that have multiple names, but renaming may still be done when the file
+being edited has only one name. If the variable
+`backup-by-copying-when-mismatch' is non-`nil', copying is done if
+renaming would cause the file's owner or group to change.
+
+\1f
+File: xemacs.info, Node: Interlocking, Prev: Backup, Up: Saving
+
+Protection Against Simultaneous Editing
+---------------------------------------
+
+ Simultaneous editing occurs when two users visit the same file, both
+make changes, and both save their changes. If no one was informed that
+this was happening, and you saved first, you would later find that your
+changes were lost. On some systems, Emacs notices immediately when the
+second user starts to change a file already being edited, and issues a
+warning. When this is not possible, or if the second user has started
+to change the file despite the warning, Emacs checks when the file is
+saved, and issues a second warning when a user is about to overwrite a
+file containing another user's changes. If you are the user editing the
+file, you can take corrective action at this point and prevent actual
+loss of work.
+
+ When you make the first modification in an Emacs buffer that is
+visiting a file, Emacs records that you have locked the file. (It does
+this by writing another file in a directory reserved for this purpose.)
+The lock is removed when you save the changes. The idea is that the
+file is locked whenever the buffer is modified. If you begin to modify
+the buffer while the visited file is locked by someone else, this
+constitutes a collision, and Emacs asks you what to do. It does this
+by calling the Lisp function `ask-user-about-lock', which you can
+redefine to customize what it does. The standard definition of this
+function asks you a question and accepts three possible answers:
+
+`s'
+ Steal the lock. Whoever was already changing the file loses the
+ lock, and you get the lock.
+
+`p'
+ Proceed. Go ahead and edit the file despite its being locked by
+ someone else.
+
+`q'
+ Quit. This causes an error (`file-locked') and the modification
+ you were trying to make in the buffer does not actually take place.
+
+ 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 do not really exist until they
+are saved.
+
+ Some systems are not configured to allow Emacs to make locks. On
+these systems, Emacs cannot detect trouble in advance, but it can still
+detect it in time to prevent you from overwriting someone else's
+changes.
+
+ Every time Emacs saves a buffer, it first checks the
+last-modification date of the existing file on disk to see 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 prints 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 `yes'
+and proceed. Otherwise, you should cancel the save with `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 `C-u C-x C-d'
+(*note Directory Listing: ListDir.). This will show the file's current
+author. You should attempt to contact that person and ask him not to
+continue editing. Often the next step is to save the contents of your
+Emacs buffer under a different name, and use `diff' to compare the two
+files.
+
+ Simultaneous editing checks are also made when you visit a file that
+is already visited with `C-x C-f' and when you start to modify a file.
+This is not strictly necessary, but it is useful to find out about such
+a problem as early as possible, when corrective action takes less work.
+
+ Another way to protect your file is to set the read, write, and
+executable permissions for the file. Use the function
+`set-default-file-modes' to set the UNIX `umask' value to the NMASK
+argument. The `umask' value is the default protection mode for new
+files.
+
+\1f
+File: xemacs.info, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files
+
+Reverting a Buffer
+==================
+
+ If you have made extensive changes to a file and then change your
+mind about them, you can get rid of all changes by reading in the
+previous version of the file. To do this, use `M-x revert-buffer',
+which operates on the current buffer. Since reverting a buffer can
+result in very extensive changes, you must confirm it with `yes'.
+
+ If the current buffer has been auto-saved more recently than it has
+been saved explicitly, `revert-buffer' offers to read the auto save file
+instead of the visited file (*note Auto Save::). Emacs asks you about
+the auto-save file before the request for confirmation of the
+`revert-buffer' operation, and demands `y' or `n' as an answer. If you
+have started to type `yes' for confirmation without realizing that the
+auto-save question was going to be asked, the `y' will answer that
+question, but the `es' will not be valid confirmation. This gives you
+a chance to cancel the operation with `C-g' and try again with the
+answers you really intend.
+
+ `revert-buffer' keeps point at the same distance (measured in
+characters) from the beginning of the file. If the file was edited only
+slightly, you will be at approximately the same piece of text after
+reverting as before. If you have made more extensive changes, the
+value of point in the old file may bring you to a totally different
+piece of text than your last editing point.
+
+ A buffer reverted from its visited file is marked "not modified"
+until you make a change.
+
+ 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.
+Buffers created randomly with `C-x b' cannot be reverted;
+`revert-buffer' reports an error when asked to do so.
+
+\1f
+File: xemacs.info, Node: Auto Save, Next: Version Control, Prev: Reverting, Up: Files
+
+Auto-Saving: Protection Against Disasters
+=========================================
+
+ Emacs saves all the visited files from time to time (based on
+counting your keystrokes) without being asked. This is called
+"auto-saving". It prevents you from losing more than a limited amount
+of work if the system crashes.
+
+ When Emacs determines 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 changed since the last time it was auto-saved. If any auto-saving
+is done, the message `Auto-saving...' is displayed in the echo area
+until auto-saving is finished. 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.
+* Control: Auto Save Control.
+* Recover:: Recovering text from auto-save files.
+
+\1f
+File: xemacs.info, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save
+
+Auto-Save Files
+---------------
+
+ Auto-saving does not normally write to the files you visited, because
+it can be undesirable to save a program that is in an inconsistent
+state when you have made only half of a planned change. Instead,
+auto-saving is done in a different file called the "auto-save file",
+and the visited file is changed only when you save explicitly, for
+example, with `C-x C-s'.
+
+ Normally, the name of the auto-save file is generated by appending
+`#' to the front and back of the visited file name. Thus, a buffer
+visiting file `foo.c' would be auto-saved in a 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
+generated by appending `#%' to the front and `#' to the back of buffer
+name. For example, the `*mail*' buffer in which you compose messages
+to be sent is auto-saved in a file named `#%*mail*#'. Names of
+auto-save files are generated this way unless you customize the
+functions `make-auto-save-file-name' and `auto-save-file-name-p' to do
+something different. The file name to be used for auto-saving a buffer
+is calculated at the time auto-saving is turned on in that buffer.
+
+ If you want auto-saving to be done in the visited file, set the
+variable `auto-save-visited-file-name' to be non-`nil'. In this mode,
+there is really no difference between auto-saving and explicit saving.
+
+ Emacs deletes a buffer's auto-save file when you explicitly save the
+buffer. To inhibit the deletion, set the variable
+`delete-auto-save-files' to `nil'. Changing the visited file name with
+`C-x C-w' or `set-visited-file-name' renames any auto-save file to
+correspond to the new visited name.
+
+\1f
+File: xemacs.info, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save
+
+Controlling Auto-Saving
+-----------------------
+
+ Each time you visit a file, auto-saving is turned on for that file's
+buffer if the variable `auto-save-default' is non-`nil' (but not in
+batch mode; *note Entering Emacs::). The default for this variable is
+`t', so Emacs auto-saves buffers that visit files by default. You can
+use the command `M-x auto-save-mode' to turn auto-saving for a buffer
+on or off. Like other minor mode commands, `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.
+
+ Emacs performs auto-saving periodically based on counting how many
+characters you have typed since the last time auto-saving happened. The
+variable `auto-save-interval' specifies the number of characters
+between auto-saves. By default, it is 300. Emacs also auto-saves
+whenever you call the function `do-auto-save'.
+
+ Emacs also does auto-saving whenever it gets a fatal error. This
+includes killing the Emacs job with a shell command such as `kill
+-emacs', or disconnecting a phone line or network connection.
+
+ You can set the number of seconds of idle time before an auto-save is
+done. Setting the value of the variable `auto-save-timeout' to zero or
+`nil' will disable auto-saving due to idleness.
+
+ The actual amount of idle time between auto-saves is logarithmically
+related to the size of the current buffer. This variable is the number
+of seconds after which an auto-save will happen when the current buffer
+is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3
+3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k
+buffer.
+
+ For this variable to have any effect, you must do `(require 'timer)'.
+
+\1f
+File: xemacs.info, Node: Recover, Prev: Auto Save Control, Up: Auto Save
+
+Recovering Data from Auto-Saves
+-------------------------------
+
+ If you want to use the contents of an auto-save file to recover from
+a loss of data, use the command `M-x recover-file <RET> FILE <RET>'.
+Emacs visits FILE and then (after your confirmation) restores the
+contents from the auto-save file `#FILE#'. You can then save the file
+with `C-x C-s' to put the recovered text into FILE itself. For
+example, to recover file `foo.c' from its auto-save file `#foo.c#', do:
+
+ M-x recover-file <RET> foo.c <RET>
+ C-x C-s
+
+ Before asking for confirmation, `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, `M-x recover-file' does not offer to read it.
+
+ Auto-saving is disabled by `M-x recover-file' because using this
+command implies that the auto-save file contains valuable data from a
+past session. If you save the data in the visited file and then go on
+to make new changes, turn auto-saving back on with `M-x auto-save-mode'.
+
+\1f
+File: xemacs.info, Node: Version Control, Next: ListDir, Prev: Auto Save, Up: Files
+
+Version Control
+===============
+
+ "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 GNU project recommends the version control system known as RCS,
+which is free software and available from the Free Software Foundation.
+Emacs supports use of either RCS or SCCS (a proprietary, but widely
+used, version control system that is not quite as powerful as RCS)
+through a facility called VC. The same Emacs commands work with either
+RCS or SCCS, so you hardly have to know which one of them you are using.
+
+* Menu:
+
+* Concepts of VC:: Basic version control information;
+ checking files in and out.
+* Editing with VC:: Commands for editing a file maintained
+ with version control.
+* Variables for Check-in/out:: Variables that affect the commands used
+ to check files in or out.
+* Log Entries:: Logging your changes.
+* Change Logs and VC:: Generating a change log file from log
+ entries.
+* Old Versions:: Examining and comparing old versions.
+* VC Status:: Commands to view the VC status of files and
+ look at log entries.
+* Renaming and VC:: A command to rename both the source and
+ master file correctly.
+* Snapshots:: How to make and use snapshots, a set of
+ file versions that can be treated as a unit.
+* Version Headers:: Inserting version control headers into
+ working files.
+
+\1f
+File: xemacs.info, Node: Concepts of VC, Next: Editing with VC, Prev: Version Control, Up: Version Control
+
+Concepts of Version Control
+---------------------------
+
+ When a file is under version control, we also say that it is
+"registered" in the version control system. Each registered file has a
+corresponding "master file" which represents the file's present state
+plus its change history, so that you can reconstruct from it either the
+current version or any specified earlier version. Usually the master
+file also records a "log entry" for each version describing what was
+changed in that version.
+
+ The file that is maintained under version control is sometimes called
+the "work file" corresponding to its master file.
+
+ To examine a file, you "check it out". This extracts a version of
+the source file (typically, the most recent) from the master file. If
+you want to edit the file, you must check it out "locked". Only one
+user can do this at a time for any given source file. (This kind of
+locking is completely unrelated to the locking that Emacs uses to
+detect simultaneous editing of a file.)
+
+ When you are done with your editing, you must "check in" the new
+version. This records the new version in the master file, and unlocks
+the source file so that other people can lock it and thus modify it.
+
+ Checkin and checkout are the basic operations of version control.
+You can do both of them with a single Emacs command: `C-x C-q'
+(`vc-toggle-read-only').
+
+ A "snapshot" is a coherent collection of versions of the various
+files that make up a program. *Note Snapshots::.
+
+\1f
+File: xemacs.info, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control
+
+Editing with Version Control
+----------------------------
+
+ When you visit a file that is maintained using version control, the
+mode line displays `RCS' or `SCCS' to inform you that version control
+is in use, and also (in case you care) which low-level system the file
+is actually stored in. Normally, such a source file is read-only, and
+the mode line indicates this with `%%'. With RCS, the mode line also
+indicates the number of the head version, which is normally also the
+version you are looking at.
+
+ These are the commands for editing a file maintained with version
+control:
+
+`C-x C-q'
+ Check the visited file in or out.
+
+`C-x v u'
+ Revert the buffer and the file to the last checked in version.
+
+`C-x v c'
+ Remove the last-entered change from the master for the visited
+ file. This undoes your last check-in.
+
+`C-x v i'
+ Register the visited file in version control.
+
+(`C-x v' is the prefix key for version control commands; all of these
+commands except for `C-x C-q' start with `C-x v'.)
+
+ When you want to modify a file maintained with version control, type
+`C-x C-q' (`vc-toggle-read-only'). This "checks out" the file, and
+tells RCS or SCCS to lock the file. This means making the file
+writable for you (but not for anyone else).
+
+ When you are finished editing the file, type `C-x C-q' again. When
+used on a file that is checked out, this command checks the file in.
+But check-in does not start immediately; first, you must enter the "log
+entry"--a description of the changes in the new version. `C-x C-q'
+pops up a buffer for you to enter this in. When you are finished
+typing in the log entry, type `C-c C-c' to terminate it; this is when
+actual check-in takes place.
+
+ Once you have checked in your changes, the file is unlocked, so that
+other users can lock it and modify it.
+
+ Emacs does not save backup files for source files that are maintained
+with version control. If you want to make backup files despite version
+control, set the variable `vc-make-backup-files' to a non-`nil' value.
+
+ Normally the work file exists all the time, whether it is locked or
+not. If you set `vc-keep-workfiles' to `nil', then checking in a new
+version with `C-x C-q' deletes the work file; but any attempt to visit
+the file with Emacs creates it again.
+
+ It is not impossible to lock a file that someone else has locked. If
+you try to check out a file that is locked, `C-x C-q' asks you whether
+you want to "steal the lock." 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. The mode line indicates that
+a file is locked by someone else by displaying the login name of that
+person, before the version number.
+
+ If you want to discard your current set of changes and revert to the
+last version checked in, use `C-x v u' (`vc-revert-buffer'). This
+cancels your last check-out, leaving the file unlocked. If you want to
+make a different set of changes, you must first check the file out
+again. `C-x v u' requires confirmation, unless it sees that you
+haven't made any changes since the last checked-in version.
+
+ `C-x v u' is also the command to use if you lock a file and then
+don't actually change it.
+
+ You can cancel a change after checking it in, with `C-x v c'
+(`vc-cancel-version'). This command discards all record of the most
+recent checked in version, so be careful about using it. It requires
+confirmation with `yes'. By default, `C-x v c' reverts your workfile
+and buffer to the previous version (the one that precedes the version
+that is deleted), but you can prevent the reversion by giving the
+command a prefix argument. Then the buffer does not change.
+
+ This command with a prefix argument 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 repeat the check-in.
+
+ Be careful when invoking `C-x v c', as it is easy to throw away a
+lot of work with it. To help you be careful, this command always
+requires confirmation with `yes'.
+
+ You can register the visited file for version control using
+`C-x v i' (`vc-register'). If the variable `vc-default-back-end' is
+non-`nil', it specifies which version control system to use; otherwise,
+this uses RCS if it is installed on your system and SCCS if not. After
+`C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you
+wish to edit it.
+
+ By default, the initial version number is 1.1. If you want to use a
+different number, give `C-x v i' a prefix argument; then it reads the
+initial version number using the minibuffer.
+
+ If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial
+comment (much like a log entry) to describe the purpose of this source
+file.
+
+ To specify the version number for a subsequent checkin, use the
+command `C-u C-x v v'. `C-x v v' (`vc-next-action') is the command
+that `C-x C-q' uses to do the "real work" when the visited file uses
+version control. When used for checkin, and given a prefix argument,
+it reads the version number with the minibuffer.
+
+\1f