Clarify use of --heading/--no-heading.

Fixes #247.

3 files changed, 16 insertions, 8 deletions

diff --git a/doc/rg.1 b/doc/rg.1
index bf49ec57..d1f2174f 100644
--- a/doc/rg.1
+++ b/doc/rg.1
@@ -222,13 +222,17 @@ This is the default when one file is searched.
 .RE
 .TP
 .B \-\-heading
-Show the file name above clusters of matches from each file.
+Show the file name above clusters of matches from each file instead of
+showing the file name for every match.
 This is the default mode at a tty.
 .RS
 .RE
 .TP
 .B \-\-no\-heading
-Don\[aq]t show any file name heading.
+Don\[aq]t group matches by each file.
+If \-H/\-\-with\-filename is enabled, then file names will be shown for
+every line matched.
+This is the default more when not at a tty.
 .RS
 .RE
 .TP
diff --git a/doc/rg.1.md b/doc/rg.1.md
index 11487d69..f0fed3da 100644
--- a/doc/rg.1.md
+++ b/doc/rg.1.md
@@ -147,11 +147,13 @@ Project home page: https://github.com/BurntSushi/ripgrep
   one file is searched.
 
 --heading
-: Show the file name above clusters of matches from each file.
-  This is the default mode at a tty.
+: Show the file name above clusters of matches from each file instead of
+  showing the file name for every match. This is the default mode at a tty.
 
 --no-heading
-: Don't show any file name heading.
+: Don't group matches by each file. If -H/--with-filename is enabled, then
+  file names will be shown for every line matched. This is the default more
+  when not at a tty.
 
 --hidden
 : Search hidden directories and files. (Hidden directories and files are
diff --git a/src/app.rs b/src/app.rs
index 231f6bcb..937529f3 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -338,11 +338,13 @@ lazy_static! {
         doc!(h, "heading",
              "Show matches grouped by each file.",
              "This shows the file name above clusters of matches from each \
-              file. This is the default mode at a tty.");
+              file instead of showing the file name for every match. This is \
+              the default mode at a tty.");
         doc!(h, "no-heading",
              "Don't group matches by each file.",
-             "Don't group matches by each file. This is the default mode \
-              when not at a tty.");
+             "Don't group matches by each file. If -H/--with-filename is \
+              enabled, then file names will be shown for every line matched. \
+              This is the default mode when not at a tty.");
         doc!(h, "hidden",
              "Search hidden files and directories.",
              "Search hidden files and directories. By default, hidden files \