Documentation/git-rebase.txt

   1 git-rebase(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-rebase - Forward-port local commits to the updated upstream head
   7
   8 SYNOPSIS
   9 --------
  10 'git-rebase' [-v] [--merge] [--onto <newbase>] <upstream> [<branch>]
  11
  12 'git-rebase' --continue | --skip | --abort
  13
  14 DESCRIPTION
  15 -----------
  16 git-rebase replaces <branch> with a new branch of the same name.  When
  17 the --onto option is provided the new branch starts out with a HEAD equal
  18 to <newbase>, otherwise it is equal to <upstream>.  It then attempts to
  19 create a new commit for each commit from the original <branch> that does
  20 not exist in the <upstream> branch.
  21
  22 It is possible that a merge failure will prevent this process from being
  23 completely automatic.  You will have to resolve any such merge failure
  24 and run `git rebase --continue`.  Another option is to bypass the commit
  25 that caused the merge failure with `git rebase --skip`.  To restore the
  26 original <branch> and remove the .dotest working files, use the command
  27 `git rebase --abort` instead.
  28
  29 Note that if <branch> is not specified on the command line, the currently
  30 checked out branch is used.
  31
  32 Assume the following history exists and the current branch is "topic":
  33
  34 ------------
  35           A---B---C topic
  36          /
  37     D---E---F---G master
  38 ------------
  39
  40 From this point, the result of either of the following commands:
  41
  42
  43     git-rebase master
  44     git-rebase master topic
  45
  46 would be:
  47
  48 ------------
  49                   A'--B'--C' topic
  50                  /
  51     D---E---F---G master
  52 ------------
  53
  54 The latter form is just a short-hand of `git checkout topic`
  55 followed by `git rebase master`.
  56
  57 Here is how you would transplant a topic branch based on one
  58 branch to another, to pretend that you forked the topic branch
  59 from the latter branch, using `rebase --onto`.
  60
  61 First let's assume your 'topic' is based on branch 'next'.
  62 For example feature developed in 'topic' depends on some
  63 functionality which is found in 'next'.
  64
  65 ------------
  66     o---o---o---o---o  master
  67          \
  68           o---o---o---o---o  next
  69                            \
  70                             o---o---o  topic
  71 ------------
  72
  73 We would want to make 'topic' forked from branch 'master',
  74 for example because the functionality 'topic' branch depend on
  75 got merged into more stable 'master' branch, like this:
  76
  77 ------------
  78     o---o---o---o---o  master
  79         |            \
  80         |             o'--o'--o'  topic
  81          \
  82           o---o---o---o---o  next
  83 ------------
  84
  85 We can get this using the following command:
  86
  87     git-rebase --onto master next topic
  88
  89
  90 Another example of --onto option is to rebase part of a
  91 branch.  If we have the following situation:
  92
  93 ------------
  94                             H---I---J topicB
  95                            /
  96                   E---F---G  topicA
  97                  /
  98     A---B---C---D  master
  99 ------------
 100
 101 then the command
 102
 103     git-rebase --onto master topicA topicB
 104
 105 would result in:
 106
 107 ------------
 108                  H'--I'--J'  topicB
 109                 /
 110                 | E---F---G  topicA
 111                 |/
 112     A---B---C---D  master
 113 ------------
 114
 115 This is useful when topicB does not depend on topicA.
 116
 117 In case of conflict, git-rebase will stop at the first problematic commit
 118 and leave conflict markers in the tree.  You can use git diff to locate
 119 the markers (<<<<<<) and make edits to resolve the conflict.  For each
 120 file you edit, you need to tell git that the conflict has been resolved,
 121 typically this would be done with
 122
 123
 124     git update-index <filename>
 125
 126
 127 After resolving the conflict manually and updating the index with the
 128 desired resolution, you can continue the rebasing process with
 129
 130
 131     git rebase --continue
 132
 133
 134 Alternatively, you can undo the git-rebase with
 135
 136
 137     git rebase --abort
 138
 139 OPTIONS
 140 -------
 141 <newbase>::
 142         Starting point at which to create the new commits. If the
 143         --onto option is not specified, the starting point is
 144         <upstream>.
 145
 146 <upstream>::
 147         Upstream branch to compare against.
 148
 149 <branch>::
 150         Working branch; defaults to HEAD.
 151
 152 --continue::
 153         Restart the rebasing process after having resolved a merge conflict.
 154
 155 --abort::
 156         Restore the original branch and abort the rebase operation.
 157
 158 --skip::
 159         Restart the rebasing process by skipping the current patch.
 160
 161 --merge::
 162         Use merging strategies to rebase.  When the recursive (default) merge
 163         strategy is used, this allows rebase to be aware of renames on the
 164         upstream side.
 165
 166 -s <strategy>, \--strategy=<strategy>::
 167         Use the given merge strategy; can be supplied more than
 168         once to specify them in the order they should be tried.
 169         If there is no `-s` option, a built-in list of strategies
 170         is used instead (`git-merge-recursive` when merging a single
 171         head, `git-merge-octopus` otherwise).  This implies --merge.
 172
 173 -v, \--verbose::
 174         Display a diffstat of what changed upstream since the last rebase.
 175
 176 include::merge-strategies.txt[]
 177
 178 NOTES
 179 -----
 180 When you rebase a branch, you are changing its history in a way that
 181 will cause problems for anyone who already has a copy of the branch
 182 in their repository and tries to pull updates from you.  You should
 183 understand the implications of using 'git rebase' on a repository that
 184 you share.
 185
 186 When the git rebase command is run, it will first execute a "pre-rebase"
 187 hook if one exists.  You can use this hook to do sanity checks and
 188 reject the rebase if it isn't appropriate.  Please see the template
 189 pre-rebase hook script for an example.
 190
 191 You must be in the top directory of your project to start (or continue)
 192 a rebase.  Upon completion, <branch> will be the current branch.
 193
 194 Author
 195 ------
 196 Written by Junio C Hamano <junkio@cox.net>
 197
 198 Documentation
 199 --------------
 200 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 201
 202 GIT
 203 ---
 204 Part of the gitlink:git[7] suite
 205