git log documentation: teach -<n> form.
[git/git.git] / Documentation / git-rerere.txt
CommitLineData
8389b52b
JH
1git-rerere(1)
2=============
3
4NAME
5----
6git-rerere - Reuse recorded resolve
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
25[NOTE]
26You need to create `$GIT_DIR/rr-cache` directory to enable this
27command.
28
cda2d3c1
JH
29
30COMMANDS
31--------
32
33Normally, git-rerere is run without arguments or user-intervention.
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
40is aborted. Calling gitlink:git-am[1] --skip or gitlink:git-rebase[1]
41[--skip|--abort] will automatcally invoke this command.
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
48diff(1) command installed in PATH.
49
50'status'::
51
52Like diff, but this only prints the filenames that will be tracked
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
84 $ git pull . master
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
93marked with `+`. Then you can test the result to make sure your
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
98commit `+`, and when your work in the topic branch is finally
99ready, pull the topic branch into master, and/or ask the
100upstream to pull from you. By that time, however, the master or
101the upstream might have been advanced since the test merge `+`,
102in which case the final commit graph would look like this:
103
104------------
105 $ git checkout topic
106 $ git pull . master
107 $ ... work on both topic and master branches
108 $ git checkout master
109 $ git pull . topic
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
129 $ git pull . master
130 $ git reset --hard HEAD^ ;# rewind the test merge
131 $ ... work on both topic and master branches
132 $ git checkout master
133 $ git pull . topic
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
145blew away. `git-rerere` command helps you to resolve this final
146conflicted merge using the information from your earlier hand
147resolve.
148
149Running `git-rerere` command immediately after a conflicted
150automerge records the conflicted working tree files, with the
151usual conflict markers `<<<<<<<`, `=======`, and `>>>>>>>` in
152them. Later, after you are done resolving the conflicts,
153running `git-rerere` again records the resolved state of these
154files. Suppose you did this when you created the test merge of
155master into the topic branch.
156
157Next time, running `git-rerere` after seeing a conflicted
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
164resolve it. Note that `git-rerere` leaves the index file alone,
165so you still need to do the final sanity checks with `git diff`
166(or `git diff -c`) and `git update-index` when you are
167satisfied.
168
169As a convenience measure, `git-merge` automatically invokes
170`git-rerere` when it exits with a failed automerge, which
171records it if it is a new conflict, or reuses the earlier hand
172resolve when it is not. `git-commit` also invokes `git-rerere`
173when recording a merge result. What this means is that you do
174not have to do anything special yourself (Note: you still have
175to create `$GIT_DIR/rr-cache` directory to enable this command).
176
177In our example, when you did the test merge, the manual
178resolution is recorded, and it will be reused when you do the
179actual merge later with updated master and topic branch, as long
180as the earlier resolution is still applicable.
181
182The information `git-rerere` records is also used when running
183`git-rebase`. After blowing away the test merge and continuing
184development on the topic branch:
185
186------------
187 o---*---o-------o---o topic
188 /
189 o---o---o---*---o---o---o---o master
190
191 $ git rebase master topic
192
193 o---*---o-------o---o topic
194 /
195 o---o---o---*---o---o---o---o master
196------------
197
198you could run `git rebase master topic`, to keep yourself
199up-to-date even before your topic is ready to be sent upstream.
200This would result in falling back to three-way merge, and it
201would conflict the same way the test merge you resolved earlier.
202`git-rerere` is run by `git rebase` to help you resolve this
203conflict.
204
205
206Author
207------
208Written by Junio C Hamano <junkio@cox.net>
209
210GIT
211---
212Part of the gitlink:git[7] suite