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