GNU Emacs Lisp Reference Manual

23.2: Auto-Saving

Emacs periodically saves all files that you are visiting; this is called 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. See Auto-Save, for information on auto-save for users. Here we describe the functions used to implement auto-saving and the variables that control them.

Variable: buffer-auto-save-file-name

This buffer-local variable is the name of the file used for auto-saving the current buffer. It is nil if the buffer should not be auto-saved.

buffer-auto-save-file-name
=> "/xcssun/users/rms/lewis/#files.texi#"

Command: auto-save-mode arg

When used interactively without an argument, this command is a toggle switch: it turns on auto-saving of the current buffer if it is off, and vice-versa. With an argument arg, the command turns auto-saving on if the value of arg is t, a nonempty list, or a positive integer. Otherwise, it turns auto-saving off.

Function: auto-save-file-name-p filename

This function returns a non-nil value if filename is a string that could be the name of an auto-save file. It works based on knowledge of the naming convention for auto-save files: a name that begins and ends with hash marks (`#') is a possible auto-save file name. The argument filename should not contain a directory part.

(make-auto-save-file-name)
     => "/xcssun/users/rms/lewis/#files.texi#"
(auto-save-file-name-p "#files.texi#")
     => 0
(auto-save-file-name-p "files.texi")
     => nil

The standard definition of this function is as follows:

(defun auto-save-file-name-p (filename)
  "Return non-nil if FILENAME can be yielded by..."
  (string-match "^#.*#$" filename))

This function exists so that you can customize it if you wish to change the naming convention for auto-save files. If you redefine it, be sure to redefine the function make-auto-save-file-name correspondingly.

Function: 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 (`#') appended and prepended to it. This function does not look at the variable auto-save-visited-file-name (described below); you should check that before calling this function.

(make-auto-save-file-name)
     => "/xcssun/users/rms/lewis/#backup.texi#"

The standard definition of this function is as follows:

(defun make-auto-save-file-name ()
  "Return file name to use for auto-saves \
of current buffer.
..."
  (if buffer-file-name
      (concat
       (file-name-directory buffer-file-name)
       "#"
       (file-name-nondirectory buffer-file-name)
       "#")
    (expand-file-name
     (concat "#%" (buffer-name) "#"))))

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 auto-save-file-name-p in a corresponding way.

Variable: auto-save-visited-file-name

If this variable is non-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 nil, so auto-save files have distinct names that are created by make-auto-save-file-name.

When you change the value of this variable, the value does not take effect until the next time auto-save mode is reenabled in any given buffer. If auto-save mode is already enabled, auto-saves continue to go in the same file name until auto-save-mode is called again.

Function: recent-auto-save-p

This function returns t if the current buffer has been auto-saved since the last time it was read in or saved.

Function: set-buffer-auto-saved

This function marks the current buffer as auto-saved. The buffer will not be auto-saved again until the buffer text is changed again. The function returns nil.

User Option: auto-save-interval

The value of this variable is the number of characters that Emacs reads from the keyboard between auto-saves. Each time this many more characters are read, auto-saving is done for all buffers in which it is enabled.

User Option: 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 auto-saves any buffers that need it. (Actually, the specified timeout is multiplied by a factor depending on the size of the current buffer.)

Variable: auto-save-hook

This normal hook is run whenever an auto-save is about to happen.

User Option: auto-save-default

If this variable is non-nil, buffers that are visiting files have auto-saving enabled by default. Otherwise, they do not.

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 `Auto-saving...' is displayed in the echo area while auto-saving is going on. However, if no-message is non-nil, the message is inhibited.

If current-only is non-nil, only the current buffer is auto-saved.

Function: delete-auto-save-file-if-necessary

This function deletes the current buffer's auto-save file if delete-auto-save-files is non-nil. It is called every time a buffer is saved.

Variable: delete-auto-save-files

This variable is used by the function delete-auto-save-file-if-necessary. If it is non-nil, Emacs deletes auto-save files when a true save is done (in the visited file). This saves disk space and unclutters your directory.

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

Variable: buffer-saved-size

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-saving. Turning auto-save mode off or on also alters this variable.

Variable: auto-save-list-file-name

This variable (if non-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 recover-session command uses these files.

The default name for this file is in your home directory and starts with `.saves-'. It also contains the Emacs process ID and the host name.