Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)

From: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
Date: Oct 24, 2023, 21:19 UTC
Message-ID: <ZTg0zXkvSQ6L+4Oj@ugly>
In-Reply-To: <e33f919d-1b6a-4944-ab5d-93ad0d323b68@xiplink.com>

On Tue, Oct 24, 2023 at 10:01:07AM -0400, Marc Branchaud wrote:

Show 5 quoted lines

>I will only say that, I personally don't read man pages from 
>start-to-end like a novel.  I jump to the part that explains the thing 
>I need to learn about.  So I think your assumptions about what context 
>a reader might have in mind when they see this text are invalid.
>

we are speaking about the context of a single paragraph, so that doesn't seem like a relevant objection.

Show 5 quoted lines

>> +The commit message for the folded commit is the concatenation of the
>> +message of the first commit with those of commits identified by "squash"
>
>s/message of the first commit/picked commit's message/
>

that does indeed sound better, but i think it's more confusing (and potentially even more so when translated directly). i guess one could use "pick'd commit's", but that's kind of ugly again.

Show 9 quoted lines

>> +commands, omitting those of commits identified by "fixup" commands,
>> +unless "fixup -c" is used. In the latter case, the message is obtained
>> +only from the "fixup -c" commit (having more than one of these is
>> +incorrect).
>
>As Phillip said, this is wrong.  I agree with Phillip that the 
>documentation should reflect the actual implementation, not what we hope 
>the implementation might be some day.
>

there is also the middle ground of making it intentionally vague in anticipation of a possible change. my current draft says "if multiple are present, the last one takes precedence, but this should not be relied upon".

Show 5 quoted lines

>> +The first commit which contributes to the suggested commit message 
>> also
>
>s/suggested/folded/ -- with "fixup -C" there is no "suggested" message.
>

that's a good point, but i want to emphasize the fact that it's the pre-edit message, i.e., that trimming down the squashed message doesn't change anything. anyway, this part will be postponed to another contribution anyway (see parallel thread).

thanks