[PATCH 0/4] git-grep documentation updates

[PATCH 0/4] git-grep documentation updates

[Mark Lodato]

This patch series contains some small changes to git-grep.txt.  It is
based on my previous "grep documentation: clarify what files match",
committed to master as 3ac44408.  I posted these as four separate
patches to document each change individually, but they could be squashed
into one if that is preferable.

Mark Lodato (4):
  grep docs: pluralize "Example" section
  grep docs: use AsciiDoc literals consistently
  grep docs: --cached and <tree>... are incompatible
  grep docs: document --no-index option

 Documentation/git-grep.txt |   30 +++++++++++++++++-------------
 1 files changed, 17 insertions(+), 13 deletions(-)

[PATCH 1/4] grep docs: pluralize "Example" section

[Mark Lodato]

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git-grep.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index c44724d..ae663b0 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -174,8 +174,8 @@ OPTIONS
 	If given, limit the search to paths matching at least one pattern.
 	Both leading paths match and glob(7) patterns are supported.
 
-Example
--------
+Examples
+--------
 
 git grep 'time_t' -- '*.[ch]'::
 	Looks for `time_t` in all tracked .c and .h files in the working
-- 
1.7.0

[PATCH 2/4] grep docs: use AsciiDoc literals consistently

[Mark Lodato]

The convention for this particular page is to use AsciiDoc literal
strings only for options (`-x` or `--long`), but not for definition list
terms and not for <meta-vars>.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git-grep.txt |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index ae663b0..2e16130 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -98,8 +98,8 @@ OPTIONS
 --files-without-match::
 	Instead of showing every matched line, show only the
 	names of files that contain (or do not contain) matches.
-	For better compatibility with 'git diff', --name-only is a
-	synonym for --files-with-matches.
+	For better compatibility with 'git diff', `--name-only` is a
+	synonym for `--files-with-matches`.
 
 -z::
 --null::
@@ -125,7 +125,7 @@ OPTIONS
 	matches.
 
 -<num>::
-	A shortcut for specifying -C<num>.
+	A shortcut for specifying `-C<num>`.
 
 -p::
 --show-function::
@@ -140,7 +140,7 @@ OPTIONS
 
 -e::
 	The next parameter is the pattern. This option has to be
-	used for patterns starting with - and should be used in
+	used for patterns starting with `-` and should be used in
 	scripts passing user input to grep.  Multiple patterns are
 	combined by 'or'.
 
@@ -163,7 +163,7 @@ OPTIONS
 	Do not output matched lines; instead, exit with status 0 when
 	there is a match and with non-zero status when there isn't.
 
-`<tree>...`::
+<tree>...::
 	Search blobs in the trees for specified patterns.
 
 \--::
-- 
1.7.0

[PATCH 3/4] grep docs: --cached and <tree>... are incompatible

[Mark Lodato]

In the synopsis for git-grep(1), show that --cached and <tree>... cannot
be used together.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
One downside to this change is that having --cached makes it prominent, which
is good since it's a very common option.  However, I think accuracy is more
important here.

 Documentation/git-grep.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 2e16130..37ce943 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -9,8 +9,7 @@ git-grep - Print lines matching a pattern
 SYNOPSIS
 --------
 [verse]
-'git grep' [--cached]
-	   [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp]
+'git grep' [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp]
 	   [-v | --invert-match] [-h|-H] [--full-name]
 	   [-E | --extended-regexp] [-G | --basic-regexp]
 	   [-F | --fixed-strings] [-n]
@@ -21,7 +20,8 @@ SYNOPSIS
 	   [--color | --no-color]
 	   [-A <post-context>] [-B <pre-context>] [-C <context>]
 	   [-f <file>] [-e] <pattern>
-	   [--and|--or|--not|(|)|-e <pattern>...] [<tree>...]
+	   [--and|--or|--not|(|)|-e <pattern>...]
+	   [--cached | <tree>...]
 	   [--] [<pathspec>...]
 
 DESCRIPTION
-- 
1.7.0

[PATCH 4/4] grep docs: document --no-index option

[Mark Lodato]

Also clarify --cached and <tree>.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git-grep.txt |   12 ++++++++----
 1 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 37ce943..86d7401 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -21,7 +21,7 @@ SYNOPSIS
 	   [-A <post-context>] [-B <pre-context>] [-C <context>]
 	   [-f <file>] [-e] <pattern>
 	   [--and|--or|--not|(|)|-e <pattern>...]
-	   [--cached | <tree>...]
+	   [--cached | --no-index | <tree>...]
 	   [--] [<pathspec>...]
 
 DESCRIPTION
@@ -33,8 +33,11 @@ registered in the index file, or blobs in given tree objects.
 OPTIONS
 -------
 --cached::
-	Instead of searching in the working tree files, check
-	the blobs registered in the index file.
+	Instead of searching tracked files in the working tree, search
+	blobs registered in the index file.
+
+--no-index::
+	Search all files in the working tree, not just those tracked by git.
 
 -a::
 --text::
@@ -164,7 +167,8 @@ OPTIONS
 	there is a match and with non-zero status when there isn't.
 
 <tree>...::
-	Search blobs in the trees for specified patterns.
+	Instead of searching tracked files in the working tree, search
+	blobs in the given trees.
 
 \--::
 	Signals the end of options; the rest of the parameters
-- 
1.7.0

Re: [PATCH 4/4] grep docs: document --no-index option

[Junio C Hamano]

Mark Lodato <lodatom@gmail.com> writes:

> +--no-index::
> +	Search all files in the working tree, not just those tracked by git.

I gave a quick glance to all four patches.  Everything other than this
looked fine.

This one is meant to be usable outside git directory, and saying "the
working tree" is misleading.  The "work tree" is a technical term that
specifically means the files in the directory hierarchy on the filesystem
that correspond to the index entries that represent them.

It probably should say "the current directory" or something here.

Re: [PATCH 4/4] grep docs: document --no-index option

[Mark Lodato]

On Fri, Feb 26, 2010 at 12:13 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> +--no-index::
>> +     Search all files in the working tree, not just those tracked by git.
>
> This one is meant to be usable outside git directory, and saying "the
> working tree" is misleading.  The "work tree" is a technical term that
> specifically means the files in the directory hierarchy on the filesystem
> that correspond to the index entries that represent them.
>
> It probably should say "the current directory" or something here.

Here's a squashable commit to do just that.

---
 Documentation/git-grep.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 86d7401..3e6eaf7 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -37,7 +37,8 @@ OPTIONS
        blobs registered in the index file.

 --no-index::
-       Search all files in the working tree, not just those tracked by git.
+       Search all files in the current directory, not just those tracked
+       by git.

 -a::
 --text::
-- 
1.7.0