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