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

From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Jun 25, 2010, 15:25 UTC
Message-ID: <vpqvd97rv5q.fsf@bauges.imag.fr>
In-Reply-To: <633f42d1967049780d66cf72552b22ae17bbbead.1277476258.git.git@drmicha.warpmail.net>

Michael J Gruber <git@drmicha.warpmail.net> writes:

Show 20 quoted lines

> The empty treeish in ":path" means "index". Document this.
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
>  Documentation/git-rev-parse.txt |    5 +++--
>  1 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index 8db600f..f964de4 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
>    followed by something else than '!' is reserved for now.
>  
>  * 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.
> +  at the given path in the tree-ish object named by the ref
> +  before the colon. An empty ref before ':' denotes the content
> +  recorded in the index at the given path.

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

>  * 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.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/