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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 25, 2010, 15:53 UTC
Message-ID: <7vd3vfkt17.fsf@alter.siamese.dyndns.org>
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.

I am wondering if it is less confusing to present these two cases as two independent entries...

    A colon ':' followed by a path names the blob at the given path in the
    index.

    A tree-ish, followed by a colon ':', followed by a path names the blob
    or tree at the given path  in the tree-ish.

It is not like we treat the index as a pseudo tree, but your wording implies we do in this syntax. We of course cannot treat the index as a pseudo tree in all operations, and people can get confused and ask "When can I say empty to mean index?"...

Thoughts?