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