@c This is part of the Emacs manual.
@c Copyright (C) 2004--2023 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@c
@c This file is included either in emacs-xtra.texi (when producing the
@c printed version) or in the main Emacs manual (for the on-line version).

@node Non-File Buffers
@subsection Auto Reverting Non-File Buffers

Global Auto Revert Mode normally only reverts file buffers.  There are
two ways to auto-revert certain non-file buffers: by enabling Auto
Revert Mode in those buffers (using @kbd{M-x auto-revert-mode}); and
by setting @code{global-auto-revert-non-file-buffers} to a
non-@code{nil} value.  The latter enables Auto Reverting for all types
of buffers for which it is implemented (listed in the menu below).

Like file buffers, non-file buffers should normally not revert while
you are working on them, or while they contain information that might
get lost after reverting.  Therefore, they do not revert if they are
modified.  This can get tricky, because deciding when a non-file
buffer should be marked modified is usually more difficult than for
file buffers.

Another tricky detail is that, for efficiency reasons, Auto Revert
often does not try to detect all possible changes in the buffer, only
changes that are major or easy to detect.  Hence, enabling
auto-reverting for a non-file buffer does not always guarantee that
all information in the buffer is up-to-date, and does not necessarily
make manual reverts useless.

At the other extreme, certain buffers automatically revert every
@code{auto-revert-interval} seconds.  (This currently only applies to
the Buffer Menu.)  In this case, Auto Revert does not print any
messages while reverting, even when @code{auto-revert-verbose} is
non-@code{nil}.

@vindex buffer-auto-revert-by-notification
Some non-file buffers can be updated reliably by file notification on
their default directory; Dired buffers is an example.  The major mode
can indicate this by setting @code{buffer-auto-revert-by-notification}
to a non-@code{nil} value in that buffer, allowing Auto Revert to
avoid periodic polling.  Such notification does not include changes to
files in that directory, only to the directory itself.

The details depend on the particular types of buffers and are
explained in the corresponding sections.

@menu
* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu.
* Auto Reverting Dired::           Auto Revert of Dired buffers.
@end menu

@node Auto Reverting the Buffer Menu
@subsubsection Auto Reverting the Buffer Menu

If auto-reverting of non-file buffers is enabled, the Buffer Menu
@iftex
(@pxref{Several Buffers,,, emacs, the Emacs Manual})
@end iftex
@ifnottex
(@pxref{Several Buffers})
@end ifnottex
automatically reverts every
@code{auto-revert-interval} seconds, whether there is a need for it or
not.  (It would probably take longer to check whether there is a need
than to actually revert.)

If the Buffer Menu inappropriately gets marked modified, just revert
it manually using @kbd{g} and auto-reverting will resume.  However, if
you marked certain buffers to get deleted or to be displayed, you have
to be careful, because reverting erases all marks.  The fact that
adding marks sets the buffer's modified flag prevents Auto Revert from
automatically erasing the marks.

@node Auto Reverting Dired
@subsubsection Auto Reverting Dired buffers

Dired buffers only auto-revert when the file list of the buffer's main
directory changes (e.g., when a new file is added or deleted).  They
do not auto-revert when information about a particular file changes
(e.g., when the size changes) or when inserted subdirectories change.
To be sure that @emph{all} listed information is up to date, you have
to manually revert using @kbd{g}, @emph{even} if auto-reverting is
enabled in the Dired buffer.  Sometimes, you might get the impression
that modifying or saving files listed in the main directory actually
does cause auto-reverting.  This is because making changes to a file,
or saving it, very often causes changes in the directory itself; for
instance, through backup files or auto-save files.  However, this is
not guaranteed.

If the Dired buffer is marked modified and there are no changes you
want to protect, then most of the time you can make auto-reverting
resume by manually reverting the buffer using @kbd{g}.  There is one
exception.  If you flag or mark files, you can safely revert the
buffer.  This will not erase the flags or marks (unless the marked
file has been deleted, of course).  However, the buffer will stay
modified, even after reverting, and auto-reverting will not resume.
This is because, if you flag or mark files, you may be working on the
buffer and you might not want the buffer to change without warning.
If you want auto-reverting to resume in the presence of marks and
flags, mark the buffer non-modified using @kbd{M-~}.  However, adding,
deleting or changing marks or flags will mark it modified again.

Remote Dired buffers are currently not auto-reverted.  Neither are
Dired buffers for which you used shell wildcards or file arguments to
list only some of the files.  @file{*Find*} and @file{*Locate*}
buffers do not auto-revert either.

Note that auto-reverting Dired buffers may not work satisfactorily on
some systems.
