Function: revert-buffer

revert-buffer is an interactive and byte-compiled function defined in files.el.gz.

Signature

(revert-buffer &optional IGNORE-AUTO NOCONFIRM PRESERVE-MODES)

Documentation

Replace current buffer text with the text of the visited file on disk.

This undoes all changes since the file was visited or saved. With a prefix argument, offer to revert from latest auto-save file, if that is more recent than the visited file.

This command also implements an interface for special buffers that contain text that doesn't come from a file, but reflects some other data instead (e.g. Dired buffers, buffer-list buffers). This is done via the variable revert-buffer-function. In these cases, it should reconstruct the buffer contents from the appropriate data.

When called from Lisp, the first argument is IGNORE-AUTO; offer to revert from the auto-save file only when this is nil. Note that the sense of this argument is the reverse of the prefix argument, for the sake of backward compatibility. IGNORE-AUTO is optional, defaulting to nil.

Optional second argument NOCONFIRM means don't ask for confirmation at all. (The variable revert-without-query offers another way to revert buffers without querying for confirmation.)

Optional third argument PRESERVE-MODES non-nil means don't alter the files modes. Normally we reinitialize them using normal-mode.

This function binds revert-buffer-in-progress-p non-nil while it operates.

This function calls the function that revert-buffer-function specifies to do the work, with arguments IGNORE-AUTO and NOCONFIRM. The default function runs the hooks before-revert-hook and after-revert-hook. Return value is whatever revert-buffer-function returns. For historical reasons, that return value is non-nil when revert-buffer-function succeeds in its job and returns non-nil.

Reverting a buffer will try to preserve markers in the buffer, but it cannot always preserve all of them. For better results, use revert-buffer-with-fine-grain, which tries harder to preserve markers and overlays, at the price of being slower.

View in manual

Probably introduced at or before Emacs version 15.

Key Bindings

Aliases

package-menu-refresh (obsolete since 27.1) doc-view-revert-buffer (obsolete since 27.1)

Source Code

;; Defined in /usr/src/emacs/lisp/files.el.gz
(defun revert-buffer (&optional ignore-auto noconfirm preserve-modes)
  "Replace current buffer text with the text of the visited file on disk.
This undoes all changes since the file was visited or saved.
With a prefix argument, offer to revert from latest auto-save file, if
that is more recent than the visited file.

This command also implements an interface for special buffers
that contain text that doesn't come from a file, but reflects
some other data instead (e.g. Dired buffers, `buffer-list'
buffers).  This is done via the variable `revert-buffer-function'.
In these cases, it should reconstruct the buffer contents from the
appropriate data.

When called from Lisp, the first argument is IGNORE-AUTO; offer to
revert from the auto-save file only when this is nil.  Note that the
sense of this argument is the reverse of the prefix argument, for the
sake of backward compatibility.  IGNORE-AUTO is optional, defaulting
to nil.

Optional second argument NOCONFIRM means don't ask for confirmation
at all.  (The variable `revert-without-query' offers another way to
revert buffers without querying for confirmation.)

Optional third argument PRESERVE-MODES non-nil means don't alter
the files modes.  Normally we reinitialize them using `normal-mode'.

This function binds `revert-buffer-in-progress-p' non-nil while it operates.

This function calls the function that `revert-buffer-function' specifies
to do the work, with arguments IGNORE-AUTO and NOCONFIRM.
The default function runs the hooks `before-revert-hook' and
`after-revert-hook'.
Return value is whatever `revert-buffer-function' returns.  For historical
reasons, that return value is non-nil when `revert-buffer-function'
succeeds in its job and returns non-nil.

Reverting a buffer will try to preserve markers in the buffer,
but it cannot always preserve all of them.  For better results,
use `revert-buffer-with-fine-grain', which tries harder to
preserve markers and overlays, at the price of being slower."
  ;; I admit it's odd to reverse the sense of the prefix argument, but
  ;; there is a lot of code out there that assumes that the first
  ;; argument should be t to avoid consulting the auto-save file, and
  ;; there's no straightforward way to encourage authors to notice a
  ;; reversal of the argument sense.  So I'm just changing the user
  ;; interface, but leaving the programmatic interface the same.
  (interactive (list (not current-prefix-arg)))
  (let ((revert-buffer-in-progress-p t)
        (revert-buffer-preserve-modes preserve-modes)
        (state (and (boundp 'read-only-mode--state)
                    (list read-only-mode--state))))
    ;; Return whatever 'revert-buffer-function' returns.
    (prog1 (funcall (or revert-buffer-function #'revert-buffer--default)
                    ignore-auto noconfirm)
      (when state
        (setq buffer-read-only (car state))
        (setq-local read-only-mode--state (car state))))))