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