git-rerere.txt: grammatical fixups and cleanups
[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
c97038d1
SB
15In a workflow employing relatively long lived topic branches,
16the developer sometimes needs to resolve the same conflicts over
8389b52b
JH
17and over again until the topic branches are done (either merged
18to the "release" branch, or sent out and accepted upstream).
19
c97038d1
SB
20This command assists the developer in this process by recording
21conflicted automerge results and corresponding hand resolve results
22on the initial manual merge, and applying previously recorded
23hand resolutions to their corresponding automerge results.
8389b52b 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
c97038d1
SB
57This prunes records of conflicted merges that
58occurred a long time ago. By default, unresolved conflicts older
59than 15 days and resolved conflicts older than 60
60days are pruned. These defaults are controlled via the
48c32424 61`gc.rerereunresolved` and `gc.rerereresolved` configuration
c97038d1 62variables respectively.
cda2d3c1
JH
63
64
8389b52b
JH
65DISCUSSION
66----------
67
c97038d1 68When your topic branch modifies an overlapping area that your
8389b52b
JH
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
c97038d1 143commits marked with `*`. However, this conflict is often the
8389b52b 144same conflict you resolved when you created the test merge you
c97038d1 145blew away. 'git-rerere' helps you 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,
c97038d1 153running 'git-rerere' again will record 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
c97038d1
SB
157Next time, after seeing the same conflicted automerge,
158running 'git-rerere' will perform a three-way merge between the
8389b52b 159earlier conflicted automerge, the earlier manual resolution, and
c97038d1 160the current conflicted automerge.
8389b52b 161If this three-way merge resolves cleanly, the result is written
c97038d1 162out to your working tree file, so you do not have to manually
ba020ef5 163resolve it. Note that 'git-rerere' leaves the index file alone,
8389b52b 164so you still need to do the final sanity checks with `git diff`
ba020ef5 165(or `git diff -c`) and 'git-add' when you are satisfied.
8389b52b 166
ba020ef5 167As a convenience measure, 'git-merge' automatically invokes
c97038d1
SB
168'git-rerere' upon exiting with a failed automerge and 'git-rerere'
169records the hand resolve when it is a new conflict, or reuses the earlier hand
ba020ef5 170resolve when it is not. 'git-commit' also invokes 'git-rerere'
c97038d1
SB
171when committing a merge result. What this means is that you do
172not have to do anything special yourself (besides enabling
173the rerere.enabled config variable).
8389b52b 174
c97038d1 175In our example, when you do the test merge, the manual
8389b52b 176resolution is recorded, and it will be reused when you do the
c97038d1
SB
177actual merge later with the updated master and topic branch, as long
178as the recorded resolution is still applicable.
8389b52b 179
ba020ef5
JN
180The information 'git-rerere' records is also used when running
181'git-rebase'. After blowing away the test merge and continuing
8389b52b
JH
182development on the topic branch:
183
184------------
185 o---*---o-------o---o topic
186 /
187 o---o---o---*---o---o---o---o master
188
189 $ git rebase master topic
190
191 o---*---o-------o---o topic
192 /
193 o---o---o---*---o---o---o---o master
194------------
195
c97038d1
SB
196you could run `git rebase master topic`, to bring yourself
197up-to-date before your topic is ready to be sent upstream.
198This would result in falling back to a three-way merge, and it
199would conflict the same way as the test merge you resolved earlier.
200'git-rerere' will be run by 'git-rebase' to help you resolve this
8389b52b
JH
201conflict.
202
203
204Author
205------
59eb68aa 206Written by Junio C Hamano <gitster@pobox.com>
8389b52b
JH
207
208GIT
209---
9e1f0a85 210Part of the linkgit:git[1] suite