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