Re: [PATCHv2] git-rev-parse.txt: Document ":path" specifier

Matthieu Moy [off-list ref] writes:

Actually, what you're adding is precisely what was already documented
right below:

quoted

 * A colon, optionally followed by a stage number (0 to 3) and a
   colon, followed by a path; this names a blob object in the

     index at the given path.  Missing stage number (and the colon
     that follows it) names a stage 0 entry. During a merge, stage
     1 is the common ancestor, stage 2 is the target branch's version
     (typically the current branch), and stage 3 is the version from
     the branch being merged.

Probably it's not obvious enough and your patch is worth it, but then
it would be less confusing if you added "(see next item)." at the end
of your sentence.

Another possibility is to swap the order of presentation.  It might reduce
the confusion of ':path' form appearing to be a variant of 'tree:path',
and that is what invited the "what happens when tree is an empty string"
question, I think.

The empty treeish in ":path" means "index". This is actually a special
case of the ":stage:path" syntax where it is documented, but mentioning
it also together with "treeish:path" is helpful, so do it.

Signed-off-by: Michael J Gruber <redacted>
---
How about this? Short description at "rev:path" but still pointing
to ":stage:path".

 Documentation/git-rev-parse.txt |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 8db600f..d525e57 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt

@@ -291,7 +291,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
 
 * A suffix ':' followed by a path; this names the blob or tree
   at the given path in the tree-ish object named by the part
-  before the colon.
+  before the colon. ":path" (with an empty part before the colon)
+  is a special case of the syntax described next: content
+  recorded in the index at the given path.
 
 * A colon, optionally followed by a stage number (0 to 3) and a
   colon, followed by a path; this names a blob object in the

-- 
1.7.1.621.g01d76