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

[Phillip Wood <phillip.wood123@gmail.com>]

On 27/10/2023 14:14, Marc Branchaud wrote:
>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
>> index e7b39ad244..578d1d34a6 100644
>> --- a/Documentation/git-rebase.txt
>> +++ b/Documentation/git-rebase.txt
>> @@ -890,20 +890,22 @@ command "pick" with the command "reword".
>>   To drop a commit, replace the command "pick" with "drop", or just
>>   delete the matching line.
>> -If you want to fold two or more commits into one, replace the command
>> -"pick" for the second and subsequent commits with "squash" or "fixup".
>> -If the commits had different authors, the folded commit will be
>> -attributed to the author of the first commit.  The suggested commit
>> -message for the folded commit is the concatenation of the first
>> -commit's message with those identified by "squash" commands, omitting 
>> the
>> -messages of commits identified by "fixup" commands, unless "fixup -c"
>> -is used.  In that case the suggested commit message is only the message
>> -of the "fixup -c" commit, and an editor is opened allowing you to edit
>> -the message.  The contents (patch) of the "fixup -c" commit are still
>> -incorporated into the folded commit. If there is more than one "fixup 
>> -c"
>> -commit, the message from the final one is used.  You can also use
>> -"fixup -C" to get the same behavior as "fixup -c" except without opening
>> -an editor.
>> +If you want to fold two or more commits into one (that is, to combine
>> +their contents/patches), replace the command "pick" for the second and
>> +subsequent commits with "squash" or "fixup".
>> +The commit message for the folded commit is the concatenation of the
>> +message of the first commit with those of commits identified by "squash"
>> +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 (if multiple are present, the last one
>> +takes precedence, but this should not be relied upon).
> 
> I like the overall phrasing here.
> 
> But I think you should remove the "but this should not be relied upon" 
> phrase.  This reads as if Git's current behaviour is undefined, which 
> most definitely is not true.

I agree it would be better to remove that phrase, as you say it makes it 
sounds like the behaviour cannot be relied on.

> Even changing this to something like "but this might change in the 
> future" is unhelpful.  Everything in Git is subject to change over a 
> long-enough time span, so the same could be said about every aspect of Git.
> 
> Until the behaviour actually changes, it's perfectly fine for people to 
> use multiple "fixup -c" commands.  There's no reason to scare them off 
> of it.

Indeed

Best Wishes

Phillip