Re: [PATCH] rev-parse: clarify documentation for the --verify option

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 31, 2013, 22:52 UTC
Message-ID: <7vwqsnnpwj.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1364625865-8459-1-git-send-email-mhagger@alum.mit.edu>

Michael Haggerty <mhagger@alum.mit.edu> writes:

> ...  Though honestly, I don't see the point of using
> --default as opposed to
>
>     $ git rev-parse --verify ${REV:-master}^{commit}

I would agree ${VAR:-default} is sufficient in that particular case.

The --default is more about the use of the pluming command not with --verify but as its original use of an "argument sifter" when composing "git rev-list" piped into "git diff-tree --stdin", i.e.

	git rev-list $(git rev-parse --default HEAD --revs-only "$@") |
        git diff-tree --stdin $(git rev-parse --no-revs "$@")

which was the original way to write commands in the "git log" family using the plumbing command as a scripted Porcelain.

Show 5 quoted lines

>  --verify::
> +	If the parameter can be used as a single object name, output
> +	that name; otherwise, emit an error message and exit with a
> +	non-zero status.  Please note that the existence and validity
> +	of the named object itself are not checked.

Perhaps s/used as a single object name/turned into a raw 20-byte SHA-1/;

Because the primary use case of this option is to implement end-user input validation, I think it would be helpful to clarify use of the peeler here. Perhaps

    --verify::
            Make sure the single given parameter can be turned into a
            raw 20-byte SHA-1, something that can be used to access the
            object database, and emit the SHA-1 in 40-hex format (unless
            --symbolic and other formatting option is given); otherwise,
            error out.
    +
    If you want to make sure that the output from this actually
    names an object in your object database and/or can be used
    as a specific type of object you require, it is a good idea
    to add "^{type}" peeling operator to the parmeter.  For
    example, `git rev-parse "$VAR^{commit}"` will make sure $VAR
    names an existing object that is a commit-ish (i.e. a
    commit, or an annotated tag that points at a commit).  To
    make sure that $VAR names an existing object of any type,
    you can say `git rev-parse "$VAR^{object}"`.

or something.