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