Deprecate git rebase --preserve-merges

From: Johannes Schindelin <[email protected]>

We have something much better now: --rebase-merges (which is a complete re-design --preserve-merges, with a lot of issues fixed such as the inability to reorder commits with --preserve-merges).

Signed-off-by Johannes Schindelin <[email protected]>

---
  Documentation/config/branch.txt |  6 +++---
  Documentation/config/pull.txt   |  6 +++---
  Documentation/git-rebase.txt    | 23 ++++++++++++-----------
  builtin/rebase.c                |  8 ++++++--
  git-rebase--preserve-merges.sh  |  2 ++
  5 files changed, 26 insertions(+), 19 deletions(-)

Documentation/config/branch.txt +3 -3

index 019d60ede2..8f4b3faadd 100644
@@ -85,9 +85,9 @@ When `merges`, pass the `--rebase-merges` option to 'git rebase'
  so that the local merge commits are included in the rebase (see
  linkgit:git-rebase[1] for details).
  +
-When preserve, also pass `--preserve-merges` along to 'git rebase'
-so that locally committed merge commits will not be flattened
-by running 'git pull'.
+When `preserve` (deprecated in favor of `merges`), also pass
+`--preserve-merges` along to 'git rebase' so that locally committed merge
+commits will not be flattened by running 'git pull'.
  +
  When the value is `interactive`, the rebase is run in interactive mode.
  +

Documentation/config/pull.txt +3 -3

index bb23a9947d..b87cab31b3 100644
@@ -18,9 +18,9 @@ When `merges`, pass the `--rebase-merges` option to 'git rebase'
  so that the local merge commits are included in the rebase (see
  linkgit:git-rebase[1] for details).
  +
-When preserve, also pass `--preserve-merges` along to 'git rebase'
-so that locally committed merge commits will not be flattened
-by running 'git pull'.
+When `preserve` (deprecated in favor of `merges`), also pass
+`--preserve-merges` along to 'git rebase' so that locally committed merge
+commits will not be flattened by running 'git pull'.
  +
  When the value is `interactive`, the rebase is run in interactive mode.
  +

Documentation/git-rebase.txt +12 -11

index 5629ba4c5d..89202dbb93 100644
@@ -415,9 +415,9 @@ i.e. commits that would be excluded by gitlink: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 `--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 the deprecated
+`--preserve-merges`, but in contrast to that option works well in interactive
+rebases: 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

@@ -427,9 +427,10 @@ See also REBASING MERGES and INCOMPATIBLE OPTIONS below.
 
  -p::
  --preserve-merges::
-	Recreate merge commits instead of flattening the history by replaying
-	commits a merge commit introduces. Merge conflict resolutions or manual
-	amendments to merge commits are not preserved.
+	[DEPRECATED: use --rebase-merges instead] Recreate merge commits
+	instead of flattening the history by replaying commits a merge commit
+	introduces. Merge conflict resolutions or manual amendments to merge
+	commits are not preserved.
  +
  This uses the `--interactive` machinery internally, but combining it
  with the `--interactive` option explicitly is generally not a good

@@ -1020,11 +1021,11 @@ merge cmake
 
  BUGS
  ----
-The todo list presented by `--preserve-merges --interactive` does not
-represent the topology of the revision graph.  Editing commits and
-rewording their commit messages should work fine, but attempts to
-reorder commits tend to produce counterintuitive results. Use
-`--rebase-merges` in such scenarios instead.
+The todo list presented by the deprecated `--preserve-merges --interactive`
+does not represent the topology of the revision graph (use `--rebase-merges`
+instead).  Editing commits and rewording their commit messages should work
+fine, but attempts to reorder commits tend to produce counterintuitive results.
+Use `--rebase-merges` in such scenarios instead.
 
  For example, an attempt to rearrange
  ------------

builtin/rebase.c +6 -2

index 7c7bc13e91..c5f5edf321 100644
@@ -1092,8 +1092,8 @@ int cmd_rebase(int argc, const char **argv, const char *prefix)
  			PARSE_OPT_NOARG | PARSE_OPT_NONEG,
  			parse_opt_interactive },
  		OPT_SET_INT('p', "preserve-merges", &options.type,
-			    N_("try to recreate merges instead of ignoring "
-			       "them"), REBASE_PRESERVE_MERGES),
+			    N_("(DEPRECATED) try to recreate merges instead of "
+			       "ignoring them"), REBASE_PRESERVE_MERGES),
  		OPT_BOOL(0, "rerere-autoupdate",
  			 &options.allow_rerere_autoupdate,
  			 N_("allow rerere to update index with resolved "

@@ -1204,6 +1204,10 @@ int cmd_rebase(int argc, const char **argv, const char *prefix)
  		usage_with_options(builtin_rebase_usage,
  				   builtin_rebase_options);
 
+	if (options.type == REBASE_PRESERVE_MERGES)
+		warning(_("--preserve-merges is deprecated in favor of "
+			  "--rebase-merges"));
+
  	if (action != NO_ACTION && !in_progress)
  		die(_("No rebase in progress?"));
  	setenv(GIT_REFLOG_ACTION_ENVIRONMENT, "rebase", 0);

git-rebase--preserve-merges.sh +2 -0

index afbb65765d..eab2e40dc6 100644
@@ -105,6 +105,8 @@ warn () {
  	printf '%s\n' "$*" >&2
  }
 
+warn "git rebase --preserve-merges is deprecated. Use --rebase-merges instead."
+
  # Output the commit message for the specified commit.
  commit_message () {
  	git cat-file commit "$1" | sed "1,/^$/d"

Documentation/git-rebase.txt +3 -0

+       instead of flattening the history by replaying commits a merge commit
+       introduces. Merge conflict resolutions or manual amendments to merge
+       commits are not preserved.

It's great to see this. Do we need the deprecation warning in both builtin/rebase.c and rebase--preserve-merges.sh? Won't that end up warning twice - maybe that's a good thing but if we go for only one I prefer the wording in rebase--preserve-merges.sh

Best Wishes

Phillip

Quoted 151 lines · Johannes Schindelin via GitGitGadget

From: Johannes Schindelin <[email protected]>

We have something much better now: --rebase-merges (which is a complete re-design --preserve-merges, with a lot of issues fixed such as the inability to reorder commits with --preserve-merges).

Signed-off-by Johannes Schindelin <[email protected]>

---
  Documentation/config/branch.txt |  6 +++---
  Documentation/config/pull.txt   |  6 +++---
  Documentation/git-rebase.txt    | 23 ++++++++++++-----------
  builtin/rebase.c                |  8 ++++++--
  git-rebase--preserve-merges.sh  |  2 ++
  5 files changed, 26 insertions(+), 19 deletions(-)

Documentation/config/branch.txt +0 -0

index 019d60ede2..8f4b3faadd 100644
@@ -85,9 +85,9 @@ When `merges`, pass the `--rebase-merges` option to 'git

rebase'
so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details).
+

Documentation/config/branch.txt +3 -3

-When preserve, also pass `--preserve-merges` along to 'git rebase'
-so that locally committed merge commits will not be flattened
-by running 'git pull'.
+When `preserve` (deprecated in favor of `merges`), also pass
+`--preserve-merges` along to 'git rebase' so that locally committed merge
+commits will not be flattened by running 'git pull'.
  +
  When the value is `interactive`, the rebase is run in interactive mode.
  +

Documentation/config/pull.txt +0 -0

index bb23a9947d..b87cab31b3 100644
@@ -18,9 +18,9 @@ When `merges`, pass the `--rebase-merges` option to 'git

rebase'
so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details).
+

Documentation/config/pull.txt +3 -3

-When preserve, also pass `--preserve-merges` along to 'git rebase'
-so that locally committed merge commits will not be flattened
-by running 'git pull'.
+When `preserve` (deprecated in favor of `merges`), also pass
+`--preserve-merges` along to 'git rebase' so that locally committed merge
+commits will not be flattened by running 'git pull'.
  +
  When the value is `interactive`, the rebase is run in interactive mode.
  +

Documentation/git-rebase.txt +0 -0

index 5629ba4c5d..89202dbb93 100644
@@ -415,9 +415,9 @@ i.e. commits that would be excluded by

gitlink:git-log[1]'s
the rebase-cousins mode is turned on, such commits are instead rebased onto <upstream> (or <onto>, if specified).
+

Documentation/git-rebase.txt +0 -2

-The `--rebase-merges` mode is similar in spirit to `--preserve-merges`, but
-in contrast to that option works well in interactive rebases: commits can

be

Documentation/git-rebase.txt +2 -1

-reordered, inserted and dropped at will.
+The `--rebase-merges` mode is similar in spirit to the deprecated
+`--preserve-merges`, but in contrast to that option works well in

interactive

Documentation/git-rebase.txt +1 -0

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

@@ -427,9 +427,10 @@ See also REBASING MERGES and INCOMPATIBLE OPTIONS

below.

-p::
--preserve-merges::

Documentation/git-rebase.txt +0 -2

-	Recreate merge commits instead of flattening the history by replaying
-	commits a merge commit introduces. Merge conflict resolutions or

manual

Documentation/git-rebase.txt +6 -6

-	amendments to merge commits are not preserved.
+	[DEPRECATED: use --rebase-merges instead] Recreate merge commits
+	instead of flattening the history by replaying commits a merge commit
+	introduces. Merge conflict resolutions or manual amendments to merge
+	commits are not preserved.
  +
  This uses the `--interactive` machinery internally, but combining it
  with the `--interactive` option explicitly is generally not a good

@@ -1020,11 +1021,11 @@ merge cmake
 
  BUGS
  ----
-The todo list presented by `--preserve-merges --interactive` does not
-represent the topology of the revision graph.  Editing commits and
-rewording their commit messages should work fine, but attempts to
-reorder commits tend to produce counterintuitive results. Use
-`--rebase-merges` in such scenarios instead.
+The todo list presented by the deprecated `--preserve-merges --interactive`
+does not represent the topology of the revision graph (use

--rebase-merges

Documentation/git-rebase.txt +2 -0

+instead).  Editing commits and rewording their commit messages should work
+fine, but attempts to reorder commits tend to produce counterintuitive

results.

Documentation/git-rebase.txt +1 -0

+Use `--rebase-merges` in such scenarios instead.
 
  For example, an attempt to rearrange
  ------------

builtin/rebase.c +1 -2

index 7c7bc13e91..c5f5edf321 100644
@@ -1092,8 +1092,8 @@ int cmd_rebase(int argc, const char **argv, const char
 *prefix)
     PARSE_OPT_NOARG | PARSE_OPT_NONEG,
     parse_opt_interactive },
  		OPT_SET_INT('p', "preserve-merges", &options.type,
-			    N_("try to recreate merges instead of ignoring "
-			       "them"), REBASE_PRESERVE_MERGES),
+			    N_("(DEPRECATED) try to recreate merges instead of

"

builtin/rebase.c +4 -0

+			       "ignoring them"), REBASE_PRESERVE_MERGES),
    OPT_BOOL(0, "rerere-autoupdate",
      &options.allow_rerere_autoupdate,
      N_("allow rerere to update index with resolved "

@@ -1204,6 +1204,10 @@ int cmd_rebase(int argc, const char **argv, const
 char *prefix)
    usage_with_options(builtin_rebase_usage,
         builtin_rebase_options);
  +	if (options.type == REBASE_PRESERVE_MERGES)
+		warning(_("--preserve-merges is deprecated in favor of "
+			  "--rebase-merges"));
+
   if (action != NO_ACTION && !in_progress)
   	die(_("No rebase in progress?"));
  	setenv(GIT_REFLOG_ACTION_ENVIRONMENT, "rebase", 0);

git-rebase--preserve-merges.sh +1 -0

index afbb65765d..eab2e40dc6 100644
@@ -105,6 +105,8 @@ warn () {
  	printf '%s\n' "$*" >&2
  }
 
+warn "git rebase --preserve-merges is deprecated. Use --rebase-merges

instead."
+
# Output the commit message for the specified commit.

  commit_message () {
   git cat-file commit "$1" | sed "1,/^$/d"

Quoted 4 lines · Johannes Schindelin via GitGitGadget

We have something much better now: --rebase-merges (which is a complete re-design --preserve-merges, with a lot of issues fixed such as the inability to reorder commits with --preserve-merges).

Documentation/git-rebase.txt See also REBASING MERGES and INCOMPATIBLE OPTIONS below. · line 428

Quoted 6 lines

Signed-off-by Johannes Schindelin <[email protected]>

---

Documentation/git-rebase.txt +1 -0

@@ -427,9 +427,10 @@ See also REBASING MERGES and INCOMPATIBLE OPTIONS below.
 --preserve-merges::
+       [DEPRECATED: use --rebase-merges instead] Recreate merge commits

s/--rebase-merges/&/

Quoted 4 lines

Documentation/git-rebase.txt +3 -0

+       instead of flattening the history by replaying commits a merge commit
+       introduces. Merge conflict resolutions or manual amendments to merge
+       commits are not preserved.

From: Johannes Schindelin <[email protected]>

We have something much better now: --rebase-merges (which is a complete re-design --preserve-merges, with a lot of issues fixed such as the inability to reorder commits with --preserve-merges).

Signed-off-by Johannes Schindelin <[email protected]>

---
 Documentation/config/branch.txt |  6 +++---
 Documentation/config/pull.txt   |  6 +++---
 Documentation/git-rebase.txt    | 23 ++++++++++++-----------
 builtin/rebase.c                |  8 ++++++--
 4 files changed, 24 insertions(+), 19 deletions(-)

Documentation/config/branch.txt +3 -3

index 019d60ede2..8f4b3faadd 100644
@@ -85,9 +85,9 @@ When `merges`, pass the `--rebase-merges` option to 'git rebase'
 so that the local merge commits are included in the rebase (see
 linkgit:git-rebase[1] for details).
 +
-When preserve, also pass `--preserve-merges` along to 'git rebase'
-so that locally committed merge commits will not be flattened
-by running 'git pull'.
+When `preserve` (deprecated in favor of `merges`), also pass
+`--preserve-merges` along to 'git rebase' so that locally committed merge
+commits will not be flattened by running 'git pull'.
 +
 When the value is `interactive`, the rebase is run in interactive mode.
 +

Documentation/config/pull.txt +3 -3

index bb23a9947d..b87cab31b3 100644
@@ -18,9 +18,9 @@ When `merges`, pass the `--rebase-merges` option to 'git rebase'
 so that the local merge commits are included in the rebase (see
 linkgit:git-rebase[1] for details).
 +
-When preserve, also pass `--preserve-merges` along to 'git rebase'
-so that locally committed merge commits will not be flattened
-by running 'git pull'.
+When `preserve` (deprecated in favor of `merges`), also pass
+`--preserve-merges` along to 'git rebase' so that locally committed merge
+commits will not be flattened by running 'git pull'.
 +
 When the value is `interactive`, the rebase is run in interactive mode.
 +

Documentation/git-rebase.txt +12 -11

index 6363d674b7..44e00329e1 100644
@@ -415,9 +415,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 `--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 the deprecated
+`--preserve-merges`, but in contrast to that option works well in interactive
+rebases: 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

@@ -427,9 +427,10 @@ See also REBASING MERGES and INCOMPATIBLE OPTIONS below.
 
 -p::
 --preserve-merges::
-	Recreate merge commits instead of flattening the history by replaying
-	commits a merge commit introduces. Merge conflict resolutions or manual
-	amendments to merge commits are not preserved.
+	[DEPRECATED: use `--rebase-merges` instead] Recreate merge commits
+	instead of flattening the history by replaying commits a merge commit
+	introduces. Merge conflict resolutions or manual amendments to merge
+	commits are not preserved.
 +
 This uses the `--interactive` machinery internally, but combining it
 with the `--interactive` option explicitly is generally not a good

@@ -1020,11 +1021,11 @@ merge cmake
 
 BUGS
 ----
-The todo list presented by `--preserve-merges --interactive` does not
-represent the topology of the revision graph.  Editing commits and
-rewording their commit messages should work fine, but attempts to
-reorder commits tend to produce counterintuitive results. Use
-`--rebase-merges` in such scenarios instead.
+The todo list presented by the deprecated `--preserve-merges --interactive`
+does not represent the topology of the revision graph (use `--rebase-merges`
+instead).  Editing commits and rewording their commit messages should work
+fine, but attempts to reorder commits tend to produce counterintuitive results.
+Use `--rebase-merges` in such scenarios instead.
 
 For example, an attempt to rearrange
 ------------

builtin/rebase.c +2 -2

index 52114cbf0d..21ac10f739 100644
@@ -1100,8 +1100,8 @@ int cmd_rebase(int argc, const char **argv, const char *prefix)
 			PARSE_OPT_NOARG | PARSE_OPT_NONEG,
 			parse_opt_interactive },
 		OPT_SET_INT('p', "preserve-merges", &options.type,
-			    N_("try to recreate merges instead of ignoring "
-			       "them"), REBASE_PRESERVE_MERGES),
+			    N_("(DEPRECATED) try to recreate merges instead of "
+			       "ignoring them"), REBASE_PRESERVE_MERGES),
 		OPT_BOOL(0, "rerere-autoupdate",
 			 &options.allow_rerere_autoupdate,
 			 N_("allow rerere to update index with resolved "

builtin/rebase.c int cmd_rebase(int argc, const char **argv, const char *prefix) · line 1221

Quoted 13 lines · Johannes Schindelin via GitGitGadget

From: Johannes Schindelin <[email protected]>

builtin/rebase.c +4 -0

@@ -1212,6 +1212,10 @@ int cmd_rebase(int argc, const char **argv, const char *prefix)
 		usage_with_options(builtin_rebase_usage,
 				   builtin_rebase_options);
 
+	if (options.type == REBASE_PRESERVE_MERGES)
+		warning(_("git rebase --preserve-merges is deprecated. "
+			  "Use --rebase-merges instead."));
+
 	if (action != NO_ACTION && !in_progress)
 		die(_("No rebase in progress?"));
 	setenv(GIT_REFLOG_ACTION_ENVIRONMENT, "rebase", 0);

An internal user reported the following "bug" they ran into:

1. They ran "git pull --rebase=preserve"
2. warning: git rebase --preserve-merges is deprecated. Use --rebase-merges instead.

This is very confusing, since the user issued "--rebase=preserve", *not* "--preserve-merges".

We could detect that we came from "git pull" and pass down the argv we used blah blah, but how about just describing things a bit more in the warning, e.g.:

warning: the "preserve" backend for 'git rebase' has been deprecated. You invoked git with "rebase --preserve-merges", either directly, or via "pull --rebase=preserve".

Use the new "rebase merges" backend of "git rebase" instead, invoked via "rebase --rebase-merges" or "pull --rebase=merges". Note that the new backend may yield different results, see the "git rebase" documentation for details.