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