git-grep documentation

From: sean <seanlkml@sympatico.ca>
Date: Jan 20, 2006, 13:47 UTC
Message-ID: <BAYC1-PASMTP07F7EA1F3B544C07AA01F8AE1F0@CEZ.ICE>

It looks as though git-grep.sh was coded to allow git-ls-files options to be passed after a '--' marker. However, this marker will never be seen by the script unless the user identifies the <pattern> by preceding it with an '-e'.

If it's not seen the '--' ends up getting passed to git-ls-files and any options are mistakenly interpreted as paths. For instance, the following two commands will do different things:

$ git-grep -e NAME -- --others Documentation/git-grep.txt $ git-grep NAME -- --others Documentation/git-grep.txt

Either the comment in the git-grep.sh script should be changed to say that only paths are acceptable after the '--' or fixed up to handle this case a bit better. The documentation patch below is only applicable if the script is fixed first.

Sean

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 2bfd8ed..c2c6ff3 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -8,7 +8,7 @@ git-grep - print lines matching a patter
 
 SYNOPSIS
 --------
-'git-grep' [<option>...] <pattern> [<path>...]
+'git-grep' [<option>...] [-e] <pattern> [-- [<ls option>...]] [<path>...]
 
 DESCRIPTION
 -----------
@@ -20,12 +20,21 @@ OPTIONS
 -------
 <option>...::
 	Either an option to pass to `grep` or `git-ls-files`.
-	Some `grep` options, such as `-C` and `-m`, that take
-	parameters are known to `git-grep`.
+
+	The specific `git-ls-files` options that may be supplied are:
+	`--cached`, `--deleted`, `--others`, `--killed`, `--ignored`, 
+	`--exclude=*`, `--exclude-from=*`, or `--exclude-per-directory=*`.
+	
+	All other options will be passed to `grep`.
 
 <pattern>::
 	The pattern to look for.
 
+<ls option>...::
+	Additional options for `git-ls-files` which must be preceded
+	by the '--' marker.   See `git-ls-files` for a list of 
+	available options.
+
 <path>...::
 	Optional paths to limit the set of files to be searched;
 	passed to `git-ls-files`.