@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2002, 2003, 2004,
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/backups
@node Backups and Auto-Saving, Buffers, Files, Top
This function makes a backup of the file visited by the current
buffer, if appropriate. It is called by @code{save-buffer} before
saving the buffer the first time.
+
+If a backup was made by renaming, the return value is a cons cell of
+the form (@var{modes} . @var{backupname}), where @var{modes} are the
+mode bits of the original file, as returned by @code{file-modes}
+(@pxref{File Attributes,, Other Information about Files}), and
+@var{backupname} is the name of the backup. In all other cases, that
+is, if a backup was made by copying or if no backup was made, this
+function returns @code{nil}.
@end defun
@defvar buffer-backed-up
been backed up on account of this buffer. If it is non-@code{nil}, then
the backup file has been written. Otherwise, the file should be backed
up when it is next saved (if backups are enabled). This is a
-permanent local; @code{kill-local-variables} does not alter it.
+permanent local; @code{kill-all-local-variables} does not alter it.
@end defvar
@defopt make-backup-files
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 may
-save disk space. (You would put this code in your @file{.emacs} file.)
+save disk space. (You would put this code in your init file.)
@smallexample
@group
-(add-hook 'rmail-mode-hook
+(add-hook 'rmail-mode-hook
(function (lambda ()
- (make-local-variable
+ (make-local-variable
'make-backup-files)
(setq make-backup-files nil))))
@end group
@defvar backup-enable-predicate
This variable's value is a function to be called on certain occasions to
decide whether a file should have backup files. The function receives
-one argument, a file name to consider. If the function returns
+one argument, an absolute file name to consider. If the function returns
@code{nil}, backups are disabled for that file. Otherwise, the other
variables 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
+@findex normal-backup-enable-predicate
+The default value is @code{normal-backup-enable-predicate}, which checks
+for files in @code{temporary-file-directory} and
+@code{small-temporary-file-directory}.
@end defvar
@defvar backup-inhibited
@code{make-backup-files} instead.
@end defvar
+@defvar backup-directory-alist
+@tindex backup-directory-alist
+This variable's value is an alist of filename patterns and backup
+directory names. Each element looks like
+@smallexample
+(@var{regexp} . @var{directory})
+@end smallexample
+
+@noindent
+Backups of files with names matching @var{regexp} will be made in
+@var{directory}. @var{directory} may be relative or absolute. If it is
+absolute, so that all matching files are backed up into the same
+directory, the file names in this directory will be the full name of the
+file backed up with all directory separators changed to @samp{!} to
+prevent clashes. This will not work correctly if your filesystem
+truncates the resulting name.
+
+For the common case of all backups going into one directory, the alist
+should contain a single element pairing @samp{"."} with the appropriate
+directory name.
+
+If this variable is @code{nil}, or it fails to match a filename, the
+backup is made in the original file's directory.
+
+On MS-DOS filesystems without long names this variable is always
+ignored.
+@end defvar
+
+@defvar make-backup-file-name-function
+@tindex make-backup-file-name-function
+This variable's value is a function to use for making backups instead
+of the default @code{make-backup-file-name}. A value of @code{nil}
+gives the default @code{make-backup-file-name} behavior.
+@xref{Backup Names,, Naming Backup Files}.
+
+This could be buffer-local to do something special for specific
+files. 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:
+ There are two ways that Emacs can make a backup file:
@itemize @bullet
@item
if non-@code{nil}, also has this effect (as a sideline of its main
significance). @xref{Saving Buffers}.
-@defvar backup-by-copying
+@defopt backup-by-copying
If this variable is non-@code{nil}, Emacs always makes backup files by
copying.
-@end defvar
+@end defopt
- The following two variables, when non-@code{nil}, cause the second
+ The following three variables, when non-@code{nil}, cause the second
method to be used in certain special cases. They have no effect on the
treatment of files that don't fall into the special cases.
-@defvar backup-by-copying-when-linked
+@defopt backup-by-copying-when-linked
If this variable is non-@code{nil}, Emacs makes backups by copying for
files 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 is
non-@code{nil}.
-@end defvar
+@end defopt
-@defvar backup-by-copying-when-mismatch
+@defopt backup-by-copying-when-mismatch
If this variable is non-@code{nil}, Emacs makes backups by copying in cases
where renaming would change either the owner or the group of the file.
This variable is significant only if @code{backup-by-copying} is
@code{nil}, since copying is always used when that variable is
non-@code{nil}.
-@end defvar
+@end defopt
+
+@defopt backup-by-copying-when-privileged-mismatch
+This variable, if non-@code{nil}, specifies the same behavior as
+@code{backup-by-copying-when-mismatch}, but only for certain user-id
+values: namely, those less than or equal to a certain number. You set
+this 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 defopt
@node Numbered Backups
@subsection Making and Deleting Numbered Backup Files
@table @asis
@item @code{nil}
Make numbered backups if the visited file already has numbered backups;
-otherwise, do not.
+otherwise, do not. This is the default.
@item @code{never}
Do not make numbered backups.
(@pxref{Backup Names}) is responsible for determining which backup
versions to delete, but does not delete them itself.
-@tindex delete-old-versions
@defopt delete-old-versions
-If this variable is non-@code{nil}, then saving a file deletes excess
-backup versions silently. Otherwise, it asks the user whether to delete
-them.
+If this variable is @code{t}, then saving a file deletes excess
+backup versions silently. If it is @code{nil}, that means
+to ask for confirmation before deleting excess backups.
+Otherwise, they are not deleted at all.
@end defopt
@defopt dired-kept-versions
(defun backup-file-name-p (file)
"Return non-nil if FILE is a backup file \
name (numeric or not)..."
- (string-match "~$" file))
+ (string-match "~\\'" file))
@end group
@end smallexample
@smallexample
@group
(defun make-backup-file-name (file)
- "Create the non-numeric backup file name for FILE@enddots{}"
+ "Create the non-numeric backup file name for FILE..."
(concat file "~"))
@end group
@end smallexample
@var{filename}. It may also propose certain existing backup files for
deletion. @code{find-backup-file-name} returns a list whose @sc{car} is
the name for the new backup file and whose @sc{cdr} is a list of backup
-files whose deletion is proposed.
+files whose deletion is proposed. The value can also be @code{nil},
+which means not to make a backup.
Two variables, @code{kept-old-versions} and @code{kept-new-versions},
determine which backup versions should be kept. This function keeps
Some file comparison commands use this function so that they can
automatically compare a file with its most recent backup.
-@end defun
+@end defun
@node Auto-Saving
@section Auto-Saving
called @dfn{auto-saving}. Auto-saving prevents you from losing more
than a limited amount of work if the system crashes. By default,
auto-saves happen every 300 keystrokes, or after around 30 seconds of
-idle time. @xref{Auto-Save, Auto-Save, Auto-Saving: Protection Against
+idle time. @xref{Auto Save, Auto Save, Auto-Saving: Protection Against
Disasters, emacs, The GNU Emacs Manual}, for information on auto-save
for users. Here we describe the functions used to implement auto-saving
and the variables that control them.
@example
@group
buffer-auto-save-file-name
-=> "/xcssun/users/rms/lewis/#files.texi#"
+ @result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@end example
@end defvar
@deffn Command auto-save-mode arg
When used interactively without an argument, this command is a toggle
switch: it turns on auto-saving of the current buffer if it is off, and
-vice-versa. With an argument @var{arg}, the command turns auto-saving
+vice versa. With an argument @var{arg}, the command turns auto-saving
on if the value of @var{arg} is @code{t}, a nonempty list, or a positive
integer. Otherwise, it turns auto-saving off.
@end deffn
@defun auto-save-file-name-p filename
This function returns a non-@code{nil} value if @var{filename} is a
-string that could be the name of an auto-save file. It works based on
-knowledge of the naming convention for auto-save files: a name that
+string that could be the name of an auto-save file. It assumes
+the usual naming convention for auto-save files: a name that
begins and ends with hash marks (@samp{#}) is a possible auto-save file
name. The argument @var{filename} should not contain a directory part.
@example
@group
(make-auto-save-file-name)
- @result{} "/xcssun/users/rms/lewis/#files.texi#"
+ @result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@group
-(auto-save-file-name-p "#files.texi#")
+(auto-save-file-name-p "#backups.texi#")
@result{} 0
@end group
@group
-(auto-save-file-name-p "files.texi")
+(auto-save-file-name-p "backups.texi")
@result{} nil
@end group
@end example
This function returns the file name to use for auto-saving the current
buffer. This is just the file name with hash marks (@samp{#}) prepended
and appended to it. This function does not look at the variable
-@code{auto-save-visited-file-name} (described below); you should check
-that before calling this function.
+@code{auto-save-visited-file-name} (described below); callers of this
+function should check that variable first.
@example
@group
(make-auto-save-file-name)
- @result{} "/xcssun/users/rms/lewis/#backup.texi#"
+ @result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@end example
-The standard definition of this function is as follows:
+Here is a simplified version of the standard definition of this
+function:
@example
@group
(defun make-auto-save-file-name ()
"Return file name to use for auto-saves \
-of current buffer@enddots{}"
+of current buffer.."
(if buffer-file-name
@end group
@group
change @code{auto-save-file-name-p} in a corresponding way.
@end defun
-@defvar auto-save-visited-file-name
+@defopt auto-save-visited-file-name
If this variable is non-@code{nil}, Emacs auto-saves buffers in
the files they are visiting. That is, the auto-save is done in the same
file that you are editing. Normally, this variable is @code{nil}, so
auto-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 take
-effect until the next time auto-save mode is reenabled in any given
-buffer. If auto-save mode is already enabled, auto-saves continue to go
-in the same file name until @code{auto-save-mode} is called again.
-@end defvar
+When you change the value of this variable, the new value does not take
+effect in an existing buffer until the next time auto-save mode is
+reenabled in it. If auto-save mode is already enabled, auto-saves
+continue to go in the same file name until @code{auto-save-mode} is
+called again.
+@end defopt
@defun recent-auto-save-p
This function returns @code{t} if the current buffer has been
@end defun
@defopt auto-save-interval
-The value of this variable is the number of characters that Emacs
-reads from the keyboard between auto-saves. Each time this many more
-characters are read, auto-saving is done for all buffers in which it is
-enabled.
+The value of this variable specifies how often to do auto-saving, in
+terms of number of input events. Each time this many additional input
+events are read, Emacs does auto-saving for all buffers in which that is
+enabled. Setting this to zero disables autosaving based on the
+number of characters typed.
@end defopt
@defopt auto-save-timeout
The value of this variable is the number of seconds of idle time that
should cause auto-saving. Each time the user pauses for this long,
-Emacs auto-saves any buffers that need it. (Actually, the specified
-timeout is multiplied by a factor depending on the size of the current
-buffer.)
+Emacs does auto-saving for all buffers in which that is enabled. (If
+the current buffer is large, the specified timeout is multiplied by a
+factor that increases as the size increases; for a million-byte
+buffer, the factor is almost 4.)
+
+If the value is zero or @code{nil}, then auto-saving is not done as a
+result of idleness, only after a certain number of input events as
+specified by @code{auto-save-interval}.
@end defopt
@defvar auto-save-hook
saves all buffers for which auto-saving is enabled and that have been
changed 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 is
-going on. However, if @var{no-message} is non-@code{nil}, the message
-is inhibited.
+If any buffers are auto-saved, @code{do-auto-save} normally displays a
+message saying @samp{Auto-saving...} in the echo area while
+auto-saving is going on. However, if @var{no-message} is
+non-@code{nil}, the message is inhibited.
If @var{current-only} is non-@code{nil}, only the current buffer
is auto-saved.
@end deffn
-@defun delete-auto-save-file-if-necessary
+@defun delete-auto-save-file-if-necessary &optional force
This function deletes the current buffer's auto-save file if
@code{delete-auto-save-files} is non-@code{nil}. It is called every
time a buffer is saved.
+
+Unless @var{force} is non-@code{nil}, this function only deletes the
+file if it was written by the current Emacs session since the last
+true save.
@end defun
-@defvar delete-auto-save-files
+@defopt delete-auto-save-files
This 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 visited
file). This saves disk space and unclutters your directory.
-@end defvar
+@end defopt
@defun rename-auto-save-file
This function adjusts the current buffer's auto-save file name if the
visited file name has changed. It also renames an existing auto-save
-file. If the visited file name has not changed, this function does
-nothing.
+file, if it was made in the current Emacs session. If the visited
+file name has not changed, this function does nothing.
@end defun
@defvar buffer-saved-size
The value of this buffer-local variable is the length of the current
-buffer as of the last time it was read in, saved, or auto-saved. This is
+buffer, when it was last read in, saved, or auto-saved. This is
used to detect a substantial decrease in size, and turn off auto-saving
in response.
-If it is @minus{}1, that means auto-saving is temporarily shut off in this
-buffer due to a substantial deletion. Explicitly saving the buffer
-stores a positive value in this variable, thus reenabling auto-saving.
-Turning auto-save mode off or on also alters this variable.
+If it is @minus{}1, that means auto-saving is temporarily shut off in
+this buffer due to a substantial decrease in size. Explicitly saving
+the buffer stores a positive value in this variable, thus reenabling
+auto-saving. Turning auto-save mode off or on also updates this
+variable, so that the substantial decrease in size is forgotten.
@end defvar
@defvar auto-save-list-file-name
if the buffer has none), and the second gives the name of the auto-save
file.
-If Emacs exits normally, it deletes this file. If Emacs crashes, you
+When Emacs exits normally, it deletes this file; if Emacs crashes, you
can look in the file to find all the auto-save files that might contain
work that was otherwise lost. The @code{recover-session} command uses
-these files.
+this file to find them.
-The default name for this file is in your home directory and starts with
-@samp{.saves-}. It also contains the Emacs process @sc{id} and the host
-name.
+The default name for this file specifies your home directory and starts
+with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the
+host name.
+@end defvar
+
+@defvar auto-save-list-file-prefix
+@tindex auto-save-list-file-prefix
+After Emacs reads your init file, it initializes
+@code{auto-save-list-file-name} (if you have not already set it
+non-@code{nil}) based on this prefix, adding the host name and process
+ID. If you set this to @code{nil} in your init file, then Emacs does
+not initialize @code{auto-save-list-file-name}.
@end defvar
@node Reverting
of 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 noconfirm
+@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes
This command replaces the buffer text with the text of the visited
file on disk. This action undoes all changes since the file was visited
or saved.
By default, if the latest auto-save file is more recent than the visited
-file, @code{revert-buffer} asks the user whether to use that instead.
-But if the argument @var{ignore-auto} is non-@code{nil}, then only the
-the visited file itself is used. Interactively, @var{ignore-auto} is
-@code{t} unless there is a numeric prefix argument; thus, the
-interactive default is to check the auto-save file.
+file, and the argument @var{ignore-auto} is @code{nil},
+@code{revert-buffer} asks the user whether to use that auto-save
+instead. When you invoke this command interactively, @var{ignore-auto}
+is @code{t} if there is no numeric prefix argument; thus, the
+interactive default is not to check the auto-save file.
Normally, @code{revert-buffer} asks for confirmation before it changes
the buffer; but if the argument @var{noconfirm} is non-@code{nil},
@code{revert-buffer} does not ask for confirmation.
+Normally, this command reinitializes the file's major and minor modes
+using @code{normal-mode}. But if @var{preserve-modes} is
+non-@code{nil}, the modes remain unchanged.
+
Reverting tries to preserve marker positions in the buffer by using the
replacement feature of @code{insert-file-contents}. If the buffer
contents and the file contents are identical before the revert
operation, reverting preserves all the markers. If they are not
-identical, reverting does change the buffer; then it preserves the
-markers in the unchanged text (if any) at the beginning and end of the
-buffer. Preserving any additional markers would be problematical.
+identical, reverting does change the buffer; in that case, it preserves
+the markers in the unchanged text (if any) at the beginning and end of
+the buffer. Preserving any additional markers would be problematical.
@end deffn
You can customize how @code{revert-buffer} does its work by setting
-these variables---typically, as buffer-local variables.
+the variables described in the rest of this section.
-@defvar revert-without-query
+@defopt revert-without-query
This variable holds a list of files that should be reverted without
-query. The value is a list of regular expressions. If a file name
-matches one of these regular expressions, then @code{revert-buffer}
-reverts the file without asking the user for confirmation, if the file
-has changed on disk and the buffer is not modified.
-@end defvar
+query. The value is a list of regular expressions. If the visited file
+name matches one of these regular expressions, and the file has changed
+on disk but the buffer is not modified, then @code{revert-buffer}
+reverts the file without asking the user for confirmation.
+@end defopt
+
+ Some major modes customize @code{revert-buffer} by making
+buffer-local bindings for these variables:
@defvar revert-buffer-function
-The 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 do
-the work of reverting. If the value is @code{nil}, reverting works the
-usual way.
+@anchor{Definition of revert-buffer-function}
+The value of this variable is the function to use to revert this
+buffer. If non-@code{nil}, it should be a function with two optional
+arguments to do the work of reverting. The two optional arguments,
+@var{ignore-auto} and @var{noconfirm}, are the arguments that
+@code{revert-buffer} received. If the value is @code{nil}, reverting
+works the usual way.
Modes such as Dired mode, in which the text being edited does not
consist of a file's contents but can be regenerated in some other
-fashion, give this variable a buffer-local value that is a function to
+fashion, can give this variable a buffer-local value that is a function to
regenerate the contents.
@end defvar
@defvar revert-buffer-insert-file-contents-function
-The value of this variable, if non-@code{nil}, is the function to use to
+The value of this variable, if non-@code{nil}, specifies the function to use to
insert the updated contents when reverting this buffer. The function
receives two arguments: first the file name to use; second, @code{t} if
the 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 the
+rest of what @code{revert-buffer} does: asking for confirmation,
+clearing the undo list, deciding the proper major mode, and running the
+hooks listed below.
@end defvar
@defvar before-revert-hook
-This normal hook is run by @code{revert-buffer} before actually
+This normal hook is run by @code{revert-buffer} before
inserting the modified contents---but only if
@code{revert-buffer-function} is @code{nil}.
@end defvar
@defvar after-revert-hook
-This normal hook is run by @code{revert-buffer} after actually inserting
+This normal hook is run by @code{revert-buffer} after inserting
the modified contents---but only if @code{revert-buffer-function} is
@code{nil}.
@end defvar
+
+@ignore
+ arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f
+@end ignore