@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999@c 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-all-local-variables} does not alter it.@end defvar@defopt make-backup-filesThis 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---provided that @code{backup-inhibited}is @code{nil} (see below).The following example shows how to change the @code{make-backup-files}variable only in the Rmail buffers and not elsewhere. Setting it@code{nil} stops Emacs from making backups of these files, which maysave disk space. (You would put this code in your init 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.@findex normal-backup-enable-predicateThe default value is @code{normal-backup-enable-predicate}, which checksfor files in @code{temporary-file-directory} and@code{small-temporary-file-directory}.@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. For example, VC sets thisvariable non-@code{nil} to prevent making backups for files managedwith a version control system.This is a permanent local, so that changing the major mode does not loseits value. Major modes should not set this variable---they should set@code{make-backup-files} instead.@end defvar@defvar backup-directory-alist@tindex backup-directory-alistThis variable's value is an alist of filename patterns and backupdirectory names. Each element looks like@smallexample(@var{regexp} . @var{directory})@end smallexample@noindentBackups of files with names matching @var{regexp} will be made in@var{directory}. @var{directory} may be relative or absolute. If it isabsolute, so that all matching files are backed up into the samedirectory, the file names in this directory will be the full name of thefile backed up with all directory separators changed to @samp{!} toprevent clashes. This will not work correctly if your filesystemtruncates the resulting name.For the common case of all backups going into one directory, the alistshould contain a single element pairing @samp{"."} with the appropriatedirectory name.If this variable is @code{nil}, or it fails to match a filename, thebackup is made in the original file's directory.On MS-DOS filesystems without long names this variable is alwaysignored.@end defvar@defvar make-backup-file-name-function@tindex make-backup-file-name-functionThis variable's value is a function to use for making backups instead ofthe default @code{make-backup-file-name}. A value of nil gives thedefault @code{make-backup-file-name} behaviour.This could be buffer-local to do something special for specificfiles. If you define it, you may need to change@code{backup-file-name-p} and @code{file-name-sans-versions} too.@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 continue to refer to thecurrent (updated) version of the file. The file's owner and group willbe 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@defvar backup-by-copying-when-privileged-mismatchThis variable, if non-@code{nil}, specifies the same behavior as@code{backup-by-copying-when-mismatch}, but only for certain user-idvalues: namely, those less than or equal to a certain number. You setthis variable to that number.Thus, if you set @code{backup-by-copying-when-privileged-mismatch}to 0, backup by copying is done for the superuser only,when necessary to prevent a change in the owner of the file.The default is 200.@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 delete-old-versionsIf this variable is @code{t}, then saving a file deletes excessbackup versions silently. If it is @code{nil}, that meansto ask for confirmation before deleting excess backups.Otherwise, they are not deleted at all.@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, on most operating systems, isas follows:@smallexample@group(defun make-backup-file-name (file) "Create the non-numeric backup file name for FILE..." (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) (expand-file-name (concat "." (file-name-nondirectory filename) "~") (file-name-directory filename)))@end group@group(make-backup-file-name "backups.texi") @result{} ".backups.texi~"@end group@end smallexampleSome parts of Emacs, including some Dired commands, assume that backupfile names end with @samp{~}. If you do not follow that convention, itwill not cause serious problems, but these commands may giveless-than-desirable results.@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 @result{} "/xcssun/users/rms/lewis/#backups.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 assumesthe usual 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/#backups.texi#"@end group@group(auto-save-file-name-p "#backups.texi#") @result{} 0@end group@group(auto-save-file-name-p "backups.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{#}) prependedand appended to it. This function does not look at the variable@code{auto-save-visited-file-name} (described below); callers of thisfunction should check that variable first.@example@group(make-auto-save-file-name) @result{} "/xcssun/users/rms/lewis/#backups.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.." (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 new value does not takeeffect in an existing buffer until the next time auto-save mode isreenabled in it. If auto-save mode is already enabled, auto-savescontinue to go in the same file name until @code{auto-save-mode} iscalled 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 specifies how often to do auto-saving, interms of number of input events. Each time this many additional inputevents are read, Emacs does auto-saving for all buffers in which that 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 does auto-saving for all buffers in which that is enabled. (Ifthe current buffer is large, the specified timeout is multiplied by afactor that increases as the size increases; for a million-bytebuffer, the factor is almost 4.)If the value is zero or nil, then auto-saving is not done as a resultof idleness, only after a certain number of input eventsas specified by @code{auto-save-interval}.@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-message current-onlyThis 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.If @var{current-only} is non-@code{nil}, only the current bufferis auto-saved.@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, when it was last read in, saved, or auto-saved. This isused to detect a substantial decrease in size, and turn off auto-savingin response.If it is @minus{}1, that means auto-saving is temporarily shut off inthis buffer due to a substantial decrease in size. Explicitly savingthe buffer stores a positive value in this variable, thus reenablingauto-saving. Turning auto-save mode off or on also updates thisvariable, so that the substantial decrease in size is forgotten.@end defvar@defvar auto-save-list-file-nameThis variable (if non-@code{nil}) specifies a file for recording thenames of all the auto-save files. Each time Emacs does auto-saving, itwrites two lines into this file for each buffer that has auto-savingenabled. The first line gives the name of the visited file (it's emptyif the buffer has none), and the second gives the name of the auto-savefile.When Emacs exits normally, it deletes this file; if Emacs crashes, youcan look in the file to find all the auto-save files that might containwork that was otherwise lost. The @code{recover-session} command usesthis file to find them.The default name for this file specifies your home directory and startswith @samp{.saves-}. It also contains the Emacs process @sc{id} and thehost name.@end defvar@defvar auto-save-list-file-prefix@tindex auto-save-list-file-prefixAfter Emacs reads your init file, it initializes@code{auto-save-list-file-name} (if you have not already set itnon-@code{nil}) based on this prefix, adding the host name and processID. If you set this to @code{nil} in your init file, then Emacs doesnot initialize @code{auto-save-list-file-name}.@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 ignore-auto 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.By default, if the latest auto-save file is more recent than the visitedfile, and the argument @var{ignore-auto} is @code{nil},@code{revert-buffer} asks the user whether to use that auto-saveinstead. When you invoke this command interactively, @var{ignore-auto}is @code{t} if there is no numeric prefix argument; thus, theinteractive default is not to check the auto-save file.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; in that case, it preservesthe markers in the unchanged text (if any) at the beginning and end ofthe buffer. Preserving any additional markers would be problematical.@end deffnYou can customize how @code{revert-buffer} does its work by settingthe variables described in the rest of this section.@defvar revert-without-queryThis variable holds a list of files that should be reverted withoutquery. The value is a list of regular expressions. If the visited filename matches one of these regular expressions, and the file has changedon disk but the buffer is not modified, then @code{revert-buffer}reverts the file without asking the user for confirmation.@end defvar Some major modes customize @code{revert-buffer} by makingbuffer-local bindings for these 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, can 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}, specifies the function to use toinsert the updated contents when reverting this buffer. The functionreceives two arguments: first the file name to use; second, @code{t} ifthe user has asked to read the auto-save file.The reason for a mode to set this variable instead of@code{revert-buffer-function} is to avoid duplicating or replacing therest of what @code{revert-buffer} does: asking for confirmation,clearing the undo list, deciding the proper major mode, and running thehooks listed below.@end defvar@defvar before-revert-hookThis normal hook is run by @code{revert-buffer} beforeinserting the modified contents---but only if@code{revert-buffer-function} is @code{nil}.@end defvar@defvar after-revert-hookThis normal hook is run by @code{revert-buffer} after insertingthe modified contents---but only if @code{revert-buffer-function} is@code{nil}.@end defvar