Skip to contentSkip to conversation

doc: improve readability of --rebase-merges in git-rebase

PATCH Superseded Naveen Nathan 3 participants 6 messages Nov 10, 2019 – Nov 12, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: improve readability of --rebase-merges in git-rebase

When --rebase-merges was introduced in 427c3bd28a the sentence describing the difference between --rebase-merges and --preserve-merges is a little unclear and difficult to parse. This patch improves readability while retaining original meaning.

---
 Documentation/git-rebase.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-rebase.txt +3 -3
index 639a4179d1..6a826b47bd 100644
@@ -442,9 +442,9 @@ i.e. commits that would be excluded by linkgit:git-log[1]'s
 the `rebase-cousins` mode is turned on, such commits are instead rebased
 onto `<upstream>` (or `<onto>`, if specified).
 +
-The `--rebase-merges` mode is similar in spirit to the deprecated
-`--preserve-merges`, but in contrast to that option works well in interactive
-rebases: commits can be reordered, inserted and dropped at will.
+The `--rebase-merges` mode is similar in spirit to `--preserve-merges`
+(deprecated) but actually works with interactive rebases, where commits
+can be reordered, inserted and dropped at will.
 +
 It is currently only possible to recreate the merge commits using the
 `recursive` merge strategy; Different merge strategies can be used only via
Signature · 1 line
2.21.0
#1 lore raw

Hi Naveen,

Quoted 15 lines · Naveen Nathan

When --rebase-merges was introduced in 427c3bd28a the sentence describing the difference between --rebase-merges and --preserve-merges is a little unclear and difficult to parse. This patch improves readability while retaining original meaning.

---
 Documentation/git-rebase.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-rebase.txt +0 -0
index 639a4179d1..6a826b47bd 100644

Documentation/git-rebase.txt i.e. commits that would be excluded by linkgit:git-log[1]'s · line 447

Quoted 9 lines
Documentation/git-rebase.txt +3 -3
@@ -442,9 +442,9 @@ i.e. commits that would be excluded by linkgit:git-log[1]'s
 the `rebase-cousins` mode is turned on, such commits are instead rebased
 onto `<upstream>` (or `<onto>`, if specified).
 +
-The `--rebase-merges` mode is similar in spirit to the deprecated
-`--preserve-merges`, but in contrast to that option works well in interactive
-rebases: commits can be reordered, inserted and dropped at will.
+The `--rebase-merges` mode is similar in spirit to `--preserve-merges`
+(deprecated) but actually works with interactive rebases, where commits
+can be reordered, inserted and dropped at will.

I like it!

ACK,
Dscho

Quoted 8 lines
Documentation/git-rebase.txt +0 -1
 +
 It is currently only possible to recreate the merge commits using the
 `recursive` merge strategy; Different merge strategies can be used only via
--

2.21.0

#2 lore raw
In reply to Naveen Nathan

Documentation/git-rebase.txt i.e. commits that would be excluded by linkgit:git-log[1]'s · line 447

Quoted 12 lines · Naveen Nathan

When --rebase-merges was introduced in 427c3bd28a the sentence describing the difference between --rebase-merges and --preserve-merges is a little unclear and difficult to parse. This patch improves readability while retaining original meaning.

...

Documentation/git-rebase.txt +3 -3
-The `--rebase-merges` mode is similar in spirit to the deprecated
-`--preserve-merges`, but in contrast to that option works well in interactive
-rebases: commits can be reordered, inserted and dropped at will.
+The `--rebase-merges` mode is similar in spirit to `--preserve-merges`
+(deprecated) but actually works with interactive rebases, where commits
+can be reordered, inserted and dropped at will.

I think the original "to the deprecated --preserve-merges" is mildly easier to follow than "to --preserve-merges (deprecated)".

The later part of the sentence with this patch does read smoother and is a definite improvement.

Thanks.

#3 lore raw
Quoted 5 lines

I think the original "to the deprecated --preserve-merges" is mildly easier to follow than "to --preserve-merges (deprecated)".

The later part of the sentence with this patch does read smoother and is a definite improvement.

Thanks Junio.

I've incorporated the suggestion and will submit a new patch shortly.

- Naveen

#4 lore raw

PATCH v2 1/1 doc: improve readability of --rebase-merges in git-rebase

In reply to Junio C Hamano

When --preserve-merges was deprecated in 427c3bd28a a sentence was introduced describing the difference between --rebase-merges and --preserve-merges which is a little unclear and difficult to parse. This patch improves readability while retaining original meaning.

---
 Documentation/git-rebase.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-rebase.txt +2 -2
index 639a4179d1..0c4f038dd6 100644
@@ -443,8 +443,8 @@ the `rebase-cousins` mode is turned on, such commits are instead rebased
 onto `<upstream>` (or `<onto>`, if specified).
 +
 The `--rebase-merges` mode is similar in spirit to the deprecated
-`--preserve-merges`, but in contrast to that option works well in interactive
-rebases: commits can be reordered, inserted and dropped at will.
+`--preserve-merges` but works with interactive rebases,
+where commits can be reordered, inserted and dropped at will.
 +
 It is currently only possible to recreate the merge commits using the
 `recursive` merge strategy; Different merge strategies can be used only via
Signature · 1 line
2.21.0
#5 lore raw
Quoted 4 lines · Naveen Nathan

When --preserve-merges was deprecated in 427c3bd28a a sentence was introduced describing the difference between --rebase-merges and --preserve-merges which is a little unclear and difficult to parse. This patch improves readability while retaining original meaning.

I notice that the above also was rewritten since v1 and I think it is a very good change.

Thanks, will queue.