Clarify documentation of 'dired-mark-files-containing-regexp'

* doc/emacs/dired.texi (Marks vs Flags): Clarify that for files
visited in buffers, 'dired-mark-files-containing-regexp' searches
the buffer rather than the file on disk.  (Bug#22694)

* lisp/dired.el (dired-mark-files-containing-regexp): Clarify that
for files visited in buffers, 'dired-mark-files-containing-regexp'
searches the buffer rather than the file on disk.  (Bug#22694)

2 files changed, 13 insertions, 2 deletions

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 8a72805f7fc..ea48a26500c 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -550,7 +550,13 @@ Mark (with @samp{*}) all files whose @emph{contents} contain a match for
 the regular expression @var{regexp}
 (@code{dired-mark-files-containing-regexp}).  This command is like
 @kbd{% m}, except that it searches the file contents instead of the file
-name.
+name.  Note that if a file is visited in an Emacs buffer, this command
+will look in the buffer without revisiting the file, so the results
+might be inconsistent with the file on disk if its contents has changed
+since it was last visited.  If you don't want this, you may wish
+reverting the files you have visited in your buffers, or turning on
+the @code{auto-revert} mode in those buffers, before invoking this
+command.  @xref{Reverting}.
 
 @item C-/
 @itemx C-x u
diff --git a/lisp/dired.el b/lisp/dired.el
index 5741872cfc8..f1adcb4c3db 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -3353,7 +3353,12 @@ object files--just `.o' will mark more than you might think."
 (defun dired-mark-files-containing-regexp (regexp &optional marker-char)
   "Mark all files with contents containing REGEXP for use in later commands.
 A prefix argument means to unmark them instead.
-`.' and `..' are never marked."
+`.' and `..' are never marked.
+
+Note that if a file is visited in an Emacs buffer, this command will
+look in the buffer without revisiting the file, so the results might
+be inconsistent with the file on disk if its contents has changed
+since it was last visited."
   (interactive
    (list (read-regexp (concat (if current-prefix-arg "Unmark" "Mark")
                               " files containing (regexp): ")