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