@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
@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
-@defvar backup-by-copying-when-privileged-mismatch
+@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
when necessary to prevent a change in the owner of the file.
The default is 200.
-@end defvar
+@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 @code{t}, then saving a file deletes excess
backup versions silently. If it is @code{nil}, that means
@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.
@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
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
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 defvar
+@end defopt
@defun recent-auto-save-p
This function returns @code{t} if the current buffer has been
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.
+enabled. Setting this to zero disables autosaving based on the
+number of characters typed.
@end defopt
@defopt auto-save-timeout
should cause auto-saving. Each time the user pauses for this long,
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 depends increases as the size increases; for a million-byte
+factor that increases as the size increases; for a million-byte
buffer, the factor is almost 4.)
-If the value is zero or 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}.
+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
this file to find them.
The default name for this file specifies your home directory and starts
-with @samp{.saves-}. It also contains the Emacs process @sc{id} and the
+with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the
host name.
@end defvar
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, and the argument @var{ignore-auto} is non-@code{nil},
+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} unless there is a numeric prefix argument; thus, the
-interactive default is to check the auto-save file.
+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
You can customize how @code{revert-buffer} does its work by setting
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 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 defvar
+@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
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