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