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

From: Marc Branchaud <marcnarc@xiplink.com>
Date: Oct 24, 2023, 14:01 UTC
Message-ID: <e33f919d-1b6a-4944-ab5d-93ad0d323b68@xiplink.com>
In-Reply-To: <20231023130016.1093356-1-oswald.buddenhagen@gmx.de>

On 2023-10-23 09:00, Oswald Buddenhagen wrote:

Show 17 quoted lines

> Create a clear top-down structure which makes it hopefully unambiguous
> what happens when.
> 
> Also mention the timestamp along with the author - this is primarily
> meant to include the keywords somebody might be searching for, like I
> did a year ago.
> 
> Signed-off-by: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
> 
> ---
> v2:
> - slight adjustments inspired by marc. however, i left most things
>    unchanged or even went in the opposite direction, because i assume the
>    readers to be sufficiently context-sensitive, and the objective is
>    merely to be not actively confusing. adding redundancy in the name of
>    clarity would just make the text stylistically inferior and arguably
>    harder to read.

I disagree with this on many levels, but your tone seems to brook no discussion and I do not want to get into a protracted debate here.

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.

Since we have very different notions about who is reading this, I think we'll never agree on the final wording. I'll continue to make my suggestions, but I won't stand in the way of these changes if I'm the only one who thinks they could be better.

Show 34 quoted lines

> Cc: Junio C Hamano <gitster@pobox.com>
> Cc: Phillip Wood <phillip.wood123@gmail.com>
> Cc: Christian Couder <christian.couder@gmail.com>
> Cc: Charvi Mendiratta <charvi077@gmail.com>
> Cc: Marc Branchaud <marcnarc@xiplink.com>
> ---
>   Documentation/git-rebase.txt | 29 +++++++++++++++--------------
>   1 file changed, 15 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index e7b39ad244..337df9ef2f 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -890,20 +890,21 @@ 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".

s/the command "pick"/the "pick" command/

> +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/

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

Show 5 quoted lines

> +If the resulting commit message is a concatenation of multiple messages,
> +an editor is opened allowing you to edit it. This is also the case for a
> +message obtained via "fixup -c", while using "fixup -C" instead skips
> +the editor; this is analogous to the behavior of `git commit`.
> +The first commit which contributes to the suggested commit message also

s/suggested/folded/ -- with "fixup -C" there is no "suggested" message.

Thanks,

M.