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