comparison lispref/backups.texi @ 54711:12ff04cae768

Various small changes in addition to: (Making Backups): Mention return value of `backup-buffer'. (Auto-Saving): Mention optional FORCE argument to `delete-auto-save-file-if-necessary'. (Reverting): Mention optional PRESERVE-MODES argument to `revert-buffer'. Correct description of `revert-buffer-function'.

54710:a02f0e9c16be

@defun backup-buffer
  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.
@end defun

@defvar buffer-backed-up
  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

@end defopt

@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
@code{nil}, backups are disabled for that file.  Otherwise, the other
variables in this section say whether and how to make backups.

@findex normal-backup-enable-predicate
The default value is @code{normal-backup-enable-predicate}, which checks

@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} behaviour.

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

the second method, which is to copy the original file and overwrite it
with the new buffer contents.  The variable @code{file-precious-flag},
if non-@code{nil}, also has this effect (as a sideline of its main
significance).  @xref{Saving Buffers}.

@defvar backup-by-copying
If this variable is non-@code{nil}, Emacs always makes backup files by
copying.
@end defvar

  The following two 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
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

@defvar 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.

The value has no effect when renaming would not alter the owner or
group of the file; that is, for files which are owned by the user and

user.

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

@defvar 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 defvar

@node Numbered Backups
@subsection Making and Deleting Numbered Backup Files

  If a file's name is @file{foo}, the names of its numbered backup

@defun find-backup-file-name filename
This function computes the file name for a new backup file for
@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.

Two variables, @code{kept-old-versions} and @code{kept-new-versions},
determine which backup versions should be kept.  This function keeps
those versions by excluding them from the @sc{cdr} of the value.
@xref{Numbered Backups}.

This exists as a separate function so that you can redefine it to
customize the naming convention for auto-save files.  Be sure to
change @code{auto-save-file-name-p} in a corresponding way.
@end defun

@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 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 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 defvar

@defun recent-auto-save-p
This function returns @code{t} if the current buffer has been
auto-saved since the last time it was read in or saved.
@end defun

@defopt auto-save-interval
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.
@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,

If @var{current-only} is non-@code{nil}, only the current buffer
is auto-saved.
@end deffn

@defun delete-auto-save-file-if-necessary
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.
@end defun

@defvar 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

@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.
@end defun

@defvar buffer-saved-size
The value of this buffer-local variable is the length of the current
buffer, when it was last read in, saved, or auto-saved.  This is

  If you have made extensive changes to a file and then change your mind
about them, you can get rid of them by reading in the previous version
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
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

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.

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

@end deffn

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
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

  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.

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, can give this variable a buffer-local value that is a function to
regenerate the contents.

54711:12ff04cae768

@defun backup-buffer
  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
  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

@end defopt

@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, 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.

@findex normal-backup-enable-predicate
The default value is @code{normal-backup-enable-predicate}, which checks

@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} behaviour.
@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

the second method, which is to copy the original file and overwrite it
with the new buffer contents.  The variable @code{file-precious-flag},
if non-@code{nil}, also has this effect (as a sideline of its main
significance).  @xref{Saving Buffers}.

@defopt backup-by-copying
If this variable is non-@code{nil}, Emacs always makes backup files by
copying.
@end defopt

  The following two 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.

@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 defopt

@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.

The value has no effect when renaming would not alter the owner or
group of the file; that is, for files which are owned by the user and

user.

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 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

  If a file's name is @file{foo}, the names of its numbered backup

@defun find-backup-file-name filename
This function computes the file name for a new backup file for
@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.  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
those versions by excluding them from the @sc{cdr} of the value.
@xref{Numbered Backups}.

This exists as a separate function so that you can redefine it to
customize the naming convention for auto-save files.  Be sure to
change @code{auto-save-file-name-p} in a corresponding way.
@end defun

@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 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
auto-saved since the last time it was read in or saved.
@end defun

@defopt auto-save-interval
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,

If @var{current-only} is non-@code{nil}, only the current buffer
is auto-saved.
@end deffn

@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

@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 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 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, when it was last read in, saved, or auto-saved.  This is

  If you have made extensive changes to a file and then change your mind
about them, you can get rid of them by reading in the previous version
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 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

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

@end deffn

You can customize how @code{revert-buffer} does its work by setting
the variables described in the rest of this section.

@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 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 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, can give this variable a buffer-local value that is a function to
regenerate the contents.