⟦a52d21dc5⟧

TextFile

@setfilename ../info/backups
@node Backups and Auto Saving, Buffers, Files, Top
@chapter Backups and Auto Saving

  Backup files and auto-save files are two methods by which Emacs tries
to protect the user from the consequences of crashes or of the user's
own errors.  Auto-saving preserves the text from earlier in the current
editing session.  Backup files preserve file contents prior to the
current session.

@menu
* Backup Files::        
* Auto Saving:: 
* Reverting::   
@end menu

@node Backup Files, Auto Saving, Backups and Auto Saving, Backups and Auto Saving
@section Backup Files
@cindex backup file

  A @dfn{backup file} is a copy of the old contents of a file you are
editing.  Emacs makes a backup file the first time you save a buffer
into the visited file.  This means that the backup file contains the
contents of the file as it was before editing started in the current
editing session.  The contents of the backup file are not normally
changed during the current editing session.

  By default, Emacs makes a single backup file for each file you edit.
You can alternatively request numbered backups; then each new backup
file gets a new name.  It is up to you to delete old numbered backups
when you don't want them any more.

  Backups are usually made by renaming the visited file to a new name.
Optionally, you can specify that backup files should be made by copying
the visited file.  This choice makes a difference for files with multiple
hard links; it also can affect the owner of the file.

@menu
* Making Backups::
* Rename or Copy::
* Backup Names::
@end menu

@node Making Backups, Rename or Copy, Backup Files, Backup Files
@subsection Making Backup Files

@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
the backup file has been written.  The file is backed up just before the
file is saved for the first time.
@end defvar

@defvar make-backup-files
  This global variable determines whether or not backup files will be
created.  If it is non-@code{nil}, then Emacs will create a backup of
each file when it is saved for the first time.  

  The following example shows how to change the
@code{make-backup-files} variable only in your @file{RMAIL} buffer and
not elsewhere.  Setting it @code{nil} stops Emacs from making backups
of your @file{RMAIL} file, which may save disk space.  (You would put
this code in your @file{.emacs} file.)

@example
(setq rmail-mode-hook 
      (function (lambda ()
                  (make-local-variable 'make-backup-files)
                  (setq make-backup-files nil)))
@end example
@end defvar

@node Rename or Copy, Backup Names, Making Backups, Backup Files
@subsection Backup by Renaming or by Copying?

@cindex backup files, how to make them

There are two ways that Emacs can make a backup: 

@itemize @bullet
@item
Emacs can rename the original file into a backup file, and then write
the buffer being saved into a new file.  In this case, any other names
(e.g., hard links) that the old file had will now refer to the backup
file.  The new file will be owned by the user and its group will be the
user's default group.

@item
Emacs can copy the original file into a backup file, and then overwrite
the original file with new contents.  In this case, any other names
(e.g., hard links) that the original file had will still refer to the
most current version of the file.  The file's owner and group will be
unchanged.
@end itemize

  The first method, of renaming, is the default.

  The variable @code{backup-by-copying}, if non-@code{nil}, says to use
the second method, which is to copy the file and then write the buffer
on top of the original.

  The variable @code{file-precious-flag}, if non-@code{nil}, also has
this effect, as a sideline of its other significance.  @xref{Saving
Buffers}.

  The variables @code{backup-by-copying-when-linked} and
@code{backup-by-copying-when-mismatch}, if 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
  This global variable determines whether backup files will be made by
copying.  If it is non-@code{nil}, then Emacs will always copy the
current contents of the file into the backup file before writing the
buffer to be saved to the file.  (In many circumstances, this has the
same effect as @code{file-precious-flag}.)
@end defvar

@defvar backup-by-copying-when-linked
  This global variable determines whether backups for files with
multiple names (hard links) will be made by copying.  If it is
non-@code{nil}, then Emacs will use copying to create backups for those
files.

  This variable is relevant 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
  This global variable determines whether Emacs will make backups by
copying when renaming would cause either the owner or the group of
the file to change.  If it is non-@code{nil} then Emacs will create backups
for those file by copying.

  Renaming may still be used (subject to control of other variables)
when it would not result in changing the owner or group of the
file; that is, for files which are owned by the user and whose group
matches the default for a new file created there by the user.

  This variable is relevant only if @code{backup-by-copying} is @code{nil},
since copying is always used when that variable is non-@code{nil}.
@end defvar

@node Backup Names, , Rename or Copy, Backup Files
@subsection Naming Backup Files

@defun backup-file-name-p filename
  This function returns a non-@code{nil} value if @var{filename} is a
possible name for a backup file.  A file with the name @var{filename}
need not exist; the function just checks the name.

@example
(backup-file-name-p "foo")
     @result{} nil
(backup-file-name-p "foo~")
     @result{} 3
@end example

  In the standard release, the body of this function consists of the
following line:

@example
(string-match "~$" file)
@end example

@noindent
In other words, the function returns a non-@code{nil} value if the
filename ends with a @samp{~}

  This simple expression is given its own name as a function so that
you can redefine it for customization.
@end defun

@defun make-backup-file-name filename
  This function creates a non-numeric backup file name to be used when
@var{filename} is backed up.  On Unix, the value is just @var{filename}
with a tilde appended.

  In the standard release, the body of this function consists of the
following line:

@example
(concat file "~")
@end example

  You can change the backup file names for all backup files by
redefining this function.  In the following example,
@code{make-backup-file-name} is redefined to prepend a @samp{.} as well
as to append a tilde.

@example
(defun make-backup-file-name (filename)
  (concat "." filename "~"))

(make-backup-file-name "backups.texinfo")
     @result{} ".backups.texinfo~"
@end example
@end defun

@defun find-backup-file-name filename
  This function computes the file name for a new backup file for
@var{filename}.  If numerous backup files for @var{filename} exist
(which implies that the backups must be numeric backups), then this
function also makes a list of old backup files that are ripe for
deletion.

  The global variables @code{kept-old-versions} and
@code{kept-new-versions} determine which old backup versions Emacs
will keep (by not including them in the list of backup files ripe 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 old versions.

  In the example, @file{~rms/lewis/foo.~5~} is the name for the
new backup file and @file{~rms/lewis/foo.~3~} is the ``excess''
version that you should consider deleting now.

@example
(find-backup-file-name "~rms/lewis/foo")
     @result{} ("~rms/lewis/foo.~5~" "~rms/lewis/foo.~3~")
@end example
@end defun

@defopt kept-old-versions
  The value of this variable is the number of oldest versions to keep
when a new numbered backup is made.  If there are backups numbered 1,
2, 3, 5, and 6, and the value of @code{kept-old-versions} is 2, then
the ``oldest'' backups 1 and 2 will be kept, and 3 will be flagged for
deletion, unless (in this example) the value of
@code{kept-new-versions} is greater than 2.
@end defopt

@defopt kept-new-versions
  The value of this variable is the number of a file's most recent
versions to keep when a new numbered backup is made.  It includes the
new backup.  It must be greater than 0.  Thus, if the value of
@code{kept-new-versions} is 2, then the two most recent backups of a
file will be kept.
@end defopt

@node Auto Saving, Reverting, Backup Files, Backups and Auto Saving
@section Auto Saving
@cindex auto saving

  Emacs saves all files that you are visiting from time to time without
being asked.  This is called ``auto saving''.  (Emacs counts your
keystrokes; by default, your work is saved after 300 keystrokes.)  Auto
saving prevents you from losing more than a limited amount of work if
the system crashes.  @xref{Auto Save, , Auto Saving: Protection Against
Disasters, emacs, The GNU Emacs Manual}.

@defvar buffer-auto-save-file-name
  This buffer-local variable is the name of the file used for
auto saving the current buffer.  It is @code{nil} if the buffer
should not be auto saved.

@example
buffer-auto-save-file-name
=> "/xcssun/users/rms/lewis/#file.texinfo#"
@end example
@end defvar

@deffn Command auto-save-mode arg
  When used interactively without being passed an argument this
command is a toggle switch.  It turns on auto saving of the contents
of the current buffer if it is off and vice-versa.  When passed
@var{arg}, the command turns auto saving on if the value of @var{arg}
is positive, 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 possibly be returned by
@code{make-auto-save-file-name}.

  According to the usual naming convention, any name that begins and
ends with hash marks (@kbd{#}) is a possible auto-save file name, and
any other name isn't.

@example
(make-auto-save-file-name)
     @result{} "/xcssun/users/rms/lewis/#file.texinfo#"
(auto-save-file-name-p "#file.texinfo#")
     @result{} 0
(auto-save-file-name-p "file.texinfo")
     @result{} nil
@end example

  In the standard release, the body of this function consists of the
following line:

@example
(string-match "^#.*#$" filename)
@end example

  This function exists so that you can customize it if you wish to
change the naming convention for auto-save files.
@end defun

@defvar auto-save-visited-file-name
  If this global variable is non-@code{nil}, then Emacs will auto save
buffers in the files they are visiting.  That is, the same name is
used as the file currently has.  Normally, auto-save files have other
names that created by @code{make-auto-save-file-name}.
@end defvar

@defun make-auto-save-file-name
  This function returns the file name to use for auto saving the current
buffer.  This is just the file name with hash marks (@kbd{#}) appended and
prepended to it.

  This function does not look at the variable
@code{auto-save-visited-file-name}; that should be checked before this
function is called.

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

  The body of @code{make-auto-save-file-name} consists of the following
lines:

@example
(if buffer-file-name
    (concat (file-name-directory buffer-file-name)
            "#"
            (file-name-nondirectory buffer-file-name)
            "#")
  (expand-file-name (concat "#%" (buffer-name) "#"))))
@end example

  This exists as a separate function so that you can redefine it
to customize the naming convention for auto-save files.
@end defun

@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

@defun set-buffer-auto-saved
  This function marks the current buffer as auto-saved.  The buffer
will not be auto-saved again until the buffer changes.  It returns
@code{nil}.
@end defun

@defopt auto-save-interval
  The value of this variable is the number of characters that Emacs may
read from the keyboard between auto-saves.  When this number is reached,
then Emacs will auto-save each file again.
@end defopt

@deffn Command do-auto-save &optional no-message
  This function auto-saves all buffers that need to be auto-saved.  This is
all buffers that have auto-saving enabled and that have been changed since
the last time they were auto-saved.

  If @var{no-message} is non-@code{nil}, then Emacs will not print out its
standard message: @samp{Auto-saving...}.
@end deffn

@defun delete-auto-save-file-if-necessary
  This function deletes the auto-save files for the current buffer if
variable @code{delete-auto-save-files} is non-@code{nil}.  This function is
called every time you save the buffer.
@end defun

@defvar delete-auto-save-files
  This global variable is used by the function
@code{delete-auto-save-file-if-necessary}.  If it is non-@code{nil}, then
auto-save files for the buffers will be deleted when you save the
buffer.

  In other words, if the value of @code{delete-auto-save-files} is
non-@code{nil}, Emacs will delete auto-save files when a true save is
done (in the visited file).  This saves on disk space and unclutters
your directory.
@end defvar

@defun rename-auto-save-file
  This function adjusts the current buffer's auto-save file name for
current conditions.  Assuming that the visited file has been renamed,
this function renames the auto-save file, too.  If the visited file name
has not changed, this function does nothing.
@end defun

@node Reverting,  , Auto Saving, Backups and Auto Saving
@section Reverting

  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 no-autosave-offer-p 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.  If the latest auto-save file is more recent than the visited
file, Emacs asks the user whether to use that instead.

  When the value of the @code{no-autosave-offer-p} argument is
non-@code{nil}, Emacs does not offer to use the auto-save file.  This
argument is the prefix argument when the function is called
interactively.

  When the value of the @code{noconfirm} argument is non-@code{nil},
Emacs does not ask for confirmation for the reversion action.  This
means that the buffer is deleted and replaced by the text from the file
on the disk, without asking the user if he or she really wants that.

  If the value of the @code{revert-buffer-function} variable is
non-@code{nil}, it is called as a function to do the work.
@end deffn

@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, set this variable
locally.
@end defvar

@deffn Command recover-file filename
  This function visits @var{filename}, but gets the contents from its
last auto-save file.

  The @code{after-find-file} function displays a message suggesting the
use of @code{recover-file} if the auto-save file is newer than the file
just visited.  This situation may be the result of a crash.  By using
@code{recover-file}, you may recover a great deal of work.

@cindex auto-save error
  It is an error 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, that is ok.  This last situation
may occur if you visited a nonexistent file and never actually saved it.

  This function is for interactive use.
@end deffn
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦a52d21dc5⟧ TextFile

Derivation

TextFile
