Next: Reverting, Previous: Backup Files, Up: Backups and Auto-Saving [Contents][Index]

### 25.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-Saving: Protection Against Disasters in 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.

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/#backups.texi#"

Command: auto-save-mode arg

  This is the mode command for Auto Save mode, a buffer-local minor mode. When Auto Save mode is enabled, auto-saving is enabled in the buffer. The calling convention is the same as for other minor mode commands (see Minor Mode Conventions).

  Unlike most minor modes, there is no `auto-save-mode` variable. Auto Save mode is enabled if `buffer-auto-save-file-name` is non-`nil` and `buffer-saved-size` (see below) is non-zero.

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 assumes the usual 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/#backups.texi#"

      (auto-save-file-name-p "#backups.texi#")
           ⇒ 0

      (auto-save-file-name-p "backups.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 (‘`#`’) prepended and appended to it. This function does not look at the variable `auto-save-visited-file-name` (described below); callers of this function should check that variable first.

      (make-auto-save-file-name)
           ⇒ "/xcssun/users/rms/lewis/#backups.texi#"

  Here is a simplified version of the standard definition of this function:

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

User Option: 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 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 `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 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.

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 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 `auto-save-interval`.

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.

  If any buffers are auto-saved, `do-auto-save` normally displays a message saying ‘`Auto-saving...`’ 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 &optional force

  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.

  Unless force is non-`nil`, this function only deletes the file if it was written by the current Emacs session since the last true save.

User Option: 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 it was made in the current Emacs session. 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, when it was last 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 decrease in size. Explicitly saving the buffer stores a positive value in this variable, thus reenabling auto-saving. Turning auto-save mode off or on also updates this variable, so that the substantial decrease in size is forgotten.

  If it is âˆ’2, that means this buffer should disregard changes in buffer size; in particular, it should not shut off auto-saving temporarily due to changes in buffer size.

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.

  When 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 this file to find them.

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

User Option: auto-save-list-file-prefix

  After Emacs reads your init file, it initializes `auto-save-list-file-name` (if you have not already set it non-`nil`) based on this prefix, adding the host name and process ID. If you set this to `nil` in your init file, then Emacs does not initialize `auto-save-list-file-name`.

Next: Reverting, Previous: Backup Files, Up: Backups and Auto-Saving [Contents][Index]