GNU Emacs
Emacs
Dashboard

18.5 Auto Revert: Keeping buffers automatically up-to-date

A buffer can get out of sync with respect to its visited file on disk if that file is changed by another program. To keep it up to date, you can enable Auto Revert mode by typing M-x auto-revert-mode. This automatically reverts the buffer when its visited file changes on disk. To do the same for all file buffers, type M-x global-auto-revert-mode to enable Global Auto Revert mode.

Auto Revert will not revert a buffer if it has unsaved changes, or if its file on disk is deleted or renamed.

One use of Auto Revert mode is to “tail” a file such as a system log, so that changes made to that file by other programs are continuously displayed. To do this, just move the point to the end of the buffer, and it will stay there as the file contents change. However, if you are sure that the file will only change by growing at the end, use Auto Revert Tail mode instead ( auto-revert-tail-mode). It is more efficient for this. Auto Revert Tail mode also works for remote files.

When a buffer is auto-reverted, a message is generated. This can be suppressed by setting auto-revert-verbose to nil.

The Auto Revert modes do not check or revert remote files, because that is usually too slow. This behavior can be changed by setting the variable auto-revert-remote-files to non- nil.

By default, Auto Revert mode works using file notifications, whereby changes in the filesystem are reported to Emacs by the OS. You can disable use of file notifications by customizing the variable auto-revert-use-notify to a nil value, then Emacs will check for file changes by polling every five seconds. You can change the polling interval through the variable auto-revert-interval.

Not all systems support file notifications; where they are not supported, auto-revert-use-notify will be nil by default.

By default, Auto Revert mode will poll files for changes periodically even when file notifications are used. Polling is unnecessary in many cases, and turning it off may save power by relying on notifications only. To do so, set the variable auto-revert-avoid-polling to non- nil. However, notification is ineffective on certain file systems; mainly network file system on Unix-like machines, where files can be altered from other machines. For such file systems, polling may be necessary. To force polling when auto-revert-avoid-polling is non- nil, set auto-revert-notify-exclude-dir-regexp to match files that should be excluded from using notification.

In Dired buffers (see Dired, the Directory Editor), Auto Revert mode refreshes the buffer when a file is created or deleted in the buffer’s directory.

See Undoing Version Control Actions, for commands to revert to earlier versions of files under version control. See Version Control and the Mode Line, for Auto Revert peculiarities when visiting files under version control.