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

Michael Haggerty [off-list ref] writes:

On 04/01/2013 06:56 PM, Junio C Hamano wrote:

quoted

Junio C Hamano [off-list ref] writes:

quoted

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

A "SQUASH???" patch on top of your original is queued on 'pu',
together with the earlier "^{object}" peeler patch.  Comments,
improvements, etc. would be nice.

Yes, your version is better.  I would make one change, though.  In your

+	Make sure the single given parameter can be turned into a
+	raw 20-byte SHA-1 that can be used to access the object
+	database, and emit it to the standard output. If it can't,
+	error out.

it could be made clearer that exactly one parameter should be provided.
Maybe

+	Verify that exactly one parameter is provided, and that it

That is probably better (I was hoping "the single" would mean the
same to the reader, though).  Thanks.

+     can be turned into a raw 20-byte SHA-1 that can be used to
+	access the object database.  If so, emit the SHA-1 to the
+	standard output; otherwise, error out.

But this makes it sound a little like the "raw 20-byte SHA-1" will be
output to stdout,...

I did consider that point, wrote "and outputs 40-hex" in my earlier
draft, and then rejected it because it was even more misleading.
The output follows the usual rules for "rev" parameters, e.g.

	git rev-parse --short --verify HEAD
	git rev-parse --symbolic --verify v1.8.2^{tree}

and "--verify" does not mean 40-hex output.  That is why I left it
vague as "emit it".

I agree that the wording incorrectly hints that you may be able to
get 20-byte raw output.  I didn't find a satisfactory phrasing.