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 A range of commits could also be removed with rebase.  If we have
 118 the following situation:
 119
 120 ------------
 121     E---F---G---H---I---J  topicA
 122 ------------
 123
 124 then the command
 125
 126     git-rebase --onto topicA~5 topicA~2 topicA
 127
 128 would result in the removal of commits F and G:
 129
 130 ------------
 131     E---H'---I'---J'  topicA
 132 ------------
 133
 134 This is useful if F and G were flawed in some way, or should not be
 135 part of topicA.  Note that the argument to --onto and the <upstream>
 136 parameter can be any valid commit-ish.
 137
 138 In case of conflict, git-rebase will stop at the first problematic commit
 139 and leave conflict markers in the tree.  You can use git diff to locate
 140 the markers (<<<<<<) and make edits to resolve the conflict.  For each
 141 file you edit, you need to tell git that the conflict has been resolved,
 142 typically this would be done with
 143
 144
 145     git update-index <filename>
 146
 147
 148 After resolving the conflict manually and updating the index with the
 149 desired resolution, you can continue the rebasing process with
 150
 151
 152     git rebase --continue
 153
 154
 155 Alternatively, you can undo the git-rebase with
 156
 157
 158     git rebase --abort
 159
 160 OPTIONS
 161 -------
 162 <newbase>::
 163         Starting point at which to create the new commits. If the
 164         --onto option is not specified, the starting point is
 165         <upstream>.  May be any valid commit, and not just an
 166         existing branch name.
 167
 168 <upstream>::
 169         Upstream branch to compare against.  May be any valid commit,
 170         not just an existing branch name.
 171
 172 <branch>::
 173         Working branch; defaults to HEAD.
 174
 175 --continue::
 176         Restart the rebasing process after having resolved a merge conflict.
 177
 178 --abort::
 179         Restore the original branch and abort the rebase operation.
 180
 181 --skip::
 182         Restart the rebasing process by skipping the current patch.
 183
 184 --merge::
 185         Use merging strategies to rebase.  When the recursive (default) merge
 186         strategy is used, this allows rebase to be aware of renames on the
 187         upstream side.
 188
 189 -s <strategy>, \--strategy=<strategy>::
 190         Use the given merge strategy; can be supplied more than
 191         once to specify them in the order they should be tried.
 192         If there is no `-s` option, a built-in list of strategies
 193         is used instead (`git-merge-recursive` when merging a single
 194         head, `git-merge-octopus` otherwise).  This implies --merge.
 195
 196 -v, \--verbose::
 197         Display a diffstat of what changed upstream since the last rebase.
 198
 199 include::merge-strategies.txt[]
 200
 201 NOTES
 202 -----
 203 When you rebase a branch, you are changing its history in a way that
 204 will cause problems for anyone who already has a copy of the branch
 205 in their repository and tries to pull updates from you.  You should
 206 understand the implications of using 'git rebase' on a repository that
 207 you share.
 208
 209 When the git rebase command is run, it will first execute a "pre-rebase"
 210 hook if one exists.  You can use this hook to do sanity checks and
 211 reject the rebase if it isn't appropriate.  Please see the template
 212 pre-rebase hook script for an example.
 213
 214 You must be in the top directory of your project to start (or continue)
 215 a rebase.  Upon completion, <branch> will be the current branch.
 216
 217 Author
 218 ------
 219 Written by Junio C Hamano <junkio@cox.net>
 220
 221 Documentation
 222 --------------
 223 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 224
 225 GIT
 226 ---
 227 Part of the gitlink:git[7] suite
 228