path: root/devdocs/elisp/auto_002dsaving.html

 <h3 class="section">Auto-Saving</h3> <p>Emacs periodically saves all files that you are visiting; this is called <em>auto-saving</em>. 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 <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Auto-Save.html#Auto-Save">Auto-Saving: Protection Against Disasters</a> in <cite>The GNU Emacs Manual</cite>, for information on auto-save for users. Here we describe the functions used to implement auto-saving and the variables that control them. </p> <dl> <dt id="buffer-auto-save-file-name">Variable: <strong>buffer-auto-save-file-name</strong>
</dt> <dd>
<p>This buffer-local variable is the name of the file used for auto-saving the current buffer. It is <code>nil</code> if the buffer should not be auto-saved. </p> <div class="example"> <pre class="example">buffer-auto-save-file-name
     ⇒ "/xcssun/users/rms/lewis/#backups.texi#"
</pre>
</div> </dd>
</dl> <dl> <dt id="auto-save-mode">Command: <strong>auto-save-mode</strong> <em>arg</em>
</dt> <dd>
<p>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 <a href="minor-mode-conventions">Minor Mode Conventions</a>). </p> <p>Unlike most minor modes, there is no <code>auto-save-mode</code> variable. Auto Save mode is enabled if <code>buffer-auto-save-file-name</code> is non-<code>nil</code> and <code>buffer-saved-size</code> (see below) is non-zero. </p>
</dd>
</dl> <dl> <dt id="auto-save-file-name-transforms">Variable: <strong>auto-save-file-name-transforms</strong>
</dt> <dd>
<p>This variable lists transforms to apply to buffer’s file name before making the auto-save file name. </p> <p>Each transform is a list of the form <code>(<var>regexp</var> <var>replacement</var> [<var>uniquify</var>])</code>. <var>regexp</var> is a regular expression to match against the file name; if it matches, <code>replace-match</code> is used to replace the matching part with <var>replacement</var>. If the optional element <var>uniquify</var> is non-nil, the auto-save file name is constructed by concatenating the directory part of the transformed file name with the buffer’s file name in which all directory separators were changed to ‘<samp>!</samp>’ to prevent clashes. (This will not work correctly if your filesystem truncates the resulting name.) </p> <p>If <var>uniquify</var> is one of the members of <code>secure-hash-algorithms</code>, Emacs constructs the nondirectory part of the auto-save file name by applying that <code>secure-hash</code> to the buffer file name. This avoids any risk of excessively long file names. </p> <p>All the transforms in the list are tried, in the order they are listed. When one transform applies, its result is final; no further transforms are tried. </p> <p>The default value is set up to put the auto-save files of remote files into the temporary directory (see <a href="unique-file-names">Unique File Names</a>). </p> <p>On MS-DOS filesystems without long names this variable is always ignored. </p>
</dd>
</dl> <dl> <dt id="auto-save-file-name-p">Function: <strong>auto-save-file-name-p</strong> <em>filename</em>
</dt> <dd>
<p>This function returns a non-<code>nil</code> value if <var>filename</var> 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 (‘<samp>#</samp>’) is a possible auto-save file name. The argument <var>filename</var> should not contain a directory part. </p> <div class="example"> <pre class="example">(make-auto-save-file-name)
     ⇒ "/xcssun/users/rms/lewis/#backups.texi#"
</pre>
<pre class="example">(auto-save-file-name-p "#backups.texi#")
     ⇒ 0
</pre>
<pre class="example">(auto-save-file-name-p "backups.texi")
     ⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="make-auto-save-file-name">Function: <strong>make-auto-save-file-name</strong>
</dt> <dd>
<p>This function returns the file name to use for auto-saving the current buffer. This is just the file name with hash marks (‘<samp>#</samp>’) prepended and appended to it. This function does not look at the variable <code>auto-save-visited-file-name</code> (described below); callers of this function should check that variable first. </p> <div class="example"> <pre class="example">(make-auto-save-file-name)
     ⇒ "/xcssun/users/rms/lewis/#backups.texi#"
</pre>
</div> </dd>
</dl> <dl> <dt id="auto-save-visited-file-name">User Option: <strong>auto-save-visited-file-name</strong>
</dt> <dd>
<p>If this variable is non-<code>nil</code>, 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</code>, so auto-save files have distinct names that are created by <code>make-auto-save-file-name</code>. </p> <p>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</code> is called again. </p> <p>Note that setting this variable to a non-<code>nil</code> value does not change the fact that auto-saving is different from saving the buffer; e.g., the hooks described in <a href="saving-buffers">Saving Buffers</a> are <em>not</em> run when a buffer is auto-saved. </p>
</dd>
</dl> <dl> <dt id="recent-auto-save-p">Function: <strong>recent-auto-save-p</strong>
</dt> <dd><p>This function returns <code>t</code> if the current buffer has been auto-saved since the last time it was read in or saved. </p></dd>
</dl> <dl> <dt id="set-buffer-auto-saved">Function: <strong>set-buffer-auto-saved</strong>
</dt> <dd><p>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 <code>nil</code>. </p></dd>
</dl> <dl> <dt id="auto-save-interval">User Option: <strong>auto-save-interval</strong>
</dt> <dd><p>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. </p></dd>
</dl> <dl> <dt id="auto-save-timeout">User Option: <strong>auto-save-timeout</strong>
</dt> <dd>
<p>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.) </p> <p>If the value is zero or <code>nil</code>, 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</code>. </p>
</dd>
</dl> <dl> <dt id="auto-save-hook">Variable: <strong>auto-save-hook</strong>
</dt> <dd><p>This normal hook is run whenever an auto-save is about to happen. </p></dd>
</dl> <dl> <dt id="auto-save-default">User Option: <strong>auto-save-default</strong>
</dt> <dd><p>If this variable is non-<code>nil</code>, buffers that are visiting files have auto-saving enabled by default. Otherwise, they do not. </p></dd>
</dl> <dl> <dt id="do-auto-save">Command: <strong>do-auto-save</strong> <em>&amp;optional no-message current-only</em>
</dt> <dd>
<p>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. </p> <p>If any buffers are auto-saved, <code>do-auto-save</code> normally displays a message saying ‘<samp>Auto-saving...</samp>’ in the echo area while auto-saving is going on. However, if <var>no-message</var> is non-<code>nil</code>, the message is inhibited. </p> <p>If <var>current-only</var> is non-<code>nil</code>, only the current buffer is auto-saved. </p>
</dd>
</dl> <dl> <dt id="delete-auto-save-file-if-necessary">Function: <strong>delete-auto-save-file-if-necessary</strong> <em>&amp;optional force</em>
</dt> <dd>
<p>This function deletes the current buffer’s auto-save file if <code>delete-auto-save-files</code> is non-<code>nil</code>. It is called every time a buffer is saved. </p> <p>Unless <var>force</var> is non-<code>nil</code>, this function only deletes the file if it was written by the current Emacs session since the last true save. </p>
</dd>
</dl> <dl> <dt id="delete-auto-save-files">User Option: <strong>delete-auto-save-files</strong>
</dt> <dd><p>This variable is used by the function <code>delete-auto-save-file-if-necessary</code>. If it is non-<code>nil</code>, Emacs deletes auto-save files when a true save is done (in the visited file). This saves disk space and unclutters your directory. </p></dd>
</dl> <dl> <dt id="rename-auto-save-file">Function: <strong>rename-auto-save-file</strong>
</dt> <dd><p>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. </p></dd>
</dl> <dl> <dt id="buffer-saved-size">Variable: <strong>buffer-saved-size</strong>
</dt> <dd>
<p>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. </p> <p>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. </p> <p>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. </p>
</dd>
</dl> <dl> <dt id="auto-save-list-file-name">Variable: <strong>auto-save-list-file-name</strong>
</dt> <dd>
<p>This variable (if non-<code>nil</code>) 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. </p> <p>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 <code>recover-session</code> command uses this file to find them. </p> <p>The default name for this file specifies your home directory and starts with ‘<samp>.saves-</samp>’. It also contains the Emacs process <acronym>ID</acronym> and the host name. </p>
</dd>
</dl> <dl> <dt id="auto-save-list-file-prefix">User Option: <strong>auto-save-list-file-prefix</strong>
</dt> <dd><p>After Emacs reads your init file, it initializes <code>auto-save-list-file-name</code> (if you have not already set it non-<code>nil</code>) based on this prefix, adding the host name and process ID. If you set this to <code>nil</code> in your init file, then Emacs does not initialize <code>auto-save-list-file-name</code>. </p></dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Auto_002dSaving.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Auto_002dSaving.html</a>
  </p>
</div>