Previous: , Up: Modes and Buffers   [Contents][Index]

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 changed 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 changed 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.

Command: 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 for how many seconds Emacs waits 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 redefines 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-buffers-p.

However the default is nil, to not 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.

Previous: , Up: Modes and Buffers   [Contents][Index]