This buffer-local variable indicates whether this buffer's file has
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 backup files are enabled). This is a
+up when it is next saved (if backups are enabled). This is a
permanent 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 it
+This variable determines whether or not to make backup files. If it
is non-@code{nil}, then Emacs creates a backup of each file when it is
-saved for the first time.
+saved 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}
+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
@end smallexample
@end defopt
-@defvar backup-enable-predicate filename
+@defvar backup-enable-predicate
This variable's value is a function to be called on certain occasions to
-decide whether a there should be backup files for file name
-@var{filename}. If it returns @code{nil}, backups are disabled.
-Otherwise, the other variables in this section say whether and how to
-make backups.
+decide whether a file should have backup files. The function receives
+one argument, a 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:
If this variable is non-@code{nil}, backups are inhibited. It records
the result of testing @code{backup-enable-predicate} on the visited file
name. It can also coherently be used by other mechanisms that inhibit
-backups based on which file is visited. Major modes should not set this
-variable.
+backups based on which file is visited. For example, VC sets this
+variable non-@code{nil} to prevent making backups for files managed
+with a version control system.
+
+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
Do not make numbered backups.
@item @var{anything else}
-Do make numbered backups.
+Make numbered backups.
@end table
@end defopt
The use of numbered backups ultimately leads to a large number of
backup versions, which must then be deleted. Emacs can do this
-automatically.
+automatically or it can ask the user whether to delete them.
@defopt kept-new-versions
-The value of this variable is the number of oldest versions to keep
+The value of this variable is the number of newest versions to keep
when a new numbered backup is made. The newly made backup is included
in the count. The default value is 2.
@end defopt
If there are backups numbered 1, 2, 3, 5, and 7, and both of these
variables have the value 2, then the backups numbered 1 and 2 are kept
as old versions and those numbered 5 and 7 are kept as new versions;
-backup version 3 is deleted. The function @code{find-backup-file-name}
+backup version 3 is excess. The function @code{find-backup-file-name}
(@pxref{Backup Names}) is responsible for determining which backup
versions to delete, but does not delete them itself.
@defopt dired-kept-versions
This variable specifies how many of the newest backup versions to keep
in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the
-same thing @code{kept-new-versions} does when you make a new backup
+same thing @code{kept-new-versions} specifies when you make a new backup
file. The default value is 2.
@end defopt
@end defun
@defun make-backup-file-name filename
-This function returns a string which is the name to use for a
+This function returns a string that is the name to use for a
non-numbered backup file for file @var{filename}. On Unix, this is just
@var{filename} with a tilde appended.
@end group
@end smallexample
-You can change the backup file naming convention by redefining this
+You can change the backup-file naming convention by redefining this
function. The following example redefines @code{make-backup-file-name}
-to prepend a @samp{.} as well as appending a tilde:
+to prepend a @samp{.} in addition to appending a tilde:
@smallexample
@group
@c Emacs 19 feature
@defun file-newest-backup filename
This function returns the name of the most recent backup file for
-@var{filename}, or @code{nil} that file has no backup files.
+@var{filename}, or @code{nil} if that file has no backup files.
-Some file comparison commands use this function in order to compare
-a file by default with its most recent backup.
+Some file comparison commands use this function so that they can
+automatically compare a file with its most recent backup.
@end defun
@node Auto-Saving
This function returns the file name to use for auto-saving the current
buffer. This is just the file name with hash marks (@samp{#}) appended
and prepended to it. This function does not look at the variable
-@code{auto-save-visited-file-name}; you should check that before calling
-this function.
+@code{auto-save-visited-file-name} (described below); you should check
+that before calling this function.
@example
@group
@defvar 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 which you are editing. Normally, this variable is @code{nil}, so
+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}.
have auto-saving enabled by default. Otherwise, they do not.
@end defopt
-@deffn Command do-auto-save &optional no-message
+@deffn Command do-auto-save &optional no-message current-only
This function auto-saves all buffers that need to be auto-saved. It
saves all buffers for which auto-saving is enabled and that have been
changed since the previous auto-save.
@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 @var{current-only} is non-@code{nil}, only the current buffer
+is auto-saved.
@end deffn
@defun delete-auto-save-file-if-necessary
@end defun
@defvar buffer-saved-size
-The value of this buffer-local variable is the former length of the
-current buffer, as of the last time it was read in, saved or auto-saved.
-This is used to detect a substantial decrease in size, and turn off
-auto-saving in response.
+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
+used to detect a substantial decrease in size, and turn off auto-saving
+in response.
If it is -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-save.
-Turning Auto-Save mode off or on also alters this variable.
+stores a positive value in this variable, thus reenabling auto-saving.
+Turning auto-save mode off or on also alters this variable.
+@end defvar
+
+@defvar auto-save-list-file-name
+This variable (if non-@code{nil}) specifies a file for recording the
+names of all the auto-save files. Each time Emacs does auto-saving, it
+writes two lines into this file for each buffer that has auto-saving
+enabled. The first line gives the name of the visited file (it's empty
+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
+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.
+
+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.
@end defvar
@node Reverting
@code{revert-buffer} does not ask for confirmation.
Reverting tries to preserve marker positions in the buffer by using the
-replacement feature of @code{insert-file-contents}. If there is no
-actual difference between the buffer and the file, before reversion,
-this preserves all the markers. If reversion does change the buffer,
-this preserves the markers in the unchanged text (if any) at the
-beginning and end of the buffer. Preserving any additional markers
-would be problematical.
-
-If the value of the @code{revert-buffer-function} variable is
-non-@code{nil}, it is called as a function with no arguments to do the
-work.
+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.
@end deffn
+You can customize how @code{revert-buffer} does its work by setting
+these variables---typically, as buffer-local variables.
+
@defvar revert-buffer-function
-The value of this variable is the function to use to revert this
-buffer; but if the value of this variable is @code{nil}, then the
-@code{revert-buffer} function carries out its default action. 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 regenerate the
-contents.
+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.
+
+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
+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 insert contents when reverting this buffer. The function receives
-two arguments, first the file name to use, and second, @code{t} if the
-user has asked to read the auto-save file.
+The value of this variable, if non-@code{nil}, is 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.
@end defvar
@defvar before-revert-hook
buffer contents.
@end defvar
-@deffn Command recover-file filename
-This function visits @var{filename}, but gets the contents from its
-last auto-save file. This is useful after the system has crashed, to
-resume editing the same file without losing all the work done in the
-previous 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 the
-auto-save file is read as usual. This last situation may occur if you
-visited a nonexistent file and never actually saved it.
-@end deffn
-
HCoop / bpt / emacs.git / blobdiff