On 2023-10-23 09:00, Oswald Buddenhagen wrote:
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@xxxxxx>
---
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.
Cc: Junio C Hamano <gitster@xxxxxxxxx>
Cc: Phillip Wood <phillip.wood123@xxxxxxxxx>
Cc: Christian Couder <christian.couder@xxxxxxxxx>
Cc: Charvi Mendiratta <charvi077@xxxxxxxxx>
Cc: Marc Branchaud <marcnarc@xxxxxxxxxxx>
---
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.
+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.
