Re: [PATCHv2] git-replace.txt: Clarify list mode

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Aug 27, 2011, 14:07 UTC
Message-ID: <4E58FA20.4030204@drmicha.warpmail.net>
In-Reply-To: <7v4o14f844.fsf@alter.siamese.dyndns.org>

Junio C Hamano venit, vidit, dixit 26.08.2011 18:30:

Show 34 quoted lines

> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> Clarify that in list mode, "git replace" outputs the shortened ref
>> names, not their values.
>>
>> Also, point to the difficult to find git show-ref $(git replace -l).
>>
>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
>> ---
>>  Documentation/git-replace.txt |    8 ++++++++
>>  1 files changed, 8 insertions(+), 0 deletions(-)
>>
>> diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
>> index 17df525..cd00837 100644
>> --- a/Documentation/git-replace.txt
>> +++ b/Documentation/git-replace.txt
>> @@ -61,6 +61,13 @@ OPTIONS
>>  	all if no pattern is given).
>>  	Typing "git replace" without arguments, also lists all replace
>>  	refs.
>> ++
>> +Note that this lists the names of the replace refs, not their values
>> +(not their replacements). You can get the latter like this, e.g.:
> 
> Hmm, the update is _not wrong_ per-se, but...
> 
> I highly doubt we would want to try to cover confusions that may come from
> any and all different mis-/pre-conceptions people may have by making the
> description _longer_.
> 
> Which part of the wording in the existing description made you think that
> the command might list both names and their contents?  We should identify
> that misleading description (if there is) and fix that, instead of tacking
> clarifying clauses at the end.

Full disclosure: I misunderstood it when I read it the first time. I never expected it to list pairs of refs, but the questions is: Does it list the original sha1 or the replacement sha1?

"replace ref" can be very easily misunderstood as "the ref which replaces", i.e. the replacement sha1. I know a ref is not a rev, but "replace ref" can easily be misread as "replace rev", "replaced ref" etc.

Secondly, "git replace -l sha1" is completely useless, and I did not expect that either. Granted, it outputs sha1 or not, depending on whether it is replaced or not, so "completely" is a bit harsh, but still.

So, while I still have things to learn about git, I've also had my share of exposure to refs and revs, and if I misunderstand a man page, it indicates that there may be others whom I could help with what I've learned from my own misunderstandings.

Also, as regards to clarifying: In out man pages, we often show practical, non-obvious ways in which a user can combine commands, and I think git show-ref $(git replace -l) is one of them.

Show 7 quoted lines

> Given these statements:
> 
> 	"git replace" lists all replace refs.
>         "ls" lists paths in the directory.
> 
> I would say a natural reading of them is that they list "replace refs" and
> "paths", not "replace refs and their contents" and "paths and their contents".

This is natural, and the confusion above is a non-issue, *if* the reader is very aware of the implementation of replacements as lightweight tag-like refs with the sha1 as refname.

> By the way, one thing I forgot to say was that I do not think the variant
> of the output you wanted to have is necessarily a bad thing (it is bad to
> change the existing output to that variant, breaking other
> people). Perhaps it can become "-v(erbose)" output?

I'd say yes, Christian seems to prefer having "-v" even closer to "branch -v". I'd say a user has the right to expect "-v,--verbose" giving more information, but the type and extent of information should depend on the actual command :)

Michael