Thomas Rast <trast@xxxxxxxxxxxxxxx> writes:
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index ff23cb0..779fa87 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -59,8 +59,9 @@ OPTIONS
> instead.
>
> --verify::
> - The parameter given must be usable as a single, valid
> - object name. Otherwise barf and abort.
> + The parameter must either be formed like an object name, or
> + dereference to an object name. This does 'not' verify that
> + the object actually exists! See EXAMPLES below.
To paraphrase what this text says, if you do
echo >.git/refs/tags/next e17aa8a9dca972ca278dd91a097873101066e963
where that hexstring does not name any existing object [*1*], you can
successfully verify "tags/next" (i.e. "git rev-parse --verify tags/next"),
but not "tags/next^0", because "tags/next^0" does not "dereference" to a
40-hex string, while "tags/next" does.
That's all good, but as I said, the hexstring is _not_ an object name. So
"dereference to an object name" is actively a wrong thing to say here.
You meant "40-hex string" with "formed _like_ an object name" in the
above, and the "like" is an attempt to say "could be usable to name an
object, but does not mean that the object has to exist".
But "dereferencing" a 40-hex string yields itself, so what you wrote can
be simplified to something like this, without using a wrong term "object
name":
Makes sure that the parameter dereferences to a string of 40
hexadecimal characters. Otherwise barf and abort.
But then, if you read the original carefully, it already says "must be
usable as a single valid object name", and "be usable as" does not
necessarily mean "named object must exist". So I agree you identified
something that needs to be clarified, but I do not think your rewrite
clarified things very much.
How about this?
The parameter given must be usable as a string to name a single
object (note that the named object does not have to exist).
Otherwise barf and abort.
Unfortunately, this does not clarify if it satisfies the above condition
to say "refs/heads/nosuch" in a repository without "nosuch" branch---the
ref expression is usable as a string to name a single object, so it should
verify Ok, but the reason it doesn't name a single object is not because
it yields a 40-hex string that no object with that name exists, but
because it doesn't dereference to a 40-hex string to begin with. So it
actually should _not_ verify well.
To fully clarify this, I think the first step we need is to add a better
definition of "to dereference" (or whatever word we would end up using to
call the act of passing a string through get_sha1()) to the glossary.
Then we can use the "string of 40 hexadecimal" rewrite I gave earlier.
[Footnote]
*1* These days, "git tag" and even "git update-ref" seems to verify that
the given name actually refers to an existing object, so this experiment
has to be done by manually futzing with the repository. Joy of safety ;-)
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html