diff --git a/Documentation/config.txt b/Documentation/config.txt index 4874364f17..84e2891aed 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1068,6 +1068,10 @@ branch..rebase:: "git pull" is run. See "pull.rebase" for doing this in a non branch-specific manner. + +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'. @@ -2669,6 +2673,10 @@ pull.rebase:: pull" is run. See "branch..rebase" for setting this on a per-branch basis. + +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'. diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index ce05b7a5b1..4e0ad6fd8e 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -101,13 +101,17 @@ Options related to merging include::merge-options.txt[] -r:: ---rebase[=false|true|preserve|interactive]:: +--rebase[=false|true|merges|preserve|interactive]:: When true, rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to the upstream branch and the upstream branch was rebased since last fetched, the rebase uses that information to avoid rebasing non-local changes. + +When set to `merges`, rebase using `git rebase --rebase-merges` so that +the local merge commits are included in the rebase (see +linkgit:git-rebase[1] for details). ++ When set to preserve, rebase with the `--preserve-merges` option passed to `git rebase` so that locally created merge commits will not be flattened. + diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index dd852068b1..bd5ecff980 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -379,6 +379,33 @@ The commit list format can be changed by setting the configuration option rebase.instructionFormat. A customized instruction format will automatically have the long commit hash prepended to the format. +-r:: +--rebase-merges[=(rebase-cousins|no-rebase-cousins)]:: + By default, a rebase will simply drop merge commits from the todo + list, and put the rebased commits into a single, linear branch. + With `--rebase-merges`, the rebase will instead try to preserve + the branching structure within the commits that are to be rebased, + by recreating the merge commits. Any resolved merge conflicts or + manual amendments in these merge commits will have to be + resolved/re-applied manually. ++ +By default, or when `no-rebase-cousins` was specified, commits which do not +have `` as direct ancestor will keep their original branch point, +i.e. commits that would be excluded by gitlink:git-log[1]'s +`--ancestry-path` option will keep their original ancestry by default. If +the `rebase-cousins` mode is turned on, such commits are instead rebased +onto `` (or ``, 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. ++ +It is currently only possible to recreate the merge commits using the +`recursive` merge strategy; Different merge strategies can be used only via +explicit `exec git merge -s [...]` commands. ++ +See also REBASING MERGES below. + -p:: --preserve-merges:: Recreate merge commits instead of flattening the history by replaying @@ -776,12 +803,146 @@ The ripple effect of a "hard case" recovery is especially bad: 'everyone' downstream from 'topic' will now have to perform a "hard case" recovery too! +REBASING MERGES +----------------- + +The interactive rebase command was originally designed to handle +individual patch series. As such, it makes sense to exclude merge +commits from the todo list, as the developer may have merged the +then-current `master` while working on the branch, only to rebase +all the commits onto `master` eventually (skipping the merge +commits). + +However, there are legitimate reasons why a developer may want to +recreate merge commits: to keep the branch structure (or "commit +topology") when working on multiple, inter-related branches. + +In the following example, the developer works on a topic branch that +refactors the way buttons are defined, and on another topic branch +that uses that refactoring to implement a "Report a bug" button. The +output of `git log --graph --format=%s -5` may look like this: + +------------ +* Merge branch 'report-a-bug' +|\ +| * Add the feedback button +* | Merge branch 'refactor-button' +|\ \ +| |/ +| * Use the Button class for all buttons +| * Extract a generic Button class from the DownloadButton one +------------ + +The developer might want to rebase those commits to a newer `master` +while keeping the branch topology, for example when the first topic +branch is expected to be integrated into `master` much earlier than the +second one, say, to resolve merge conflicts with changes to the +DownloadButton class that made it into `master`. + +This rebase can be performed using the `--rebase-merges` option. +It will generate a todo list looking like this: + +------------ +label onto + +# Branch: refactor-button +reset onto +pick 123456 Extract a generic Button class from the DownloadButton one +pick 654321 Use the Button class for all buttons +label refactor-button + +# Branch: report-a-bug +reset refactor-button # Use the Button class for all buttons +pick abcdef Add the feedback button +label report-a-bug + +reset onto +merge -C a1b2c3 refactor-button # Merge 'refactor-button' +merge -C 6f5e4d report-a-bug # Merge 'report-a-bug' +------------ + +In contrast to a regular interactive rebase, there are `label`, `reset` +and `merge` commands in addition to `pick` ones. + +The `label` command associates a label with the current HEAD when that +command is executed. These labels are created as worktree-local refs +(`refs/rewritten/