1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.4.5" />
7 <title>git-rebase(
1)
</title>
8 <style type=
"text/css">
10 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
12 border: 1px solid red;
17 margin: 1em 5% 1em 5%;
22 text-decoration: underline
;
42 h1
, h2
, h3
, h4
, h5
, h6
{
44 font-family: sans-serif
;
51 border-bottom: 2px solid silver
;
69 border: 1px solid silver
;
88 font-family: sans-serif
;
94 span#revnumber
, span#revdate
, span#revremark
{
95 font-family: sans-serif
;
99 font-family: sans-serif
;
101 border-top: 2px solid silver
;
107 padding-bottom: 0.5em;
111 padding-bottom: 0.5em;
116 margin-bottom: 1.5em;
118 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
119 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
120 div
.admonitionblock
{
122 margin-bottom: 1.5em;
124 div
.admonitionblock
{
126 margin-bottom: 2.5em;
129 div
.content
{ /* Block element content. */
133 /* Block element titles. */
134 div
.title
, caption
.title
{
136 font-family: sans-serif
;
140 margin-bottom: 0.5em;
146 td div
.title:first-child
{
149 div
.content div
.title:first-child
{
152 div
.content
+ div
.title
{
156 div
.sidebarblock
> div
.content
{
158 border: 1px solid silver
;
162 div
.listingblock
> div
.content
{
163 border: 1px solid silver
;
172 div
.quoteblock
> div
.attribution
{
181 div
.verseblock
> div
.content
{
184 div
.verseblock
> div
.attribution
{
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div
.verseblock
+ div
.attribution
{
193 div
.admonitionblock
.icon
{
197 text-decoration: underline
;
199 padding-right: 0.5em;
201 div
.admonitionblock td
.content
{
203 border-left: 2px solid silver
;
206 div
.exampleblock
> div
.content
{
207 border-left: 2px solid silver
;
211 div
.imageblock div
.content
{ padding-left: 0; }
212 span
.image img
{ border-style: none
; }
213 a
.image:visited
{ color: white
; }
217 margin-bottom: 0.8em;
230 list-style-position: outside
;
233 list-style-type: decimal
;
236 list-style-type: lower-alpha
;
239 list-style-type: upper-alpha
;
242 list-style-type: lower-roman
;
245 list-style-type: upper-roman
;
248 div
.compact ul
, div
.compact ol
,
249 div
.compact p
, div
.compact p
,
250 div
.compact div
, div
.compact div
{
252 margin-bottom: 0.1em;
255 div
.tableblock
> table
{
256 border: 3px solid
#527bbd;
259 font-family: sans-serif
;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div
.tableblock
> table
[frame
="void"] {
275 div
.tableblock
> table
[frame
="hsides"] {
276 border-left-style: none
;
277 border-right-style: none
;
279 div
.tableblock
> table
[frame
="vsides"] {
280 border-top-style: none
;
281 border-bottom-style: none
;
287 margin-bottom: 0.8em;
290 padding-bottom: 15px;
292 dt
.hdlist1
.strong
, td
.hdlist1
.strong
{
298 padding-right: 0.8em;
304 div
.hdlist
.compact tr
{
314 div#footer-badges
{ display: none
; }
319 font-family: sans-serif
;
323 margin-bottom: 0.1em;
326 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
342 /* Overrides for manpage documents */
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver
;
347 border-bottom: 2px solid silver
;
357 div#toc
{ display: none
; }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
362 div
.sidebar-content
{
364 border: 1px solid silver
;
367 div
.sidebar-title
, div
.image-title
{
369 font-family: sans-serif
;
372 margin-bottom: 0.5em;
375 div
.listingblock div
.content
{
376 border: 1px solid silver
;
381 div
.quoteblock-attribution
{
386 div
.verseblock-content
{
389 div
.verseblock-attribution
{
394 div
.exampleblock-content
{
395 border-left: 2px solid silver
;
399 /* IE6 sets dynamically generated links as visited. */
400 div#toc
a:visited
{ color: blue
; }
406 git-rebase(
1) Manual Page
409 <div class=
"sectionbody">
411 Forward-port local commits to the updated upstream head
415 <h2 id=
"_synopsis">SYNOPSIS
</h2>
416 <div class=
"sectionbody">
417 <div class=
"verseblock">
418 <div class=
"verseblock-content"><em>git rebase
</em> [-i | --interactive] [options] [--onto
<newbase
>]
419 [
<upstream
>] [
<branch
>]
420 <em>git rebase
</em> [-i | --interactive] [options] --onto
<newbase
>
421 --root [
<branch
>]
</div>
422 <div class=
"verseblock-attribution">
424 <div class=
"paragraph"><p><em>git rebase
</em> --continue | --skip | --abort
</p></div>
426 <h2 id=
"_description">DESCRIPTION
</h2>
427 <div class=
"sectionbody">
428 <div class=
"paragraph"><p>If
<branch
> is specified,
<em>git rebase
</em> will perform an automatic
429 <tt>git checkout
<branch
></tt> before doing anything else. Otherwise
430 it remains on the current branch.
</p></div>
431 <div class=
"paragraph"><p>If
<upstream
> is not specified, the upstream configured in
432 branch.
<name
>.remote and branch.
<name
>.merge options will be used; see
433 <a href=
"git-config.html">git-config(
1)
</a> for details. If you are currently not on any
434 branch or if the current branch does not have a configured upstream,
435 the rebase will abort.
</p></div>
436 <div class=
"paragraph"><p>All changes made by commits in the current branch but that are not
437 in
<upstream
> are saved to a temporary area. This is the same set
438 of commits that would be shown by
<tt>git log
<upstream
>..HEAD
</tt> (or
439 <tt>git log HEAD
</tt>, if --root is specified).
</p></div>
440 <div class=
"paragraph"><p>The current branch is reset to
<upstream
>, or
<newbase
> if the
441 --onto option was supplied. This has the exact same effect as
442 <tt>git reset --hard
<upstream
></tt> (or
<newbase
>). ORIG_HEAD is set
443 to point at the tip of the branch before the reset.
</p></div>
444 <div class=
"paragraph"><p>The commits that were previously saved into the temporary area are
445 then reapplied to the current branch, one by one, in order. Note that
446 any commits in HEAD which introduce the same textual changes as a commit
447 in HEAD..
<upstream
> are omitted (i.e., a patch already accepted upstream
448 with a different commit message or timestamp will be skipped).
</p></div>
449 <div class=
"paragraph"><p>It is possible that a merge failure will prevent this process from being
450 completely automatic. You will have to resolve any such merge failure
451 and run
<tt>git rebase --continue
</tt>. Another option is to bypass the commit
452 that caused the merge failure with
<tt>git rebase --skip
</tt>. To restore the
453 original
<branch
> and remove the .git/rebase-apply working files, use the
454 command
<tt>git rebase --abort
</tt> instead.
</p></div>
455 <div class=
"paragraph"><p>Assume the following history exists and the current branch is
"topic":
</p></div>
456 <div class=
"listingblock">
457 <div class=
"content">
458 <pre><tt> A---B---C topic
460 D---E---F---G master
</tt></pre>
462 <div class=
"paragraph"><p>From this point, the result of either of the following commands:
</p></div>
463 <div class=
"literalblock">
464 <div class=
"content">
465 <pre><tt>git rebase master
466 git rebase master topic
</tt></pre>
468 <div class=
"paragraph"><p>would be:
</p></div>
469 <div class=
"listingblock">
470 <div class=
"content">
471 <pre><tt> A'--B'--C' topic
473 D---E---F---G master
</tt></pre>
475 <div class=
"paragraph"><p><strong>NOTE:
</strong> The latter form is just a short-hand of
<tt>git checkout topic
</tt>
476 followed by
<tt>git rebase master
</tt>. When rebase exits
<tt>topic
</tt> will
477 remain the checked-out branch.
</p></div>
478 <div class=
"paragraph"><p>If the upstream branch already contains a change you have made (e.g.,
479 because you mailed a patch which was applied upstream), then that commit
480 will be skipped. For example, running
‘git rebase master` on the
481 following history (in which A
’ and A introduce the same set of changes,
482 but have different committer information):
</p></div>
483 <div class=
"listingblock">
484 <div class=
"content">
485 <pre><tt> A---B---C topic
487 D---E---A'---F master
</tt></pre>
489 <div class=
"paragraph"><p>will result in:
</p></div>
490 <div class=
"listingblock">
491 <div class=
"content">
492 <pre><tt> B'---C' topic
494 D---E---A'---F master
</tt></pre>
496 <div class=
"paragraph"><p>Here is how you would transplant a topic branch based on one
497 branch to another, to pretend that you forked the topic branch
498 from the latter branch, using
<tt>rebase --onto
</tt>.
</p></div>
499 <div class=
"paragraph"><p>First let
’s assume your
<em>topic
</em> is based on branch
<em>next
</em>.
500 For example, a feature developed in
<em>topic
</em> depends on some
501 functionality which is found in
<em>next
</em>.
</p></div>
502 <div class=
"listingblock">
503 <div class=
"content">
504 <pre><tt> o---o---o---o---o master
506 o---o---o---o---o next
508 o---o---o topic
</tt></pre>
510 <div class=
"paragraph"><p>We want to make
<em>topic
</em> forked from branch
<em>master
</em>; for example,
511 because the functionality on which
<em>topic
</em> depends was merged into the
512 more stable
<em>master
</em> branch. We want our tree to look like this:
</p></div>
513 <div class=
"listingblock">
514 <div class=
"content">
515 <pre><tt> o---o---o---o---o master
519 o---o---o---o---o next
</tt></pre>
521 <div class=
"paragraph"><p>We can get this using the following command:
</p></div>
522 <div class=
"literalblock">
523 <div class=
"content">
524 <pre><tt>git rebase --onto master next topic
</tt></pre>
526 <div class=
"paragraph"><p>Another example of --onto option is to rebase part of a
527 branch. If we have the following situation:
</p></div>
528 <div class=
"listingblock">
529 <div class=
"content">
530 <pre><tt> H---I---J topicB
534 A---B---C---D master
</tt></pre>
536 <div class=
"paragraph"><p>then the command
</p></div>
537 <div class=
"literalblock">
538 <div class=
"content">
539 <pre><tt>git rebase --onto master topicA topicB
</tt></pre>
541 <div class=
"paragraph"><p>would result in:
</p></div>
542 <div class=
"listingblock">
543 <div class=
"content">
544 <pre><tt> H'--I'--J' topicB
548 A---B---C---D master
</tt></pre>
550 <div class=
"paragraph"><p>This is useful when topicB does not depend on topicA.
</p></div>
551 <div class=
"paragraph"><p>A range of commits could also be removed with rebase. If we have
552 the following situation:
</p></div>
553 <div class=
"listingblock">
554 <div class=
"content">
555 <pre><tt> E---F---G---H---I---J topicA
</tt></pre>
557 <div class=
"paragraph"><p>then the command
</p></div>
558 <div class=
"literalblock">
559 <div class=
"content">
560 <pre><tt>git rebase --onto topicA~
5 topicA~
3 topicA
</tt></pre>
562 <div class=
"paragraph"><p>would result in the removal of commits F and G:
</p></div>
563 <div class=
"listingblock">
564 <div class=
"content">
565 <pre><tt> E---H'---I'---J' topicA
</tt></pre>
567 <div class=
"paragraph"><p>This is useful if F and G were flawed in some way, or should not be
568 part of topicA. Note that the argument to --onto and the
<upstream
>
569 parameter can be any valid commit-ish.
</p></div>
570 <div class=
"paragraph"><p>In case of conflict,
<em>git rebase
</em> will stop at the first problematic commit
571 and leave conflict markers in the tree. You can use
<em>git diff
</em> to locate
572 the markers (
<<<<<<) and make edits to resolve the conflict. For each
573 file you edit, you need to tell git that the conflict has been resolved,
574 typically this would be done with
</p></div>
575 <div class=
"literalblock">
576 <div class=
"content">
577 <pre><tt>git add
<filename
></tt></pre>
579 <div class=
"paragraph"><p>After resolving the conflict manually and updating the index with the
580 desired resolution, you can continue the rebasing process with
</p></div>
581 <div class=
"literalblock">
582 <div class=
"content">
583 <pre><tt>git rebase --continue
</tt></pre>
585 <div class=
"paragraph"><p>Alternatively, you can undo the
<em>git rebase
</em> with
</p></div>
586 <div class=
"literalblock">
587 <div class=
"content">
588 <pre><tt>git rebase --abort
</tt></pre>
591 <h2 id=
"_configuration">CONFIGURATION
</h2>
592 <div class=
"sectionbody">
593 <div class=
"dlist"><dl>
599 Whether to show a diffstat of what changed upstream since the last
600 rebase. False by default.
608 If set to true enable
<em>--autosquash
</em> option by default.
613 <h2 id=
"_options">OPTIONS
</h2>
614 <div class=
"sectionbody">
615 <div class=
"dlist"><dl>
621 Starting point at which to create the new commits. If the
622 --onto option is not specified, the starting point is
623 <upstream
>. May be any valid commit, and not just an
624 existing branch name.
626 <div class=
"paragraph"><p>As a special case, you may use
"A...B" as a shortcut for the
627 merge base of A and B if there is exactly one merge base. You can
628 leave out at most one of A and B, in which case it defaults to HEAD.
</p></div>
635 Upstream branch to compare against. May be any valid commit,
636 not just an existing branch name. Defaults to the configured
637 upstream for the current branch.
645 Working branch; defaults to HEAD.
653 Restart the rebasing process after having resolved a merge conflict.
661 Restore the original branch and abort the rebase operation.
669 Restart the rebasing process by skipping the current patch.
680 Use merging strategies to rebase. When the recursive (default) merge
681 strategy is used, this allows rebase to be aware of renames on the
684 <div class=
"paragraph"><p>Note that a rebase merge works by replaying each commit from the working
685 branch on top of the
<upstream
> branch. Because of this, when a merge
686 conflict happens, the side reported as
<em>ours
</em> is the so-far rebased
687 series, starting with
<upstream
>, and
<em>theirs
</em> is the working branch. In
688 other words, the sides are swapped.
</p></div>
694 --strategy=
<strategy
>
698 Use the given merge strategy.
699 If there is no
<tt>-s
</tt> option
<em>git merge-recursive
</em> is used
700 instead. This implies --merge.
702 <div class=
"paragraph"><p>Because
<em>git rebase
</em> replays each commit from the working branch
703 on top of the
<upstream
> branch using the given strategy, using
704 the
<em>ours
</em> strategy simply discards all patches from the
<branch
>,
705 which makes little sense.
</p></div>
708 -X
<strategy-option
>
711 --strategy-option=
<strategy-option
>
715 Pass the
<strategy-option
> through to the merge strategy.
716 This implies
<tt>--merge
</tt> and, if no strategy has been
717 specified,
<tt>-s recursive
</tt>. Note the reversal of
<em>ours
</em> and
718 <em>theirs
</em> as noted in above for the
<tt>-m
</tt> option.
729 Be quiet. Implies --no-stat.
740 Be verbose. Implies --stat.
748 Show a diffstat of what changed upstream since the last rebase. The
749 diffstat is also controlled by the configuration option rebase.stat.
760 Do not show a diffstat as part of the rebase process.
768 This option bypasses the pre-rebase hook. See also
<a href=
"githooks.html">githooks(
5)
</a>.
776 Allows the pre-rebase hook to run, which is the default. This option can
777 be used to override --no-verify. See also
<a href=
"githooks.html">githooks(
5)
</a>.
785 Ensure at least
<n
> lines of surrounding context match before
786 and after each change. When fewer lines of surrounding
787 context exist they all must match. By default no context is
799 Force the rebase even if the current branch is a descendant
800 of the commit you are rebasing onto. Normally non-interactive rebase will
801 exit with the message
"Current branch is up to date" in such a
803 Incompatible with the --interactive option.
805 <div class=
"paragraph"><p>You may find this (or --no-ff with an interactive rebase) helpful after
806 reverting a topic branch merge, as this option recreates the topic branch with
807 fresh commits so it can be remerged successfully without needing to
"revert
808 the reversion" (see the
809 <a href=
"howto/revert-a-faulty-merge.txt">revert-a-faulty-merge How-To
</a> for details).
</p></div>
815 --whitespace=
<option
>
819 These flag are passed to the
<em>git apply
</em> program
820 (see
<a href=
"git-apply.html">git-apply(
1)
</a>) that applies the patch.
821 Incompatible with the --interactive option.
825 --committer-date-is-author-date
832 These flags are passed to
<em>git am
</em> to easily change the dates
833 of the rebased commits (see
<a href=
"git-am.html">git-am(
1)
</a>).
834 Incompatible with the --interactive option.
845 Make a list of the commits which are about to be rebased. Let the
846 user edit that list before rebasing. This mode can also be used to
847 split commits (see SPLITTING COMMITS below).
858 Instead of ignoring merges, try to recreate them.
860 <div class=
"paragraph"><p>This uses the
<tt>--interactive
</tt> machinery internally, but combining it
861 with the
<tt>--interactive
</tt> option explicitly is generally not a good
862 idea unless you know what you are doing (see BUGS below).
</p></div>
869 Rebase all commits reachable from
<branch
>, instead of
870 limiting them with an
<upstream
>. This allows you to rebase
871 the root commit(s) on a branch. Must be used with --onto, and
872 will skip changes already contained in
<newbase
> (instead of
873 <upstream
>). When used together with --preserve-merges,
<em>all
</em>
874 root commits will be rewritten to have
<newbase
> as parent
886 When the commit log message begins with
"squash! …" (or
887 "fixup! …"), and there is a commit whose title begins with
888 the same
…, automatically modify the todo list of rebase -i
889 so that the commit marked for squashing comes right after the
890 commit to be modified, and change the action of the moved
891 commit from
<tt>pick
</tt> to
<tt>squash
</tt> (or
<tt>fixup
</tt>).
893 <div class=
"paragraph"><p>This option is only valid when the
<em>--interactive
</em> option is used.
</p></div>
894 <div class=
"paragraph"><p>If the
<em>--autosquash
</em> option is enabled by default using the
895 configuration variable
<tt>rebase.autosquash
</tt>, this option can be
896 used to override and disable this setting.
</p></div>
903 With --interactive, cherry-pick all rebased commits instead of
904 fast-forwarding over the unchanged ones. This ensures that the
905 entire history of the rebased branch is composed of new commits.
907 <div class=
"paragraph"><p>Without --interactive, this is a synonym for --force-rebase.
</p></div>
908 <div class=
"paragraph"><p>You may find this helpful after reverting a topic branch merge, as this option
909 recreates the topic branch with fresh commits so it can be remerged
910 successfully without needing to
"revert the reversion" (see the
911 <a href=
"howto/revert-a-faulty-merge.txt">revert-a-faulty-merge How-To
</a> for details).
</p></div>
915 <h2 id=
"_merge_strategies">MERGE STRATEGIES
</h2>
916 <div class=
"sectionbody">
917 <div class=
"paragraph"><p>The merge mechanism (
<em>git-merge
</em> and
<em>git-pull
</em> commands) allows the
918 backend
<em>merge strategies
</em> to be chosen with
<tt>-s
</tt> option. Some strategies
919 can also take their own options, which can be passed by giving
<tt>-X
<option
></tt>
920 arguments to
<em>git-merge
</em> and/or
<em>git-pull
</em>.
</p></div>
921 <div class=
"dlist"><dl>
927 This can only resolve two heads (i.e. the current branch
928 and another branch you pulled from) using a
3-way merge
929 algorithm. It tries to carefully detect criss-cross
930 merge ambiguities and is considered generally safe and
939 This can only resolve two heads using a
3-way merge
940 algorithm. When there is more than one common
941 ancestor that can be used for
3-way merge, it creates a
942 merged tree of the common ancestors and uses that as
943 the reference tree for the
3-way merge. This has been
944 reported to result in fewer merge conflicts without
945 causing mis-merges by tests done on actual merge commits
946 taken from Linux
2.6 kernel development history.
947 Additionally this can detect and handle merges involving
948 renames. This is the default merge strategy when
949 pulling or merging one branch.
951 <div class=
"paragraph"><p>The
<em>recursive
</em> strategy can take the following options:
</p></div>
952 <div class=
"dlist"><dl>
958 This option forces conflicting hunks to be auto-resolved cleanly by
959 favoring
<em>our
</em> version. Changes from the other tree that do not
960 conflict with our side are reflected to the merge result.
962 <div class=
"paragraph"><p>This should not be confused with the
<em>ours
</em> merge strategy, which does not
963 even look at what the other tree contains at all. It discards everything
964 the other tree did, declaring
<em>our
</em> history contains all that happened in it.
</p></div>
971 This is opposite of
<em>ours
</em>.
979 With this option,
<em>merge-recursive
</em> spends a little extra time
980 to avoid mismerges that sometimes occur due to unimportant
981 matching lines (e.g., braces from distinct functions). Use
982 this when the branches to be merged have diverged wildly.
983 See also
<a href=
"git-diff.html">git-diff(
1)
</a> <tt>--patience
</tt>.
997 Treats lines with the indicated type of whitespace change as
998 unchanged for the sake of a three-way merge. Whitespace
999 changes mixed with other changes to a line are not ignored.
1000 See also
<a href=
"git-diff.html">git-diff(
1)
</a> <tt>-b
</tt>,
<tt>-w
</tt>, and
1001 <tt>--ignore-space-at-eol
</tt>.
1003 <div class=
"ulist"><ul>
1006 If
<em>their
</em> version only introduces whitespace changes to a line,
1007 <em>our
</em> version is used;
1012 If
<em>our
</em> version introduces whitespace changes but
<em>their
</em>
1013 version includes a substantial change,
<em>their
</em> version is used;
1018 Otherwise, the merge proceeds in the usual way.
1023 <dt class=
"hdlist1">
1028 This runs a virtual check-out and check-in of all three stages
1029 of a file when resolving a three-way merge. This option is
1030 meant to be used when merging branches with different clean
1031 filters or end-of-line normalization rules. See
"Merging
1032 branches with differing checkin/checkout attributes" in
1033 <a href=
"gitattributes.html">gitattributes(
5)
</a> for details.
1036 <dt class=
"hdlist1">
1041 Disables the
<tt>renormalize
</tt> option. This overrides the
1042 <tt>merge.renormalize
</tt> configuration variable.
1045 <dt class=
"hdlist1">
1046 rename-threshold=
<n
>
1050 Controls the similarity threshold used for rename detection.
1051 See also
<a href=
"git-diff.html">git-diff(
1)
</a> <tt>-M
</tt>.
1054 <dt class=
"hdlist1">
1055 subtree[=
<path
>]
1059 This option is a more advanced form of
<em>subtree
</em> strategy, where
1060 the strategy makes a guess on how two trees must be shifted to
1061 match with each other when merging. Instead, the specified path
1062 is prefixed (or stripped from the beginning) to make the shape of
1068 <dt class=
"hdlist1">
1073 This resolves cases with more than two heads, but refuses to do
1074 a complex merge that needs manual resolution. It is
1075 primarily meant to be used for bundling topic branch
1076 heads together. This is the default merge strategy when
1077 pulling or merging more than one branch.
1080 <dt class=
"hdlist1">
1085 This resolves any number of heads, but the resulting tree of the
1086 merge is always that of the current branch head, effectively
1087 ignoring all changes from all other branches. It is meant to
1088 be used to supersede old development history of side
1089 branches. Note that this is different from the -Xours option to
1090 the
<em>recursive
</em> merge strategy.
1093 <dt class=
"hdlist1">
1098 This is a modified recursive strategy. When merging trees A and
1099 B, if B corresponds to a subtree of A, B is first adjusted to
1100 match the tree structure of A, instead of reading the trees at
1101 the same level. This adjustment is also done to the common
1107 <h2 id=
"_notes">NOTES
</h2>
1108 <div class=
"sectionbody">
1109 <div class=
"paragraph"><p>You should understand the implications of using
<em>git rebase
</em> on a
1110 repository that you share. See also RECOVERING FROM UPSTREAM REBASE
1112 <div class=
"paragraph"><p>When the git-rebase command is run, it will first execute a
"pre-rebase"
1113 hook if one exists. You can use this hook to do sanity checks and
1114 reject the rebase if it isn
’t appropriate. Please see the template
1115 pre-rebase hook script for an example.
</p></div>
1116 <div class=
"paragraph"><p>Upon completion,
<branch
> will be the current branch.
</p></div>
1118 <h2 id=
"_interactive_mode">INTERACTIVE MODE
</h2>
1119 <div class=
"sectionbody">
1120 <div class=
"paragraph"><p>Rebasing interactively means that you have a chance to edit the commits
1121 which are rebased. You can reorder the commits, and you can
1122 remove them (weeding out bad or otherwise unwanted patches).
</p></div>
1123 <div class=
"paragraph"><p>The interactive mode is meant for this type of workflow:
</p></div>
1124 <div class=
"olist arabic"><ol class=
"arabic">
1127 have a wonderful idea
1137 prepare a series for submission
1146 <div class=
"paragraph"><p>where point
2. consists of several instances of
</p></div>
1147 <div class=
"olist loweralpha"><ol class=
"loweralpha">
1152 <div class=
"olist arabic"><ol class=
"arabic">
1155 finish something worthy of a commit
1169 <div class=
"olist arabic"><ol class=
"arabic">
1172 realize that something does not work
1188 <div class=
"paragraph"><p>Sometimes the thing fixed in b
.2. cannot be amended to the not-quite
1189 perfect commit it fixes, because that commit is buried deeply in a
1190 patch series. That is exactly what interactive rebase is for: use it
1191 after plenty of
"a"s and
"b"s, by rearranging and editing
1192 commits, and squashing multiple commits into one.
</p></div>
1193 <div class=
"paragraph"><p>Start it with the last commit you want to retain as-is:
</p></div>
1194 <div class=
"literalblock">
1195 <div class=
"content">
1196 <pre><tt>git rebase -i
<after-this-commit
></tt></pre>
1198 <div class=
"paragraph"><p>An editor will be fired up with all the commits in your current branch
1199 (ignoring merge commits), which come after the given commit. You can
1200 reorder the commits in this list to your heart
’s content, and you can
1201 remove them. The list looks more or less like this:
</p></div>
1202 <div class=
"listingblock">
1203 <div class=
"content">
1204 <pre><tt>pick deadbee The oneline of this commit
1205 pick fa1afe1 The oneline of the next commit
1208 <div class=
"paragraph"><p>The oneline descriptions are purely for your pleasure;
<em>git rebase
</em> will
1209 not look at them but at the commit names (
"deadbee" and
"fa1afe1" in this
1210 example), so do not delete or edit the names.
</p></div>
1211 <div class=
"paragraph"><p>By replacing the command
"pick" with the command
"edit", you can tell
1212 <em>git rebase
</em> to stop after applying that commit, so that you can edit
1213 the files and/or the commit message, amend the commit, and continue
1215 <div class=
"paragraph"><p>If you just want to edit the commit message for a commit, replace the
1216 command
"pick" with the command
"reword".
</p></div>
1217 <div class=
"paragraph"><p>If you want to fold two or more commits into one, replace the command
1218 "pick" for the second and subsequent commits with
"squash" or
"fixup".
1219 If the commits had different authors, the folded commit will be
1220 attributed to the author of the first commit. The suggested commit
1221 message for the folded commit is the concatenation of the commit
1222 messages of the first commit and of those with the
"squash" command,
1223 but omits the commit messages of commits with the
"fixup" command.
</p></div>
1224 <div class=
"paragraph"><p><em>git rebase
</em> will stop when
"pick" has been replaced with
"edit" or
1225 when a command fails due to merge errors. When you are done editing
1226 and/or resolving conflicts you can continue with
<tt>git rebase --continue
</tt>.
</p></div>
1227 <div class=
"paragraph"><p>For example, if you want to reorder the last
5 commits, such that what
1228 was HEAD~
4 becomes the new HEAD. To achieve that, you would call
1229 <em>git rebase
</em> like this:
</p></div>
1230 <div class=
"listingblock">
1231 <div class=
"content">
1232 <pre><tt>$ git rebase -i HEAD~
5</tt></pre>
1234 <div class=
"paragraph"><p>And move the first patch to the end of the list.
</p></div>
1235 <div class=
"paragraph"><p>You might want to preserve merges, if you have a history like this:
</p></div>
1236 <div class=
"listingblock">
1237 <div class=
"content">
1242 ---o---O---P---Q
</tt></pre>
1244 <div class=
"paragraph"><p>Suppose you want to rebase the side branch starting at
"A" to
"Q". Make
1245 sure that the current HEAD is
"B", and call
</p></div>
1246 <div class=
"listingblock">
1247 <div class=
"content">
1248 <pre><tt>$ git rebase -i -p --onto Q O
</tt></pre>
1250 <div class=
"paragraph"><p>Reordering and editing commits usually creates untested intermediate
1251 steps. You may want to check that your history editing did not break
1252 anything by running a test, or at least recompiling at intermediate
1253 points in history by using the
"exec" command (shortcut
"x"). You may
1254 do so by creating a todo list like this one:
</p></div>
1255 <div class=
"listingblock">
1256 <div class=
"content">
1257 <pre><tt>pick deadbee Implement feature XXX
1258 fixup f1a5c00 Fix to feature XXX
1260 pick c0ffeee The oneline of the next commit
1261 edit deadbab The oneline of the commit after
1262 exec cd subdir; make test
1265 <div class=
"paragraph"><p>The interactive rebase will stop when a command fails (i.e. exits with
1266 non-
0 status) to give you an opportunity to fix the problem. You can
1267 continue with
<tt>git rebase --continue
</tt>.
</p></div>
1268 <div class=
"paragraph"><p>The
"exec" command launches the command in a shell (the one specified
1269 in
<tt>$SHELL
</tt>, or the default shell if
<tt>$SHELL
</tt> is not set), so you can
1270 use shell features (like
"cd",
">",
";" …). The command is run from
1271 the root of the working tree.
</p></div>
1273 <h2 id=
"_splitting_commits">SPLITTING COMMITS
</h2>
1274 <div class=
"sectionbody">
1275 <div class=
"paragraph"><p>In interactive mode, you can mark commits with the action
"edit". However,
1276 this does not necessarily mean that
<em>git rebase
</em> expects the result of this
1277 edit to be exactly one commit. Indeed, you can undo the commit, or you can
1278 add other commits. This can be used to split a commit into two:
</p></div>
1279 <div class=
"ulist"><ul>
1282 Start an interactive rebase with
<tt>git rebase -i
<commit
>^
</tt>, where
1283 <commit
> is the commit you want to split. In fact, any commit range
1284 will do, as long as it contains that commit.
1289 Mark the commit you want to split with the action
"edit".
1294 When it comes to editing that commit, execute
<tt>git reset HEAD^
</tt>. The
1295 effect is that the HEAD is rewound by one, and the index follows suit.
1296 However, the working tree stays the same.
1301 Now add the changes to the index that you want to have in the first
1302 commit. You can use
<tt>git add
</tt> (possibly interactively) or
1303 <em>git gui
</em> (or both) to do that.
1308 Commit the now-current index with whatever commit message is appropriate
1314 Repeat the last two steps until your working tree is clean.
1319 Continue the rebase with
<tt>git rebase --continue
</tt>.
1323 <div class=
"paragraph"><p>If you are not absolutely sure that the intermediate revisions are
1324 consistent (they compile, pass the testsuite, etc.) you should use
1325 <em>git stash
</em> to stash away the not-yet-committed changes
1326 after each commit, test, and amend the commit if fixes are necessary.
</p></div>
1328 <h2 id=
"_recovering_from_upstream_rebase">RECOVERING FROM UPSTREAM REBASE
</h2>
1329 <div class=
"sectionbody">
1330 <div class=
"paragraph"><p>Rebasing (or any other form of rewriting) a branch that others have
1331 based work on is a bad idea: anyone downstream of it is forced to
1332 manually fix their history. This section explains how to do the fix
1333 from the downstream
’s point of view. The real fix, however, would be
1334 to avoid rebasing the upstream in the first place.
</p></div>
1335 <div class=
"paragraph"><p>To illustrate, suppose you are in a situation where someone develops a
1336 <em>subsystem
</em> branch, and you are working on a
<em>topic
</em> that is dependent
1337 on this
<em>subsystem
</em>. You might end up with a history like the
1338 following:
</p></div>
1339 <div class=
"listingblock">
1340 <div class=
"content">
1341 <pre><tt> o---o---o---o---o---o---o---o---o master
1343 o---o---o---o---o subsystem
1345 *---*---* topic
</tt></pre>
1347 <div class=
"paragraph"><p>If
<em>subsystem
</em> is rebased against
<em>master
</em>, the following happens:
</p></div>
1348 <div class=
"listingblock">
1349 <div class=
"content">
1350 <pre><tt> o---o---o---o---o---o---o---o master
1352 o---o---o---o---o o'--o'--o'--o'--o' subsystem
1354 *---*---* topic
</tt></pre>
1356 <div class=
"paragraph"><p>If you now continue development as usual, and eventually merge
<em>topic
</em>
1357 to
<em>subsystem
</em>, the commits from
<em>subsystem
</em> will remain duplicated forever:
</p></div>
1358 <div class=
"listingblock">
1359 <div class=
"content">
1360 <pre><tt> o---o---o---o---o---o---o---o master
1362 o---o---o---o---o o'--o'--o'--o'--o'--M subsystem
1364 *---*---*-..........-*--* topic
</tt></pre>
1366 <div class=
"paragraph"><p>Such duplicates are generally frowned upon because they clutter up
1367 history, making it harder to follow. To clean things up, you need to
1368 transplant the commits on
<em>topic
</em> to the new
<em>subsystem
</em> tip, i.e.,
1369 rebase
<em>topic
</em>. This becomes a ripple effect: anyone downstream from
1370 <em>topic
</em> is forced to rebase too, and so on!
</p></div>
1371 <div class=
"paragraph"><p>There are two kinds of fixes, discussed in the following subsections:
</p></div>
1372 <div class=
"dlist"><dl>
1373 <dt class=
"hdlist1">
1374 Easy case: The changes are literally the same.
1378 This happens if the
<em>subsystem
</em> rebase was a simple rebase and
1382 <dt class=
"hdlist1">
1383 Hard case: The changes are not the same.
1387 This happens if the
<em>subsystem
</em> rebase had conflicts, or used
1388 <tt>--interactive
</tt> to omit, edit, squash, or fixup commits; or
1389 if the upstream used one of
<tt>commit --amend
</tt>,
<tt>reset
</tt>, or
1390 <tt>filter-branch
</tt>.
1394 <h3 id=
"_the_easy_case">The easy case
</h3><div style=
"clear:left"></div>
1395 <div class=
"paragraph"><p>Only works if the changes (patch IDs based on the diff contents) on
1396 <em>subsystem
</em> are literally the same before and after the rebase
1397 <em>subsystem
</em> did.
</p></div>
1398 <div class=
"paragraph"><p>In that case, the fix is easy because
<em>git rebase
</em> knows to skip
1399 changes that are already present in the new upstream. So if you say
1400 (assuming you
’re on
<em>topic
</em>)
</p></div>
1401 <div class=
"listingblock">
1402 <div class=
"content">
1403 <pre><tt> $ git rebase subsystem
</tt></pre>
1405 <div class=
"paragraph"><p>you will end up with the fixed history
</p></div>
1406 <div class=
"listingblock">
1407 <div class=
"content">
1408 <pre><tt> o---o---o---o---o---o---o---o master
1410 o'--o'--o'--o'--o' subsystem
1412 *---*---* topic
</tt></pre>
1414 <h3 id=
"_the_hard_case">The hard case
</h3><div style=
"clear:left"></div>
1415 <div class=
"paragraph"><p>Things get more complicated if the
<em>subsystem
</em> changes do not exactly
1416 correspond to the ones before the rebase.
</p></div>
1417 <div class=
"admonitionblock">
1420 <div class=
"title">Note
</div>
1422 <td class=
"content">While an
"easy case recovery" sometimes appears to be successful
1423 even in the hard case, it may have unintended consequences. For
1424 example, a commit that was removed via
<tt>git rebase
1425 --interactive
</tt> will be
<strong>resurrected
</strong>!
</td>
1428 <div class=
"paragraph"><p>The idea is to manually tell
<em>git rebase
</em> "where the old <em>subsystem</em>
1429 ended and your <em>topic</em> began", that is, what the old merge-base
1430 between them was. You will have to find a way to name the last commit
1431 of the old
<em>subsystem
</em>, for example:
</p></div>
1432 <div class=
"ulist"><ul>
1435 With the
<em>subsystem
</em> reflog: after
<em>git fetch
</em>, the old tip of
1436 <em>subsystem
</em> is at
<tt>subsystem@{
1}
</tt>. Subsequent fetches will
1437 increase the number. (See
<a href=
"git-reflog.html">git-reflog(
1)
</a>.)
1442 Relative to the tip of
<em>topic
</em>: knowing that your
<em>topic
</em> has three
1443 commits, the old tip of
<em>subsystem
</em> must be
<tt>topic~
3</tt>.
1447 <div class=
"paragraph"><p>You can then transplant the old
<tt>subsystem..topic
</tt> to the new tip by
1448 saying (for the reflog case, and assuming you are on
<em>topic
</em> already):
</p></div>
1449 <div class=
"listingblock">
1450 <div class=
"content">
1451 <pre><tt> $ git rebase --onto subsystem subsystem@{
1}
</tt></pre>
1453 <div class=
"paragraph"><p>The ripple effect of a
"hard case" recovery is especially bad:
1454 <em>everyone
</em> downstream from
<em>topic
</em> will now have to perform a
"hard
1455 case" recovery too!
</p></div>
1457 <h2 id=
"_bugs">BUGS
</h2>
1458 <div class=
"sectionbody">
1459 <div class=
"paragraph"><p>The todo list presented by
<tt>--preserve-merges --interactive
</tt> does not
1460 represent the topology of the revision graph. Editing commits and
1461 rewording their commit messages should work fine, but attempts to
1462 reorder commits tend to produce counterintuitive results.
</p></div>
1463 <div class=
"paragraph"><p>For example, an attempt to rearrange
</p></div>
1464 <div class=
"listingblock">
1465 <div class=
"content">
1466 <pre><tt>1 ---
2 ---
3 ---
4 ---
5</tt></pre>
1468 <div class=
"paragraph"><p>to
</p></div>
1469 <div class=
"listingblock">
1470 <div class=
"content">
1471 <pre><tt>1 ---
2 ---
4 ---
3 ---
5</tt></pre>
1473 <div class=
"paragraph"><p>by moving the
"pick 4" line will result in the following history:
</p></div>
1474 <div class=
"listingblock">
1475 <div class=
"content">
1478 1 ---
2 ---
4 ---
5</tt></pre>
1481 <h2 id=
"_git">GIT
</h2>
1482 <div class=
"sectionbody">
1483 <div class=
"paragraph"><p>Part of the
<a href=
"git.html">git(
1)
</a> suite
</p></div>
1486 <div id=
"footer-text">
1487 Last updated
2011-
04-
28 22:
25:
18 UTC