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