threads / patch / 52230

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

Subject: [PATCH] doc: improve readability of --rebase-merges in git-rebase

## tl;dr

6 messages between Nov 10, 2019 and Nov 12, 2019. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Naveen Nathan· Nov 10, 2019, 09:59 UTC · lore

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.

Signed-off-by: Naveen Nathan <naveen@lastninja.net>
---
 Documentation/git-rebase.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

Show changes to Documentation/git-rebase.txt +3 −3

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 639a4179d1..6a826b47bd 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -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

-- 
2.21.0

Johannes Schindelin· Nov 11, 2019, 08:49 UTC · re: Naveen Nathan · lore

Re: [PATCH] doc: improve readability of --rebase-merges in git-rebase

Hi Naveen,

On Sun, 10 Nov 2019, Naveen Nathan wrote:

Show 24 quoted lines

> 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.
>
> Signed-off-by: Naveen Nathan <naveen@lastninja.net>
> ---
>  Documentation/git-rebase.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index 639a4179d1..6a826b47bd 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -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

Show 8 quoted lines

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

Junio C Hamano· Nov 11, 2019, 09:08 UTC · re: Naveen Nathan · lore

Re: [PATCH] doc: improve readability of --rebase-merges in git-rebase

Naveen Nathan <naveen@lastninja.net> writes:

Show 12 quoted lines

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

Naveen Nathan· Nov 11, 2019, 21:44 UTC · re: Junio C Hamano · lore

Re: [PATCH] doc: improve readability of --rebase-merges in git-rebase

Show 5 quoted 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

Naveen Nathan· Nov 11, 2019, 23:21 UTC · re: Junio C Hamano · lore

[PATCH v2] doc: improve readability of --rebase-merges in git-rebase

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.

Signed-off-by: Naveen Nathan <naveen@lastninja.net>
---
 Documentation/git-rebase.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Show changes to Documentation/git-rebase.txt +2 −2

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 639a4179d1..0c4f038dd6 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -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

-- 
2.21.0

Junio C Hamano· Nov 12, 2019, 04:18 UTC · re: Naveen Nathan · lore

Re: [PATCH v2] doc: improve readability of --rebase-merges in git-rebase

Naveen Nathan <naveen@lastninja.net> writes:

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