Documentation / git-rebase.txton commit Teach bash about completing arguments for git-tag (88e21dc)
   1git-rebase(1)
   2=============
   3
   4NAME
   5----
   6git-rebase - Forward-port local commits to the updated upstream head
   7
   8SYNOPSIS
   9--------
  10[verse]
  11'git-rebase' [-i | --interactive] [-v | --verbose] [--merge] [-C<n>]
  12        [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>]
  13'git-rebase' --continue | --skip | --abort
  14
  15DESCRIPTION
  16-----------
  17If <branch> is specified, git-rebase will perform an automatic
  18`git checkout <branch>` before doing anything else.  Otherwise
  19it remains on the current branch.
  20
  21All changes made by commits in the current branch but that are not
  22in <upstream> are saved to a temporary area.  This is the same set
  23of commits that would be shown by `git log <upstream>..HEAD`.
  24
  25The current branch is reset to <upstream>, or <newbase> if the
  26--onto option was supplied.  This has the exact same effect as
  27`git reset --hard <upstream>` (or <newbase>).
  28
  29The commits that were previously saved into the temporary area are
  30then reapplied to the current branch, one by one, in order.
  31
  32It is possible that a merge failure will prevent this process from being
  33completely automatic.  You will have to resolve any such merge failure
  34and run `git rebase --continue`.  Another option is to bypass the commit
  35that caused the merge failure with `git rebase --skip`.  To restore the
  36original <branch> and remove the .dotest working files, use the command
  37`git rebase --abort` instead.
  38
  39Assume the following history exists and the current branch is "topic":
  40
  41------------
  42          A---B---C topic
  43         /
  44    D---E---F---G master
  45------------
  46
  47From this point, the result of either of the following commands:
  48
  49
  50    git-rebase master
  51    git-rebase master topic
  52
  53would be:
  54
  55------------
  56                  A'--B'--C' topic
  57                 /
  58    D---E---F---G master
  59------------
  60
  61The latter form is just a short-hand of `git checkout topic`
  62followed by `git rebase master`.
  63
  64Here is how you would transplant a topic branch based on one
  65branch to another, to pretend that you forked the topic branch
  66from the latter branch, using `rebase --onto`.
  67
  68First let's assume your 'topic' is based on branch 'next'.
  69For example feature developed in 'topic' depends on some
  70functionality which is found in 'next'.
  71
  72------------
  73    o---o---o---o---o  master
  74         \
  75          o---o---o---o---o  next
  76                           \
  77                            o---o---o  topic
  78------------
  79
  80We would want to make 'topic' forked from branch 'master',
  81for example because the functionality 'topic' branch depend on
  82got merged into more stable 'master' branch, like this:
  83
  84------------
  85    o---o---o---o---o  master
  86        |            \
  87        |             o'--o'--o'  topic
  88         \
  89          o---o---o---o---o  next
  90------------
  91
  92We can get this using the following command:
  93
  94    git-rebase --onto master next topic
  95
  96
  97Another example of --onto option is to rebase part of a
  98branch.  If we have the following situation:
  99
 100------------
 101                            H---I---J topicB
 102                           /
 103                  E---F---G  topicA
 104                 /
 105    A---B---C---D  master
 106------------
 107
 108then the command
 109
 110    git-rebase --onto master topicA topicB
 111
 112would result in:
 113
 114------------
 115                 H'--I'--J'  topicB
 116                /
 117                | E---F---G  topicA
 118                |/
 119    A---B---C---D  master
 120------------
 121
 122This is useful when topicB does not depend on topicA.
 123
 124A range of commits could also be removed with rebase.  If we have
 125the following situation:
 126
 127------------
 128    E---F---G---H---I---J  topicA
 129------------
 130
 131then the command
 132
 133    git-rebase --onto topicA~5 topicA~3 topicA
 134
 135would result in the removal of commits F and G:
 136
 137------------
 138    E---H'---I'---J'  topicA
 139------------
 140
 141This is useful if F and G were flawed in some way, or should not be
 142part of topicA.  Note that the argument to --onto and the <upstream>
 143parameter can be any valid commit-ish.
 144
 145In case of conflict, git-rebase will stop at the first problematic commit
 146and leave conflict markers in the tree.  You can use git diff to locate
 147the markers (<<<<<<) and make edits to resolve the conflict.  For each
 148file you edit, you need to tell git that the conflict has been resolved,
 149typically this would be done with
 150
 151
 152    git add <filename>
 153
 154
 155After resolving the conflict manually and updating the index with the
 156desired resolution, you can continue the rebasing process with
 157
 158
 159    git rebase --continue
 160
 161
 162Alternatively, you can undo the git-rebase with
 163
 164
 165    git rebase --abort
 166
 167OPTIONS
 168-------
 169<newbase>::
 170        Starting point at which to create the new commits. If the
 171        --onto option is not specified, the starting point is
 172        <upstream>.  May be any valid commit, and not just an
 173        existing branch name.
 174
 175<upstream>::
 176        Upstream branch to compare against.  May be any valid commit,
 177        not just an existing branch name.
 178
 179<branch>::
 180        Working branch; defaults to HEAD.
 181
 182--continue::
 183        Restart the rebasing process after having resolved a merge conflict.
 184
 185--abort::
 186        Restore the original branch and abort the rebase operation.
 187
 188--skip::
 189        Restart the rebasing process by skipping the current patch.
 190
 191--merge::
 192        Use merging strategies to rebase.  When the recursive (default) merge
 193        strategy is used, this allows rebase to be aware of renames on the
 194        upstream side.
 195
 196-s <strategy>, \--strategy=<strategy>::
 197        Use the given merge strategy; can be supplied more than
 198        once to specify them in the order they should be tried.
 199        If there is no `-s` option, a built-in list of strategies
 200        is used instead (`git-merge-recursive` when merging a single
 201        head, `git-merge-octopus` otherwise).  This implies --merge.
 202
 203-v, \--verbose::
 204        Display a diffstat of what changed upstream since the last rebase.
 205
 206-C<n>::
 207        Ensure at least <n> lines of surrounding context match before
 208        and after each change.  When fewer lines of surrounding
 209        context exist they all must match.  By default no context is
 210        ever ignored.
 211
 212-i, \--interactive::
 213        Make a list of the commits which are about to be rebased.  Let the
 214        user edit that list before rebasing.
 215
 216-p, \--preserve-merges::
 217        Instead of ignoring merges, try to recreate them.  This option
 218        only works in interactive mode.
 219
 220include::merge-strategies.txt[]
 221
 222NOTES
 223-----
 224When you rebase a branch, you are changing its history in a way that
 225will cause problems for anyone who already has a copy of the branch
 226in their repository and tries to pull updates from you.  You should
 227understand the implications of using 'git rebase' on a repository that
 228you share.
 229
 230When the git rebase command is run, it will first execute a "pre-rebase"
 231hook if one exists.  You can use this hook to do sanity checks and
 232reject the rebase if it isn't appropriate.  Please see the template
 233pre-rebase hook script for an example.
 234
 235You must be in the top directory of your project to start (or continue)
 236a rebase.  Upon completion, <branch> will be the current branch.
 237
 238INTERACTIVE MODE
 239----------------
 240
 241Rebasing interactively means that you have a chance to edit the commits
 242which are rebased.  You can reorder the commits, and you can
 243remove them (weeding out bad or otherwise unwanted patches).
 244
 245The interactive mode is meant for this type of workflow:
 246
 2471. have a wonderful idea
 2482. hack on the code
 2493. prepare a series for submission
 2504. submit
 251
 252where point 2. consists of several instances of
 253
 254a. regular use
 255 1. finish something worthy of a commit
 256 2. commit
 257b. independent fixup
 258 1. realize that something does not work
 259 2. fix that
 260 3. commit it
 261
 262Sometimes the thing fixed in b.2. cannot be amended to the not-quite
 263perfect commit it fixes, because that commit is buried deeply in a
 264patch series.  That is exactly what interactive rebase is for: use it
 265after plenty of "a"s and "b"s, by rearranging and editing
 266commits, and squashing multiple commits into one.
 267
 268Start it with the last commit you want to retain as-is:
 269
 270        git rebase -i <after-this-commit>
 271
 272An editor will be fired up with all the commits in your current branch
 273(ignoring merge commits), which come after the given commit.  You can
 274reorder the commits in this list to your heart's content, and you can
 275remove them.  The list looks more or less like this:
 276
 277-------------------------------------------
 278pick deadbee The oneline of this commit
 279pick fa1afe1 The oneline of the next commit
 280...
 281-------------------------------------------
 282
 283The oneline descriptions are purely for your pleasure; `git-rebase` will
 284not look at them but at the commit names ("deadbee" and "fa1afe1" in this
 285example), so do not delete or edit the names.
 286
 287By replacing the command "pick" with the command "edit", you can tell
 288`git-rebase` to stop after applying that commit, so that you can edit
 289the files and/or the commit message, amend the commit, and continue
 290rebasing.
 291
 292If you want to fold two or more commits into one, replace the command
 293"pick" with "squash" for the second and subsequent commit.  If the
 294commits had different authors, it will attribute the squashed commit to
 295the author of the last commit.
 296
 297In both cases, or when a "pick" does not succeed (because of merge
 298errors), the loop will stop to let you fix things, and you can continue
 299the loop with `git rebase --continue`.
 300
 301For example, if you want to reorder the last 5 commits, such that what
 302was HEAD~4 becomes the new HEAD. To achieve that, you would call
 303`git-rebase` like this:
 304
 305----------------------
 306$ git rebase -i HEAD~5
 307----------------------
 308
 309And move the first patch to the end of the list.
 310
 311You might want to preserve merges, if you have a history like this:
 312
 313------------------
 314           X
 315            \
 316         A---M---B
 317        /
 318---o---O---P---Q
 319------------------
 320
 321Suppose you want to rebase the side branch starting at "A" to "Q". Make
 322sure that the current HEAD is "B", and call
 323
 324-----------------------------
 325$ git rebase -i -p --onto Q O
 326-----------------------------
 327
 328Authors
 329------
 330Written by Junio C Hamano <junkio@cox.net> and
 331Johannes E. Schindelin <johannes.schindelin@gmx.de>
 332
 333Documentation
 334--------------
 335Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 336
 337GIT
 338---
 339Part of the gitlink:git[7] suite