By default Magit automatically reverts buffers that are visiting files that are being tracked in a Git repository, after they have changed on disk. When using Magit one often changes files on disk by running Git, i.e. "outside Emacs", making this a rather important feature.
For example, if you discard a change in the status buffer, then that is done by running
git apply --reverse ..., and Emacs considers the file to have "changed on disk". If Magit did not automatically revert the buffer, then you would have to type
M-x revert-buffer RET RET in the visiting buffer before you could continue making changes.
user option magit-auto-revert-mode
When this mode is enabled, then buffers that visit tracked files are automatically reverted after the visited files change on disk.
user option global-auto-revert-mode
When this mode is enabled, then any file-visiting buffer is automatically reverted after the visited file changes on disk.
If you like buffers that visit tracked files to be automatically reverted, then you might also like any buffer to be reverted, not just those visiting tracked files. If that is the case, then enable this mode instead of
user option magit-auto-revert-immediately
This option controls whether Magit reverts buffers immediately.
If this is non-nil and either
magit-auto-revert-mode is enabled, then Magit immediately reverts buffers by explicitly calling
auto-revert-buffers after running Git for side-effects.
auto-revert-use-notify is non-nil (and file notifications are actually supported), then
magit-auto-revert-immediately does not have to be non-nil, because the reverts happen immediately anyway.
auto-revert-use-notify are both
nil, then reverts happen after
auto-revert-interval seconds of user inactivity. That is not desirable.
user option auto-revert-use-notify
This option controls whether file notification functions should be used. Note that this variable unfortunately defaults to
t even on systems on which file notifications cannot be used.
user option magit-auto-revert-tracked-only
This option controls whether
magit-auto-revert-mode only reverts tracked files or all files that are located inside Git repositories, including untracked files and files located inside Git’s control directory.
user option auto-revert-mode
The global mode
magit-auto-revert-mode works by turning on this local mode in the appropriate buffers (but
global-auto-revert-mode is implemented differently). You can also turn it on or off manually, which might be necessary if Magit does not notice that a previously untracked file now is being tracked or vice-versa.
user option auto-revert-stop-on-user-input
This option controls whether the arrival of user input suspends the automatic reverts for
user option auto-revert-interval
This option controls how many seconds Emacs waits for before resuming suspended reverts.
user option auto-revert-buffer-list-filter
This option specifies an additional filter used by
auto-revert-buffers to determine whether a buffer should be reverted or not.
This option is provided by Magit, which also advises
auto-revert-buffers to respect it. Magit users who do not turn on the local mode
auto-revert-mode themselves, are best served by setting the value to
However the default is nil, so as not to disturb users who do use the local mode directly. If you experience delays when running Magit commands, then you should consider using one of the predicates provided by Magit - especially if you also use Tramp.
Users who do turn on
auto-revert-mode in buffers in which Magit doesn’t do that for them, should likely not use any filter. Users who turn on
global-auto-revert-mode, do not have to worry about this option, because it is disregarded if the global mode is enabled.
user option auto-revert-verbose
This option controls whether Emacs reports when a buffer has been reverted.
The options with the
auto-revert- prefix are located in the Custom group named
auto-revert. The other, Magit-specific, options are located in the
|• Risk of Reverting Automatically:|
Risk of Reverting Automatically
For the vast majority of users, automatically reverting file-visiting buffers after they have changed on disk is harmless.
If a buffer is modified (i.e. it contains changes that haven’t been saved yet), then Emacs will refuse to automatically revert it. If you save a previously modified buffer, then that results in what is seen by Git as an uncommitted change. Git will then refuse to carry out any commands that would cause these changes to be lost. In other words, if there is anything that could be lost, then either Git or Emacs will refuse to discard the changes.
However, if you use file-visiting buffers as a sort of ad hoc "staging area", then the automatic reverts could potentially cause data loss. So far I have heard from only one user who uses such a workflow.
An example: You visit some file in a buffer, edit it, and save the changes. Then, outside of Emacs (or at least not using Magit or by saving the buffer) you change the file on disk again. At this point the buffer is the only place where the intermediate version still exists. You have saved the changes to disk, but that has since been overwritten. Meanwhile Emacs considers the buffer to be unmodified (because you have not made any changes to it since you last saved it to the visited file) and therefore would not object to it being automatically reverted. At this point an Auto-Revert mode would kick in. It would check whether the buffer is modified and since that is not the case it would revert it. The intermediate version would be lost. (Actually you could still get it back using the
If your workflow depends on Emacs preserving the intermediate version in the buffer, then you have to disable all Auto-Revert modes. But please consider that such a workflow would be dangerous even without using an Auto-Revert mode, and should therefore be avoided. If Emacs crashes or if you quit Emacs by mistake, then you would also lose the buffer content. There would be no autosave file still containing the intermediate version (because that was deleted when you saved the buffer) and you would not be asked whether you want to save the buffer (because it isn’t modified).