comparison lispref/backups.texi @ 88155:d7ddb3e565de

sync with trunk

88154:8ce476d3ba36

@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

@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

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

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

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

  Emacs periodically saves all files that you are visiting; this is
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
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.

@defvar buffer-auto-save-file-name

(make-auto-save-file-name)
     @result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@end example

The standard definition of this function is as follows:

@example
@group
(defun make-auto-save-file-name ()
  "Return file name to use for auto-saves \

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,
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 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
This normal hook is run whenever an auto-save is about to happen.
@end defvar

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

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

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
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
host name.
@end defvar

@defvar auto-save-list-file-prefix
@tindex auto-save-list-file-prefix

  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.

@defvar after-revert-hook
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

88155:d7ddb3e565de

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2002, 2003, 2004,
@c   2005 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

@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

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

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

@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

file or multiple numbered backups.

@table @asis
@item @code{nil}
Make numbered backups if the visited file already has numbered backups;
otherwise, do not.  This is the default.

@item @code{never}
Do not make numbered backups.

@item @var{anything else}

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

  Emacs periodically saves all files that you are visiting; this is
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
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.

@defvar buffer-auto-save-file-name

(make-auto-save-file-name)
     @result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@end example

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 \

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,
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
This normal hook is run whenever an auto-save is about to happen.
@end defvar

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

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

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
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 @acronym{ID} and the
host name.
@end defvar

@defvar auto-save-list-file-prefix
@tindex auto-save-list-file-prefix

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

@defvar after-revert-hook
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