Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision

From: Philip Oakley <philipoakley@iee.org>
Date: Aug 14, 2016, 22:45 UTC
Message-ID: <6ACCC850AC434350B15AADC19F02760B@PhilipOakley>
In-Reply-To: <xmqq60r3knoz.fsf@gitster.mtv.corp.google.com>

From: "Junio C Hamano" <gitster@pobox.com>

Show 22 quoted lines

> Philip Oakley <philipoakley@iee.org> writes:
>> Be clearer that the --fixup/--squash options can take any of the
>> gitrevisions methods of specifying a commit, not just a 'hash'.
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>> ...
>> @@ -81,15 +81,15 @@ OPTIONS
>>  --fixup=<commit>::
>>  Construct a commit message for use with `rebase --autosquash`.
>>  The commit message will be the subject line from the specified
>> - commit with a prefix of "fixup! ".  See linkgit:git-rebase[1]
>> - for details.
>> + commit revision with a prefix of "fixup! ".  See linkgit:git-rebase[1]
>> + and linkgit:gitrevisions[7] for details.
>
> The same comment applies to the other hunk, but rephrasing "commit"
> with "commit revision" (the latter is not even in the glossary) does
> not make it clearer at all.  Especially when discussing rebases and
> anything that rewrites commits, it can easily be mistaken as if you
> are talking about v2 of the commit by fixing up the original, but
> that is not the impression you want to give.

Hmm, had to read that a few times before I saw what you meant regarding 'v2' as the revised commit.

>
> "The specified commit" is clear enough.  It may be debatable if we
> want to talk about "how" to specify the commit, though.

Exactly. The latter.

Show 5 quoted lines

> I think the
> use of "commit" in an angle-bracket-pair in the label for the
> section, i.e. "--fixup=<commit>", has been considered to be clear
> enough to tell that you can use usual extended SHA-1 syntax to
> specify the commit you want to talk about,

I certainly hadn't picked up on that ability to use the extended sha1 syntax (specifying revisions...) here.

Part of the issue is that the whole fixup/squash capability is buried within just two documents as asides [1], and in the place it's spelt out (in rebase) it talks about the commit message being used, which is just part of the confusion.

Show 7 quoted lines

>  but if so, that is not
> limited to this entry, and I do not think this description or the
> other one for the "--squash" option are particularly worse than
> those for the "-c" and "-C" options.  The description for "-c" does
> say "Take an existing commit object", but that's like "the specified
> commit" used here.
>

OK -- Philip [1] just looked at the new Progit version and fixup/squash is not even mentioned.