From ae863bc7aa6fc887aa237b007f3bfce4fdf33e11 Mon Sep 17 00:00:00 2001
From: Andrew Gallant <jamslam@gmail.com>
Date: Sun, 12 Mar 2017 20:31:09 -0400
Subject: [PATCH] Improve docs for --glob flag.

Fixes #345.
---
 doc/rg.1    | 27 ++++++++++++++++++---------
 doc/rg.1.md |  9 +++++++--
 2 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/doc/rg.1 b/doc/rg.1
index de0d5910..e5d4323c 100644
--- a/doc/rg.1
+++ b/doc/rg.1
@@ -64,20 +64,29 @@ Treat the pattern as a literal string instead of a regular expression.
 .TP
 .B \-g, \-\-glob \f[I]GLOB\f[] ...
 Include or exclude files for searching that match the given glob.
-This always overrides any other ignore logic.
+This always overrides any other ignore logic if there is a conflict, but
+is otherwise applied in addition to ignore files (e.g., .gitignore or
+\&.ignore).
 Multiple glob flags may be used.
 Globbing rules match .gitignore globs.
 Precede a glob with a \[aq]!\[aq] to exclude it.
 .RS
-.PP
-Values given to \-g must be quoted or your shell will expand them and
-result in unexpected behavior.
-.PP
-Combine with the \-\-files flag to return matched filenames (i.e., to
-replicate ack/ag\[aq]s \-g flag).
-.PP
-For example: rg \-g \[aq]<glob>\[aq] \-\-files
 .RE
+.PP
+The \-\-glob flag subsumes the functionality of both the \-\-include and
+\-\-exclude flags commonly found in other tools.
+.IP
+.nf
+\f[C]
+Values\ given\ to\ \-g\ must\ be\ quoted\ or\ your\ shell\ will\ expand\ them\ and\ result
+in\ unexpected\ behavior.
+
+Combine\ with\ the\ \-\-files\ flag\ to\ return\ matched\ filenames
+(i.e.,\ to\ replicate\ ack/ag\[aq]s\ \-g\ flag).
+
+For\ example:\ rg\ \-g\ \[aq]\\<glob\\>\[aq]\ \-\-files
+\f[]
+.fi
 .TP
 .B \-h, \-\-help
 Show this usage message.
diff --git a/doc/rg.1.md b/doc/rg.1.md
index fce63c56..d8e498c0 100644
--- a/doc/rg.1.md
+++ b/doc/rg.1.md
@@ -49,8 +49,13 @@ Project home page: https://github.com/BurntSushi/ripgrep
 
 -g, --glob *GLOB* ...
 : Include or exclude files for searching that match the given glob. This always
-  overrides any other ignore logic. Multiple glob flags may be used. Globbing
-  rules match .gitignore globs. Precede a glob with a '!' to exclude it.
+  overrides any other ignore logic if there is a conflict, but is otherwise
+  applied in addition to ignore files (e.g., .gitignore or .ignore). Multiple
+  glob flags may be used. Globbing rules match .gitignore globs. Precede a
+  glob with a '!' to exclude it.
+
+  The --glob flag subsumes the functionality of both the --include and
+  --exclude flags commonly found in other tools.
 
     Values given to -g must be quoted or your shell will expand them and result
     in unexpected behavior.