threads / patch / 22830

patch, 4 partsgrep docs: pluralize "Example" section

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

## tl;dr

7 messages between Feb 26, 2010 and Feb 26, 2010. Diffs are folded; open one to read it.

replies: 6people: 2as markdown or json

Mark Lodato· Feb 26, 2010, 03:40 UTC · lore

[PATCH 0/4] git-grep documentation updates

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(-)

Mark Lodato· Feb 26, 2010, 03:40 UTC · re: Mark Lodato · lore

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

Show changes to Documentation/git-grep.txt +2 −1

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

Mark Lodato· Feb 26, 2010, 03:40 UTC · re: Mark Lodato · lore

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

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(-)

Show changes to Documentation/git-grep.txt +5 −5

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

Mark Lodato· Feb 26, 2010, 03:40 UTC · re: Mark Lodato · lore

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

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(-)

Show changes to Documentation/git-grep.txt +3 −3

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

Mark Lodato· Feb 26, 2010, 03:40 UTC · re: Mark Lodato · lore

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

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(-)

Show changes to Documentation/git-grep.txt +8 −4

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

Junio C Hamano· Feb 26, 2010, 05:13 UTC · re: Mark Lodato · lore

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

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.

Mark Lodato· Feb 26, 2010, 22:07 UTC · re: Junio C Hamano · lore

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

On Fri, Feb 26, 2010 at 12:13 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 11 quoted lines

> 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(-)

Show changes to Documentation/git-grep.txt +2 −1

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