1git-rerere(1) 2============= 3 4NAME 5---- 6git-rerere - Reuse recorded resolve 7 8SYNOPSIS 9-------- 10'git-rerere' [clear|diff|status] 11 12DESCRIPTION 13----------- 14 15In a workflow that employs relatively long lived topic branches, 16the developer sometimes needs to resolve the same conflict over 17and over again until the topic branches are done (either merged 18to the "release" branch, or sent out and accepted upstream). 19 20This command helps this process by recording conflicted 21automerge results and corresponding hand-resolve results on the 22initial manual merge, and later by noticing the same automerge 23results and applying the previously recorded hand resolution. 24 25[NOTE] 26You need to create `$GIT_DIR/rr-cache` directory to enable this 27command. 28 29DISCUSSION 30---------- 31 32When your topic branch modifies overlapping area that your 33master branch (or upstream) touched since your topic branch 34forked from it, you may want to test it with the latest master, 35even before your topic branch is ready to be pushed upstream: 36 37------------ 38 o---*---o topic 39 / 40 o---o---o---*---o---o master 41------------ 42 43For such a test, you need to merge master and topic somehow. 44One way to do it is to pull master into the topic branch: 45 46------------ 47 $ git checkout topic 48 $ git pull . master 49 50 o---*---o---+ topic 51 / / 52 o---o---o---*---o---o master 53------------ 54 55The commits marked with `*` touch the same area in the same 56file; you need to resolve the conflicts when creating the commit 57marked with `+`. Then you can test the result to make sure your 58work-in-progress still works with what is in the latest master. 59 60After this test merge, there are two ways to continue your work 61on the topic. The easiest is to build on top of the test merge 62commit `+`, and when your work in the topic branch is finally 63ready, pull the topic branch into master, and/or ask the 64upstream to pull from you. By that time, however, the master or 65the upstream might have been advanced since the test merge `+`, 66in which case the final commit graph would look like this: 67 68------------ 69 $ git checkout topic 70 $ git pull . master 71 $ ... work on both topic and master branches 72 $ git checkout master 73 $ git pull . topic 74 75 o---*---o---+---o---o topic 76 / / \ 77 o---o---o---*---o---o---o---o---+ master 78------------ 79 80When your topic branch is long-lived, however, your topic branch 81would end up having many such "Merge from master" commits on it, 82which would unnecessarily clutter the development history. 83Readers of the Linux kernel mailing list may remember that Linus 84complained about such too frequent test merges when a subsystem 85maintainer asked to pull from a branch full of "useless merges". 86 87As an alternative, to keep the topic branch clean of test 88merges, you could blow away the test merge, and keep building on 89top of the tip before the test merge: 90 91------------ 92 $ git checkout topic 93 $ git pull . master 94 $ git reset --hard HEAD^ ;# rewind the test merge 95 $ ... work on both topic and master branches 96 $ git checkout master 97 $ git pull . topic 98 99 o---*---o-------o---o topic 100 / \ 101 o---o---o---*---o---o---o---o---+ master 102------------ 103 104This would leave only one merge commit when your topic branch is 105finally ready and merged into the master branch. This merge 106would require you to resolve the conflict, introduced by the 107commits marked with `*`. However, often this conflict is the 108same conflict you resolved when you created the test merge you 109blew away. `git-rerere` command helps you to resolve this final 110conflicted merge using the information from your earlier hand 111resolve. 112 113Running `git-rerere` command immediately after a conflicted 114automerge records the conflicted working tree files, with the 115usual conflict markers `<<<<<<<`, `=======`, and `>>>>>>>` in 116them. Later, after you are done resolving the conflicts, 117running `git-rerere` again records the resolved state of these 118files. Suppose you did this when you created the test merge of 119master into the topic branch. 120 121Next time, running `git-rerere` after seeing a conflicted 122automerge, if the conflict is the same as the earlier one 123recorded, it is noticed and a three-way merge between the 124earlier conflicted automerge, the earlier manual resolution, and 125the current conflicted automerge is performed by the command. 126If this three-way merge resolves cleanly, the result is written 127out to your working tree file, so you would not have to manually 128resolve it. Note that `git-rerere` leaves the index file alone, 129so you still need to do the final sanity checks with `git diff` 130(or `git diff -c`) and `git update-index` when you are 131satisfied. 132 133As a convenience measure, `git-merge` automatically invokes 134`git-rerere` when it exits with a failed automerge, which 135records it if it is a new conflict, or reuses the earlier hand 136resolve when it is not. `git-commit` also invokes `git-rerere` 137when recording a merge result. What this means is that you do 138not have to do anything special yourself (Note: you still have 139to create `$GIT_DIR/rr-cache` directory to enable this command). 140 141In our example, when you did the test merge, the manual 142resolution is recorded, and it will be reused when you do the 143actual merge later with updated master and topic branch, as long 144as the earlier resolution is still applicable. 145 146The information `git-rerere` records is also used when running 147`git-rebase`. After blowing away the test merge and continuing 148development on the topic branch: 149 150------------ 151 o---*---o-------o---o topic 152 / 153 o---o---o---*---o---o---o---o master 154 155 $ git rebase master topic 156 157 o---*---o-------o---o topic 158 / 159 o---o---o---*---o---o---o---o master 160------------ 161 162you could run `git rebase master topic`, to keep yourself 163up-to-date even before your topic is ready to be sent upstream. 164This would result in falling back to three-way merge, and it 165would conflict the same way the test merge you resolved earlier. 166`git-rerere` is run by `git rebase` to help you resolve this 167conflict. 168 169COMMANDS 170-------- 171 172Normally, git-rerere is run without arguments or user-intervention. 173However, it has several commands that allow it to interact with 174its working state. 175 176'clear':: 177 178This resets the metadata used by rerere if a merge resolution is to be 179is aborted. Calling gitlink:git-am[1] --skip or gitlink:git-rebase[1] 180[--skip|--abort] will automatcally invoke this command. 181 182'diff':: 183 184This displays diffs for the current state of the resolution. It is 185useful for tracking what has changed while the user is resolving 186conflicts. Additional arguments are passed directly to the system 187diff(1) command installed in PATH. 188 189'status':: 190 191Like diff, but this only prints the filenames that will be tracked 192for resolutions. 193 194Author 195------ 196Written by Junio C Hamano <junkio@cox.net> 197 198GIT 199--- 200Part of the gitlink:git[7] suite