]>
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] |
3e7a1df8 | 11 | 'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'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] |
fe61ccbc | 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 | ||
3e7a1df8 | 40 | Reset 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 | ||
3e7a1df8 | 46 | Reset the conflict resolutions which rerere has recorded for the current |
5d2c3b01 | 47 | conflict in <pathspec>. |
2c640344 | 48 | |
cda2d3c1 JH |
49 | 'diff':: |
50 | ||
3e7a1df8 | 51 | Display diffs for the current state of the resolution. It is |
cda2d3c1 JH |
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 | ||
3e7a1df8 PH |
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. | |
cda2d3c1 JH |
65 | |
66 | 'gc':: | |
67 | ||
3e7a1df8 | 68 | Prune records of conflicted merges that |
c97038d1 SB |
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 | |
da0005b8 | 72 | `gc.rerereUnresolved` and `gc.rerereResolved` configuration |
c97038d1 | 73 | variables respectively. |
cda2d3c1 JH |
74 | |
75 | ||
8389b52b JH |
76 | DISCUSSION |
77 | ---------- | |
78 | ||
c97038d1 | 79 | When your topic branch modifies an overlapping area that your |
8389b52b JH |
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 | ------------ | |
328c6cb8 | 94 | $ git switch topic |
c14261ea | 95 | $ git merge master |
8389b52b JH |
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 | |
6cf378f0 | 104 | marked with `+`. Then you can test the result to make sure your |
8389b52b JH |
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 | |
6cf378f0 | 109 | commit `+`, and when your work in the topic branch is finally |
8389b52b JH |
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 | |
6cf378f0 | 112 | the upstream might have been advanced since the test merge `+`, |
8389b52b JH |
113 | in which case the final commit graph would look like this: |
114 | ||
115 | ------------ | |
328c6cb8 | 116 | $ git switch topic |
c14261ea | 117 | $ git merge master |
8389b52b | 118 | $ ... work on both topic and master branches |
328c6cb8 | 119 | $ git switch master |
c14261ea | 120 | $ git merge topic |
8389b52b JH |
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 | ------------ | |
328c6cb8 | 139 | $ git switch topic |
c14261ea | 140 | $ git merge master |
8389b52b JH |
141 | $ git reset --hard HEAD^ ;# rewind the test merge |
142 | $ ... work on both topic and master branches | |
328c6cb8 | 143 | $ git switch master |
c14261ea | 144 | $ git merge topic |
8389b52b JH |
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 | |
c97038d1 | 154 | commits marked with `*`. However, this conflict is often the |
8389b52b | 155 | same conflict you resolved when you created the test merge you |
0b444cdb | 156 | blew away. 'git rerere' helps you resolve this final |
8389b52b JH |
157 | conflicted merge using the information from your earlier hand |
158 | resolve. | |
159 | ||
0b444cdb | 160 | Running the 'git rerere' command immediately after a conflicted |
8389b52b JH |
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, | |
0b444cdb | 164 | running 'git rerere' again will record the resolved state of these |
8389b52b JH |
165 | files. Suppose you did this when you created the test merge of |
166 | master into the topic branch. | |
167 | ||
c97038d1 | 168 | Next time, after seeing the same conflicted automerge, |
0b444cdb | 169 | running 'git rerere' will perform a three-way merge between the |
8389b52b | 170 | earlier conflicted automerge, the earlier manual resolution, and |
c97038d1 | 171 | the current conflicted automerge. |
8389b52b | 172 | If this three-way merge resolves cleanly, the result is written |
c97038d1 | 173 | out to your working tree file, so you do not have to manually |
0b444cdb | 174 | resolve it. Note that 'git rerere' leaves the index file alone, |
8389b52b | 175 | so you still need to do the final sanity checks with `git diff` |
0b444cdb | 176 | (or `git diff -c`) and 'git add' when you are satisfied. |
8389b52b | 177 | |
0b444cdb TR |
178 | As a convenience measure, 'git merge' automatically invokes |
179 | 'git rerere' upon exiting with a failed automerge and 'git rerere' | |
c97038d1 | 180 | records the hand resolve when it is a new conflict, or reuses the earlier hand |
0b444cdb | 181 | resolve when it is not. 'git commit' also invokes 'git rerere' |
c97038d1 SB |
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). | |
8389b52b | 185 | |
c97038d1 | 186 | In our example, when you do the test merge, the manual |
8389b52b | 187 | resolution is recorded, and it will be reused when you do the |
c97038d1 SB |
188 | actual merge later with the updated master and topic branch, as long |
189 | as the recorded resolution is still applicable. | |
8389b52b | 190 | |
0b444cdb TR |
191 | The information 'git rerere' records is also used when running |
192 | 'git rebase'. After blowing away the test merge and continuing | |
8389b52b JH |
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 | ||
c97038d1 | 207 | you could run `git rebase master topic`, to bring yourself |
7560f547 | 208 | up to date before your topic is ready to be sent upstream. |
c97038d1 SB |
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. | |
0b444cdb | 211 | 'git rerere' will be run by 'git rebase' to help you resolve this |
8389b52b JH |
212 | conflict. |
213 | ||
f427869b TG |
214 | [NOTE] 'git rerere' relies on the conflict markers in the file to |
215 | detect the conflict. If the file already contains lines that look the | |
216 | same as lines with conflict markers, 'git rerere' may fail to record a | |
217 | conflict resolution. To work around this, the `conflict-marker-size` | |
218 | setting in linkgit:gitattributes[5] can be used. | |
219 | ||
8389b52b JH |
220 | GIT |
221 | --- | |
9e1f0a85 | 222 | Part of the linkgit:git[1] suite |