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