Subject: bug#75626: 31.0.50; Dired misses or double-processes files when auto-revert-mode is enabled

From: Michael Albinus <[email-masked]>
Date: Sun, 02 Feb 2025 13:30:47 +0100

Michael Albinus <[email-masked]> writes:

Hi Tassilo,

>> Maybe the caveat that notifications might not result in a revert when a
>> buffer's major mode doesn't allow a revert at that time should be
>> documented.
>
> Agreed. I'm just working on the Elisp manual; will mention it there.

Appended is the doc change I propose. For review.

>> Bye,
>> Tassilo

Best regards, Michael.

diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 50c7ace253c..f3f0902f364 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -852,6 +852,30 @@ Reverting
 as a consequence of auto-reverting.  Of course, moving point might be
 inevitable if the buffer radically changes.

+@defvar inhibit-auto-revert-buffers
+When the current buffer is member of this variable (a list of buffers),
+auto-reverting is suppressed for that buffer.  This is useful if serious
+changes are applied to that buffer which would be poisoned by an
+unexpected auto-revert.  After the change is finished, the buffer shall
+be removed from @code{inhibit-auto-revert-buffers}.
+
+The check of membership in @code{inhibit-auto-revert-buffers} is applied
+prior to the call of @code{buffer-stale-function}; any heavy check in
+that function is avoided, therefore.
+
+If auto-reverting is triggered by file notification while
+@code{inhibit-auto-revert-buffers} prevents this, auto-revert will
+happen next time the buffer is polled for changes, unless
+@code{auto-revert-avoid-polling} is non-@code{nil}.  @pxref{(emacs) Auto
+Revert}.
+@end defvar
+
+@defmac inhibit-auto-revert &rest body
+This macro adds the current buffer to
+@code{inhibit-auto-revert-buffers}, runs @var{body}, and removes the
+current buffer from @code{inhibit-auto-revert-buffers} afterwards.
+@end defmac
+
 You should make sure that the @code{revert-buffer-function} does not
 print messages that unnecessarily duplicate Auto Revert's own messages,
 displayed if @code{auto-revert-verbose} is @code{t}, and effectively