SYNOPSIS
--------
[verse]
-'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]
+'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]
[<upstream> [<branch>]]
-'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]
+'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]
--root [<branch>]
-'git rebase' --continue | --skip | --abort | --quit | --edit-todo
+'git rebase' --continue | --skip | --abort | --quit | --edit-todo | --show-current-patch
DESCRIPTION
-----------
CONFIGURATION
-------------
-rebase.stat::
- Whether to show a diffstat of what changed upstream since the last
- rebase. False by default.
-
-rebase.autoSquash::
- If set to true enable `--autosquash` option by default.
-
-rebase.autoStash::
- If set to true enable `--autostash` option by default.
-
-rebase.missingCommitsCheck::
- If set to "warn", print warnings about removed commits in
- interactive mode. If set to "error", print the warnings and
- stop the rebase. If set to "ignore", no checking is
- done. "ignore" by default.
-
-rebase.instructionFormat::
- Custom commit list format to use during an `--interactive` rebase.
+include::rebase-config.txt[]
OPTIONS
-------
--keep-empty::
Keep the commits that do not change anything from its
parents in the result.
++
+See also INCOMPATIBLE OPTIONS below.
+
+--allow-empty-message::
+ By default, rebasing commits with an empty message will fail.
+ This option overrides that behavior, allowing commits with empty
+ messages to be rebased.
++
+See also INCOMPATIBLE OPTIONS below.
--skip::
Restart the rebasing process by skipping the current patch.
--edit-todo::
Edit the todo list during an interactive rebase.
+--show-current-patch::
+ Show the current patch in an interactive rebase or when rebase
+ is stopped because of conflicts. This is the equivalent of
+ `git show REBASE_HEAD`.
+
-m::
--merge::
Use merging strategies to rebase. When the recursive (default) merge
conflict happens, the side reported as 'ours' is the so-far rebased
series, starting with <upstream>, and 'theirs' is the working branch. In
other words, the sides are swapped.
++
+See also INCOMPATIBLE OPTIONS below.
-s <strategy>::
--strategy=<strategy>::
+
Because 'git rebase' replays each commit from the working branch
on top of the <upstream> branch using the given strategy, using
-the 'ours' strategy simply discards all patches from the <branch>,
+the 'ours' strategy simply empties all patches from the <branch>,
which makes little sense.
++
+See also INCOMPATIBLE OPTIONS below.
-X <strategy-option>::
--strategy-option=<strategy-option>::
This implies `--merge` and, if no strategy has been
specified, `-s recursive`. Note the reversal of 'ours' and
'theirs' as noted above for the `-m` option.
++
+See also INCOMPATIBLE OPTIONS below.
-S[<keyid>]::
--gpg-sign[=<keyid>]::
and after each change. When fewer lines of surrounding
context exist they all must match. By default no context is
ever ignored.
++
+See also INCOMPATIBLE OPTIONS below.
--f::
+--no-ff::
--force-rebase::
- Force a rebase even if the current branch is up to date and
- the command without `--force` would return without doing anything.
+-f::
+ Individually replay all rebased commits instead of fast-forwarding
+ over the unchanged ones. This ensures that the entire history of
+ the rebased branch is composed of new commits.
+
-You may find this (or --no-ff with an interactive rebase) helpful after
-reverting a topic branch merge, as this option recreates the topic branch with
-fresh commits so it can be remerged successfully without needing to "revert
-the reversion" (see the
-link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details).
+You may find this helpful after reverting a topic branch merge, as this option
+recreates the topic branch with fresh commits so it can be remerged
+successfully without needing to "revert the reversion" (see the
+link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for
+details).
--fork-point::
--no-fork-point::
--whitespace=<option>::
These flag are passed to the 'git apply' program
(see linkgit:git-apply[1]) that applies the patch.
- Incompatible with the --interactive option.
++
+See also INCOMPATIBLE OPTIONS below.
--committer-date-is-author-date::
--ignore-date::
These flags are passed to 'git am' to easily change the dates
of the rebased commits (see linkgit:git-am[1]).
- Incompatible with the --interactive option.
++
+See also INCOMPATIBLE OPTIONS below.
--signoff::
- This flag is passed to 'git am' to sign off all the rebased
- commits (see linkgit:git-am[1]). Incompatible with the
- --interactive option.
+ Add a Signed-off-by: trailer to all the rebased commits. Note
+ that if `--interactive` is given then only commits marked to be
+ picked, edited or reworded will have the trailer added.
++
+See also INCOMPATIBLE OPTIONS below.
-i::
--interactive::
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.
++
+See also INCOMPATIBLE OPTIONS below.
+
+-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 `<upstream>` 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 `<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.
++
+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 <strategy> [...]` commands.
++
+See also REBASING MERGES and INCOMPATIBLE OPTIONS below.
-p::
--preserve-merges::
This uses the `--interactive` machinery internally, but combining it
with the `--interactive` option explicitly is generally not a good
idea unless you know what you are doing (see BUGS below).
++
+See also INCOMPATIBLE OPTIONS below.
-x <cmd>::
--exec <cmd>::
+
This uses the `--interactive` machinery internally, but it can be run
without an explicit `--interactive`.
++
+See also INCOMPATIBLE OPTIONS below.
--root::
Rebase all commits reachable from <branch>, instead of
When used together with both --onto and --preserve-merges,
'all' root commits will be rewritten to have <newbase> as parent
instead.
++
+See also INCOMPATIBLE OPTIONS below.
--autosquash::
--no-autosquash::
too. The recommended way to create fixup/squash commits is by using
the `--fixup`/`--squash` options of linkgit:git-commit[1].
+
-This option is only valid when the `--interactive` option is used.
-+
If the `--autosquash` option is enabled by default using the
configuration variable `rebase.autoSquash`, this option can be
used to override and disable this setting.
++
+See also INCOMPATIBLE OPTIONS below.
--autostash::
--no-autostash::
with care: the final stash application after a successful
rebase might result in non-trivial conflicts.
---no-ff::
- With --interactive, cherry-pick all rebased commits instead of
- fast-forwarding over the unchanged ones. This ensures that the
- entire history of the rebased branch is composed of new commits.
-+
-Without --interactive, this is a synonym for --force-rebase.
-+
-You may find this helpful after reverting a topic branch merge, as this option
-recreates the topic branch with fresh commits so it can be remerged
-successfully without needing to "revert the reversion" (see the
-link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details).
+INCOMPATIBLE OPTIONS
+--------------------
+
+git-rebase has many flags that are incompatible with each other,
+predominantly due to the fact that it has three different underlying
+implementations:
+
+ * one based on linkgit:git-am[1] (the default)
+ * one based on git-merge-recursive (merge backend)
+ * one based on linkgit:git-cherry-pick[1] (interactive backend)
+
+Flags only understood by the am backend:
+
+ * --committer-date-is-author-date
+ * --ignore-date
+ * --whitespace
+ * --ignore-whitespace
+ * -C
+
+Flags understood by both merge and interactive backends:
+
+ * --merge
+ * --strategy
+ * --strategy-option
+ * --allow-empty-message
+
+Flags only understood by the interactive backend:
+
+ * --[no-]autosquash
+ * --rebase-merges
+ * --preserve-merges
+ * --interactive
+ * --exec
+ * --keep-empty
+ * --autosquash
+ * --edit-todo
+ * --root when used in combination with --onto
+
+Other incompatible flag pairs:
+
+ * --preserve-merges and --interactive
+ * --preserve-merges and --signoff
+ * --preserve-merges and --rebase-merges
+ * --rebase-merges and --strategy
+ * --rebase-merges and --strategy-option
+
+BEHAVIORAL DIFFERENCES
+-----------------------
+
+ * empty commits:
+
+ am-based rebase will drop any "empty" commits, whether the
+ commit started empty (had no changes relative to its parent to
+ start with) or ended empty (all changes were already applied
+ upstream in other commits).
+
+ merge-based rebase does the same.
+
+ interactive-based rebase will by default drop commits that
+ started empty and halt if it hits a commit that ended up empty.
+ The `--keep-empty` option exists for interactive rebases to allow
+ it to keep commits that started empty.
+
+ * directory rename detection:
+
+ merge-based and interactive-based rebases work fine with
+ directory rename detection. am-based rebases sometimes do not.
include::merge-strategies.txt[]
'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/<label>`) that will be deleted when the rebase
+finishes. That way, rebase operations in multiple worktrees linked to
+the same repository do not interfere with one another. If the `label`
+command fails, it is rescheduled immediately, with a helpful message how
+to proceed.
+
+The `reset` command resets the HEAD, index and worktree to the specified
+revision. It is similar to an `exec git reset --hard <label>`, but
+refuses to overwrite untracked files. If the `reset` command fails, it is
+rescheduled immediately, with a helpful message how to edit the todo list
+(this typically happens when a `reset` command was inserted into the todo
+list manually and contains a typo).
+
+The `merge` command will merge the specified revision(s) into whatever
+is HEAD at that time. With `-C <original-commit>`, the commit message of
+the specified merge commit will be used. When the `-C` is changed to
+a lower-case `-c`, the message will be opened in an editor after a
+successful merge so that the user can edit the message.
+
+If a `merge` command fails for any reason other than merge conflicts (i.e.
+when the merge operation did not even start), it is rescheduled immediately.
+
+At this time, the `merge` command will *always* use the `recursive`
+merge strategy for regular merges, and `octopus` for octopus merges,
+strategy, with no way to choose a different one. To work around
+this, an `exec` command can be used to call `git merge` explicitly,
+using the fact that the labels are worktree-local refs (the ref
+`refs/rewritten/onto` would correspond to the label `onto`, for example).
+
+Note: the first command (`label onto`) labels the revision onto which
+the commits are rebased; The name `onto` is just a convention, as a nod
+to the `--onto` option.
+
+It is also possible to introduce completely new merge commits from scratch
+by adding a command of the form `merge <merge-head>`. This form will
+generate a tentative commit message and always open an editor to let the
+user edit it. This can be useful e.g. when a topic branch turns out to
+address more than a single concern and wants to be split into two or
+even more topic branches. Consider this todo list:
+
+------------
+pick 192837 Switch from GNU Makefiles to CMake
+pick 5a6c7e Document the switch to CMake
+pick 918273 Fix detection of OpenSSL in CMake
+pick afbecd http: add support for TLS v1.3
+pick fdbaec Fix detection of cURL in CMake on Windows
+------------
+
+The one commit in this list that is not related to CMake may very well
+have been motivated by working on fixing all those bugs introduced by
+switching to CMake, but it addresses a different concern. To split this
+branch into two topic branches, the todo list could be edited like this:
+
+------------
+label onto
+
+pick afbecd http: add support for TLS v1.3
+label tlsv1.3
+
+reset onto
+pick 192837 Switch from GNU Makefiles to CMake
+pick 918273 Fix detection of OpenSSL in CMake
+pick fdbaec Fix detection of cURL in CMake on Windows
+pick 5a6c7e Document the switch to CMake
+label cmake
+
+reset onto
+merge tlsv1.3
+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.
+reorder commits tend to produce counterintuitive results. Use
+`--rebase-merges` in such scenarios instead.
For example, an attempt to rearrange
------------