doc: clarify --with-filename behavior with --heading

4 files changed, 13 insertions, 6 deletions

diff --git a/complete/_rg b/complete/_rg
index ec4863b8..cd5b5ac6 100644
--- a/complete/_rg
+++ b/complete/_rg
@@ -80,7 +80,7 @@ _rg() {
     '*'{-u,--unrestricted}'[reduce level of "smart" searching]'
     '(: -)'{-V,--version}'[display version information]'
     '(-p --heading --no-heading --pretty)--vimgrep[show results in vim-compatible format]'
-    '(-H --no-filename --with-filename)'{-H,--with-filename}'[prefix each match with name of file that contains it]'
+    '(-H --no-filename --with-filename)'{-H,--with-filename}'[display the file name for matches]'
     '(-w -x --line-regexp --word-regexp)'{-w,--word-regexp}'[only show matches surrounded by word boundaries]'
     '(-e -f --file --files --regexp --type-list)1: :_rg_pattern'
     '(--type-list)*:file:_files'
diff --git a/doc/rg.1 b/doc/rg.1
index c0c1df0d..1b346740 100644
--- a/doc/rg.1
+++ b/doc/rg.1
@@ -274,8 +274,11 @@ Only show path of each file with no matches.
 .RE
 .TP
 .B \-H, \-\-with\-filename
-Prefix each match with the file name that contains it.
+Display the file name for matches.
 This is the default when more than one file is searched.
+If \-\-heading is enabled, the file name will be shown above clusters of
+matches from each file; otherwise, the file name will be shown on each
+match.
 .RS
 .RE
 .TP
diff --git a/doc/rg.1.md b/doc/rg.1.md
index 56fb5858..a069691e 100644
--- a/doc/rg.1.md
+++ b/doc/rg.1.md
@@ -182,8 +182,10 @@ Project home page: https://github.com/BurntSushi/ripgrep
 : Only show path of each file with no matches.
 
 -H, --with-filename
-: Prefix each match with the file name that contains it. This is the
-  default when more than one file is searched.
+: Display the file name for matches. This is the default when
+  more than one file is searched. If --heading is enabled, the
+  file name will be shown above clusters of matches from each
+  file; otherwise, the file name will be shown on each match.
 
 --no-filename
 : Never show the filename for a match. This is the default when
diff --git a/src/app.rs b/src/app.rs
index 061f8705..615b21d1 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -398,8 +398,10 @@ lazy_static! {
              "Only show the paths that contains zero matches.");
         doc!(h, "with-filename",
              "Show file name for each match.",
-             "Prefix each match with the file name that contains it. This is \
-              the default when more than one file is searched.");
+             "Display the file name for matches. This is the default when \
+             more than one file is searched. If --heading is enabled, the \
+             file name will be shown above clusters of matches from each \
+             file; otherwise, the file name will be shown on each match.");
         doc!(h, "no-filename",
              "Never show the file name for a match.",
              "Never show the file name for a match. This is the default when \