4.1.6 Automatic Reverting of File-Visiting Buffers
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 magit-auto-revert-mode.
user option magit-auto-revert-immediately​
This option controls whether Magit reverts buffers immediately.
If this is non-nil and either global-auto-revert-mode or magit-auto-revert-mode is enabled, then Magit immediately reverts buffers by explicitly calling auto-revert-buffers after running Git for side-effects.
If 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.
If magit-auto-revert-immediately and 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 auto-revert-interval seconds.
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 magit-auto-revert-repository-buffer-p.
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 magit group.
| • 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 undo command.)
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).