@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions.@setfilename ../info/backups@node Backups and Auto-Saving, Buffers, Files, Top@chapter Backups and Auto-Saving Backup files and auto-save files are two methods by which Emacs triesto protect the user from the consequences of crashes or of the user'sown errors. Auto-saving preserves the text from earlier in the currentediting session; backup files preserve file contents prior to thecurrent session.@menu* Backup Files:: How backup files are made; how their names are chosen.* Auto-Saving:: How auto-save files are made; how their names are chosen.* Reverting:: @code{revert-buffer}, and how to customize what it does.@end menu@node Backup Files@section Backup Files@cindex backup file A @dfn{backup file} is a copy of the old contents of a file you areediting. Emacs makes a backup file the first time you save a bufferinto its visited file. Normally, this means that the backup filecontains the contents of the file as it was before the current editingsession. The contents of the backup file normally remain unchanged onceit exists. Backups are usually made by renaming the visited file to a new name.Optionally, you can specify that backup files should be made by copyingthe visited file. This choice makes a difference for files withmultiple names; it also can affect whether the edited file remains ownedby the original owner or becomes owned by the user editing it. By default, Emacs makes a single backup file for each file edited.You can alternatively request numbered backups; then each new backupfile gets a new name. You can delete old numbered backups when youdon't want them any more, or Emacs can delete them automatically.@menu* Making Backups:: How Emacs makes backup files, and when.* Rename or Copy:: Two alternatives: renaming the old file or copying it.* Numbered Backups:: Keeping multiple backups for each source file.* Backup Names:: How backup file names are computed; customization.@end menu@node Making Backups@subsection Making Backup Files@defun backup-buffer This function makes a backup of the file visited by the currentbuffer, if appropriate. It is called by @code{save-buffer} beforesaving the buffer the first time.@end defun@defvar buffer-backed-up This buffer-local variable indicates whether this buffer's file hasbeen backed up on account of this buffer. If it is non-@code{nil}, thenthe backup file has been written. Otherwise, the file should be backedup when it is next saved (if backups are enabled). This is apermanent local; @code{kill-local-variables} does not alter it.@end defvar@defopt make-backup-files This variable determines whether or not to make backup files. If itis non-@code{nil}, then Emacs creates a backup of each file when it issaved for the first time. The following example shows how to change the @code{make-backup-files}variable only in the @file{RMAIL} buffer and not elsewhere. Setting it@code{nil} stops Emacs from making backups of the @file{RMAIL} file,which may save disk space. (You would put this code in your@file{.emacs} file.)@smallexample@group(add-hook 'rmail-mode-hook (function (lambda () (make-local-variable 'make-backup-files) (setq make-backup-files nil))))@end group@end smallexample@end defopt@defvar backup-enable-predicateThis variable's value is a function to be called on certain occasions todecide whether a file should have backup files. The function receivesone argument, a file name to consider. If the function returns@code{nil}, backups are disabled for that file. Otherwise, the othervariables in this section say whether and how to make backups.The default value is this:@example(lambda (name) (or (< (length name) 5) (not (string-equal "/tmp/" (substring name 0 5)))))@end example@end defvar@defvar backup-inhibitedIf this variable is non-@code{nil}, backups are inhibited. It recordsthe result of testing @code{backup-enable-predicate} on the visited filename. It can also coherently be used by other mechanisms that inhibitbackups based on which file is visited. This is a permanent local,so that changing the major mode does not lose its value.Major modes should not set this variable---they should set@code{make-backup-files} instead.@end defvar@node Rename or Copy@subsection Backup by Renaming or by Copying?@cindex backup files, how to make them There are two ways that Emacs can make a backup file: @itemize @bullet@itemEmacs can rename the original file so that it becomes a backup file, andthen write the buffer being saved into a new file. After thisprocedure, any other names (i.e., hard links) of the original file nowrefer to the backup file. The new file is owned by the user doing theediting, and its group is the default for new files written by the userin that directory.@itemEmacs can copy the original file into a backup file, and then overwritethe original file with new contents. After this procedure, any othernames (i.e., hard links) of the original file still refer to the currentversion of the file. The file's owner and group will be unchanged.@end itemize The first method, renaming, is the default. The variable @code{backup-by-copying}, if non-@code{nil}, says to usethe second method, which is to copy the original file and overwrite itwith the new buffer contents. The variable @code{file-precious-flag},if non-@code{nil}, also has this effect (as a sideline of its mainsignificance). @xref{Saving Buffers}.@defvar backup-by-copyingIf this variable is non-@code{nil}, Emacs always makes backup files bycopying.@end defvar The following two variables, when non-@code{nil}, cause the secondmethod to be used in certain special cases. They have no effect on thetreatment of files that don't fall into the special cases.@defvar backup-by-copying-when-linkedIf this variable is non-@code{nil}, Emacs makes backups by copying forfiles with multiple names (hard links).This variable is significant only if @code{backup-by-copying} is@code{nil}, since copying is always used when that variable isnon-@code{nil}.@end defvar@defvar backup-by-copying-when-mismatchIf this variable is non-@code{nil}, Emacs makes backups by copying in caseswhere renaming would change either the owner or the group of the file.The value has no effect when renaming would not alter the owner orgroup of the file; that is, for files which are owned by the user andwhose group matches the default for a new file created there by theuser.This variable is significant only if @code{backup-by-copying} is@code{nil}, since copying is always used when that variable isnon-@code{nil}.@end defvar@node Numbered Backups@subsection Making and Deleting Numbered Backup Files If a file's name is @file{foo}, the names of its numbered backupversions are @file{foo.~@var{v}~}, for various integers @var{v}, likethis: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{},@file{foo.~259~}, and so on.@defopt version-controlThis variable controls whether to make a single non-numbered backupfile or multiple numbered backups.@table @asis@item @code{nil}Make numbered backups if the visited file already has numbered backups;otherwise, do not.@item @code{never}Do not make numbered backups.@item @var{anything else}Make numbered backups.@end table@end defopt The use of numbered backups ultimately leads to a large number ofbackup versions, which must then be deleted. Emacs can do thisautomatically or it can ask the user whether to delete them.@defopt kept-new-versionsThe value of this variable is the number of newest versions to keepwhen a new numbered backup is made. The newly made backup is includedin the count. The default value is 2.@end defopt@defopt kept-old-versionsThe value of this variable is the number of oldest versions to keepwhen a new numbered backup is made. The default value is 2.@end defopt If there are backups numbered 1, 2, 3, 5, and 7, and both of thesevariables have the value 2, then the backups numbered 1 and 2 are keptas old versions and those numbered 5 and 7 are kept as new versions;backup version 3 is excess. The function @code{find-backup-file-name}(@pxref{Backup Names}) is responsible for determining which backupversions to delete, but does not delete them itself.@defopt trim-versions-without-askingIf this variable is non-@code{nil}, then saving a file deletes excessbackup versions silently. Otherwise, it asks the user whether to deletethem.@end defopt@defopt dired-kept-versionsThis variable specifies how many of the newest backup versions to keepin the Dired command @kbd{.} (@code{dired-clean-directory}). That's thesame thing @code{kept-new-versions} specifies when you make a new backupfile. The default value is 2.@end defopt@node Backup Names@subsection Naming Backup Files The functions in this section are documented mainly because you cancustomize the naming conventions for backup files by redefining them.If you change one, you probably need to change the rest.@defun backup-file-name-p filenameThis function returns a non-@code{nil} value if @var{filename} is apossible name for a backup file. A file with the name @var{filename}need not exist; the function just checks the name.@smallexample@group(backup-file-name-p "foo") @result{} nil@end group@group(backup-file-name-p "foo~") @result{} 3@end group@end smallexampleThe standard definition of this function is as follows:@smallexample@group(defun backup-file-name-p (file) "Return non-nil if FILE is a backup file \name (numeric or not)..." (string-match "~$" file))@end group@end smallexample@noindentThus, the function returns a non-@code{nil} value if the file name endswith a @samp{~}. (We use a backslash to split the documentationstring's first line into two lines in the text, but produce just oneline in the string itself.)This simple expression is placed in a separate function to make it easyto redefine for customization.@end defun@defun make-backup-file-name filenameThis function returns a string that is the name to use for anon-numbered backup file for file @var{filename}. On Unix, this is just@var{filename} with a tilde appended.The standard definition of this function is as follows:@smallexample@group(defun make-backup-file-name (file) "Create the non-numeric backup file name for FILE.@dots{}" (concat file "~"))@end group@end smallexampleYou can change the backup-file naming convention by redefining thisfunction. The following example redefines @code{make-backup-file-name}to prepend a @samp{.} in addition to appending a tilde:@smallexample@group(defun make-backup-file-name (filename) (concat "." filename "~"))@end group@group(make-backup-file-name "backups.texi") @result{} ".backups.texi~"@end group@end smallexample@end defun@defun find-backup-file-name filenameThis function computes the file name for a new backup file for@var{filename}. It may also propose certain existing backup files fordeletion. @code{find-backup-file-name} returns a list whose @sc{car} isthe name for the new backup file and whose @sc{cdr} is a list of backupfiles whose deletion is proposed.Two variables, @code{kept-old-versions} and @code{kept-new-versions},determine which backup versions should be kept. This function keepsthose versions by excluding them from the @sc{cdr} of the value.@xref{Numbered Backups}.In this example, the value says that @file{~rms/foo.~5~} is the nameto use for the new backup file, and @file{~rms/foo.~3~} is an ``excess''version that the caller should consider deleting now.@smallexample@group(find-backup-file-name "~rms/foo") @result{} ("~rms/foo.~5~" "~rms/foo.~3~")@end group@end smallexample@end defun@c Emacs 19 feature@defun file-newest-backup filenameThis function returns the name of the most recent backup file for@var{filename}, or @code{nil} if that file has no backup files.Some file comparison commands use this function so that they canautomatically compare a file with its most recent backup.@end defun @node Auto-Saving@section Auto-Saving@cindex auto-saving Emacs periodically saves all files that you are visiting; this iscalled @dfn{auto-saving}. Auto-saving prevents you from losing morethan a limited amount of work if the system crashes. By default,auto-saves happen every 300 keystrokes, or after around 30 seconds ofidle time. @xref{Auto-Save, Auto-Save, Auto-Saving: Protection AgainstDisasters, emacs, The GNU Emacs Manual}, for information on auto-savefor users. Here we describe the functions used to implement auto-savingand the variables that control them.@defvar buffer-auto-save-file-nameThis buffer-local variable is the name of the file used forauto-saving the current buffer. It is @code{nil} if the buffershould not be auto-saved.@example@groupbuffer-auto-save-file-name=> "/xcssun/users/rms/lewis/#files.texi#"@end group@end example@end defvar@deffn Command auto-save-mode argWhen used interactively without an argument, this command is a toggleswitch: it turns on auto-saving of the current buffer if it is off, andvice-versa. With an argument @var{arg}, the command turns auto-savingon if the value of @var{arg} is @code{t}, a nonempty list, or a positiveinteger. Otherwise, it turns auto-saving off.@end deffn@defun auto-save-file-name-p filenameThis function returns a non-@code{nil} value if @var{filename} is astring that could be the name of an auto-save file. It works based onknowledge of the naming convention for auto-save files: a name thatbegins and ends with hash marks (@samp{#}) is a possible auto-save filename. The argument @var{filename} should not contain a directory part.@example@group(make-auto-save-file-name) @result{} "/xcssun/users/rms/lewis/#files.texi#"@end group@group(auto-save-file-name-p "#files.texi#") @result{} 0@end group@group(auto-save-file-name-p "files.texi") @result{} nil@end group@end exampleThe standard definition of this function is as follows:@example@group(defun auto-save-file-name-p (filename) "Return non-nil if FILENAME can be yielded by..." (string-match "^#.*#$" filename))@end group@end exampleThis function exists so that you can customize it if you wish tochange the naming convention for auto-save files. If you redefine it,be sure to redefine the function @code{make-auto-save-file-name}correspondingly.@end defun@defun make-auto-save-file-nameThis function returns the file name to use for auto-saving the currentbuffer. This is just the file name with hash marks (@samp{#}) appendedand prepended to it. This function does not look at the variable@code{auto-save-visited-file-name} (described below); you should checkthat before calling this function.@example@group(make-auto-save-file-name) @result{} "/xcssun/users/rms/lewis/#backup.texi#"@end group@end exampleThe standard definition of this function is as follows:@example@group(defun make-auto-save-file-name () "Return file name to use for auto-saves \of current buffer.@dots{}" (if buffer-file-name@end group@group (concat (file-name-directory buffer-file-name) "#" (file-name-nondirectory buffer-file-name) "#") (expand-file-name (concat "#%" (buffer-name) "#"))))@end group@end exampleThis exists as a separate function so that you can redefine it tocustomize the naming convention for auto-save files. Be sure tochange @code{auto-save-file-name-p} in a corresponding way.@end defun@defvar auto-save-visited-file-nameIf this variable is non-@code{nil}, Emacs auto-saves buffers inthe files they are visiting. That is, the auto-save is done in the samefile that you are editing. Normally, this variable is @code{nil}, soauto-save files have distinct names that are created by@code{make-auto-save-file-name}.When you change the value of this variable, the value does not takeeffect until the next time auto-save mode is reenabled in any givenbuffer. If auto-save mode is already enabled, auto-saves continue to goin the same file name until @code{auto-save-mode} is called again.@end defvar@defun recent-auto-save-pThis function returns @code{t} if the current buffer has beenauto-saved since the last time it was read in or saved.@end defun@defun set-buffer-auto-savedThis function marks the current buffer as auto-saved. The buffer willnot be auto-saved again until the buffer text is changed again. Thefunction returns @code{nil}.@end defun@defopt auto-save-intervalThe value of this variable is the number of characters that Emacsreads from the keyboard between auto-saves. Each time this many morecharacters are read, auto-saving is done for all buffers in which it isenabled.@end defopt@defopt auto-save-timeoutThe value of this variable is the number of seconds of idle time thatshould cause auto-saving. Each time the user pauses for this long,Emacs auto-saves any buffers that need it. (Actually, the specifiedtimeout is multiplied by a factor depending on the size of the currentbuffer.)@end defopt@defvar auto-save-hookThis normal hook is run whenever an auto-save is about to happen.@end defvar@defopt auto-save-defaultIf this variable is non-@code{nil}, buffers that are visiting fileshave auto-saving enabled by default. Otherwise, they do not.@end defopt@deffn Command do-auto-save &optional no-messageThis function auto-saves all buffers that need to be auto-saved. Itsaves all buffers for which auto-saving is enabled and that have beenchanged since the previous auto-save.Normally, if any buffers are auto-saved, a message that says@samp{Auto-saving...} is displayed in the echo area while auto-saving isgoing on. However, if @var{no-message} is non-@code{nil}, the messageis inhibited.@end deffn@defun delete-auto-save-file-if-necessaryThis function deletes the current buffer's auto-save file if@code{delete-auto-save-files} is non-@code{nil}. It is called everytime a buffer is saved.@end defun@defvar delete-auto-save-filesThis variable is used by the function@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil},Emacs deletes auto-save files when a true save is done (in the visitedfile). This saves disk space and unclutters your directory.@end defvar@defun rename-auto-save-fileThis function adjusts the current buffer's auto-save file name if thevisited file name has changed. It also renames an existing auto-savefile. If the visited file name has not changed, this function doesnothing.@end defun@defvar buffer-saved-sizeThe value of this buffer-local variable is the length of the currentbuffer as of the last time it was read in, saved, or auto-saved. This isused to detect a substantial decrease in size, and turn off auto-savingin response.If it is -1, that means auto-saving is temporarily shut off in thisbuffer due to a substantial deletion. Explicitly saving the bufferstores a positive value in this variable, thus reenabling auto-save.Turning auto-save mode off or on also alters this variable.@end defvar@node Reverting@section Reverting If you have made extensive changes to a file and then change your mindabout them, you can get rid of them by reading in the previous versionof the file with the @code{revert-buffer} command. @xref{Reverting, ,Reverting a Buffer, emacs, The GNU Emacs Manual}.@deffn Command revert-buffer &optional check-auto-save noconfirmThis command replaces the buffer text with the text of the visitedfile on disk. This action undoes all changes since the file was visitedor saved.If the argument @var{check-auto-save} is non-@code{nil}, and thelatest auto-save file is more recent than the visited file,@code{revert-buffer} asks the user whether to use that instead.Otherwise, it always uses the text of the visited file itself.Interactively, @var{check-auto-save} is set if there is a numeric prefixargument.Normally, @code{revert-buffer} asks for confirmation before it changesthe buffer; but if the argument @var{noconfirm} is non-@code{nil},@code{revert-buffer} does not ask for confirmation.Reverting tries to preserve marker positions in the buffer by using thereplacement feature of @code{insert-file-contents}. If the buffercontents and the file contents are identical before the revertoperation, reverting preserves all the markers. If they are notidentical, reverting does change the buffer; then it preserves themarkers in the unchanged text (if any) at the beginning and end of thebuffer. Preserving any additional markers would be problematical.@end deffnYou can customize how @code{revert-buffer} does its work by settingthese variables---typically, as buffer-local variables.@defvar revert-buffer-functionThe value of this variable is the function to use to revert this buffer.If non-@code{nil}, it is called as a function with no arguments to dothe work of reverting. If the value is @code{nil}, reverting works theusual way.Modes such as Dired mode, in which the text being edited does notconsist of a file's contents but can be regenerated in some otherfashion, give this variable a buffer-local value that is a function toregenerate the contents.@end defvar@defvar revert-buffer-insert-file-contents-functionThe value of this variable, if non-@code{nil}, is the function to use toinsert contents when reverting this buffer. The function receives twoarguments, first the file name to use; second, @code{t} if the user hasasked to read the auto-save file.@end defvar@defvar before-revert-hookThis normal hook is run by @code{revert-buffer} before actuallyinserting the modified contents---but only if@code{revert-buffer-function} is @code{nil}.Font Lock mode uses this hook to record that the buffer contents are nolonger fontified.@end defvar@defvar after-revert-hookThis normal hook is run by @code{revert-buffer} after actually insertingthe modified contents---but only if @code{revert-buffer-function} is@code{nil}.Font Lock mode uses this hook to recompute the fonts for the updatedbuffer contents.@end defvar@deffn Command recover-file filenameThis function visits @var{filename}, but gets the contents from itslast auto-save file. This is useful after the system has crashed, toresume editing the same file without losing all the work done in theprevious session.An error is signaled if there is no auto-save file for @var{filename},or if @var{filename} is newer than its auto-save file. If@var{filename} does not exist, but its auto-save file does, then theauto-save file is read as usual. This last situation may occur if youvisited a nonexistent file and never actually saved it.@end deffn