elisp: Reverting
25.3 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 ‘revert-buffer’ command. Reverting a Buffer
(emacs)Reverting.
-- Command: revert-buffer &optional ignore-auto noconfirm
preserve-modes
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.
By default, if the latest auto-save file is more recent than the
visited file, and the argument IGNORE-AUTO is ‘nil’,
‘revert-buffer’ asks the user whether to use that auto-save
instead. When you invoke this command interactively, IGNORE-AUTO
is ‘t’ if there is no numeric prefix argument; thus, the
interactive default is not to check the auto-save file.
Normally, ‘revert-buffer’ asks for confirmation before it changes
the buffer; but if the argument NOCONFIRM is non-‘nil’,
‘revert-buffer’ does not ask for confirmation.
Normally, this command reinitializes the buffer’s major and minor
modes using ‘normal-mode’. But if PRESERVE-MODES is non-‘nil’, the
modes remain unchanged.
Reverting tries to preserve marker positions in the buffer by using
the replacement feature of ‘insert-file-contents’. If the buffer
contents and the file contents are identical before the revert
operation, reverting preserves all the markers. If they are not
identical, reverting does change the buffer; in that case, it
preserves the markers in the unchanged text (if any) at the
beginning and end of the buffer. Preserving any additional markers
would be problematical.
-- Variable: revert-buffer-in-progress-p
‘revert-buffer’ binds this variable to a non-‘nil’ value while it
is working.
You can customize how ‘revert-buffer’ does its work by setting the
variables described in the rest of this section.
-- User Option: revert-without-query
This variable holds a list of files that should be reverted without
query. The value is a list of regular expressions. If the visited
file name matches one of these regular expressions, and the file
has changed on disk but the buffer is not modified, then
‘revert-buffer’ reverts the file without asking the user for
confirmation.
Some major modes customize ‘revert-buffer’ by making buffer-local
bindings for these variables:
-- Variable: revert-buffer-function
The value of this variable is the function to use to revert this
buffer. It should be a function with two optional arguments to do
the work of reverting. The two optional arguments, IGNORE-AUTO and
NOCONFIRM, are the arguments that ‘revert-buffer’ received.
Modes such as Dired mode, in which the text being edited does not
consist of a file’s contents but can be regenerated in some other
fashion, can give this variable a buffer-local value that is a
special function to regenerate the contents.
-- Variable: revert-buffer-insert-file-contents-function
The value of this variable specifies the function to use to insert
the updated contents when reverting this buffer. The function
receives two arguments: first the file name to use; second, ‘t’ if
the user has asked to read the auto-save file.
The reason for a mode to change this variable instead of
‘revert-buffer-function’ is to avoid duplicating or replacing the
rest of what ‘revert-buffer’ does: asking for confirmation,
clearing the undo list, deciding the proper major mode, and running
the hooks listed below.
-- Variable: before-revert-hook
This normal hook is run by the default ‘revert-buffer-function’
before inserting the modified contents. A custom
‘revert-buffer-function’ may or may not run this hook.
-- Variable: after-revert-hook
This normal hook is run by the default ‘revert-buffer-function’
after inserting the modified contents. A custom
‘revert-buffer-function’ may or may not run this hook.
-- Variable: buffer-stale-function
The value of this variable specifies a function to call to check
whether a buffer needs reverting. The default value only handles
buffers that are visiting files, by checking their modification
time. Buffers that are not visiting files require a custom
function ((emacs)Supporting additional buffers).