Autogenerated HTML docs for v1.7.7-290-gc9e7aa
[git/jnareb-git.git] / git-rerere.html
blob789c15dbf903f6b82bd7e6a190c5166ccb9f2b78
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6 <meta name="generator" content="AsciiDoc 8.5.2" />
7 <title>git-rerere(1)</title>
8 <style type="text/css">
9 /* Debug borders */
10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
12 border: 1px solid red;
16 body {
17 margin: 1em 5% 1em 5%;
20 a {
21 color: blue;
22 text-decoration: underline;
24 a:visited {
25 color: fuchsia;
28 em {
29 font-style: italic;
30 color: navy;
33 strong {
34 font-weight: bold;
35 color: #083194;
38 tt {
39 color: navy;
42 h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
50 h1, h2, h3 {
51 border-bottom: 2px solid silver;
53 h2 {
54 padding-top: 0.5em;
56 h3 {
57 float: left;
59 h3 + * {
60 clear: left;
63 div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
68 hr {
69 border: 1px solid silver;
72 p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
77 ul, ol, li > p {
78 margin-top: 0;
81 pre {
82 padding: 0;
83 margin: 0;
86 span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
90 font-size: 1.1em;
92 span#email {
94 span#revnumber, span#revdate, span#revremark {
95 font-family: sans-serif;
98 div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
105 div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
109 div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
114 div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120 div.admonitionblock {
121 margin-top: 1.0em;
122 margin-bottom: 1.5em;
124 div.admonitionblock {
125 margin-top: 2.0em;
126 margin-bottom: 2.0em;
127 margin-right: 10%;
128 color: #606060;
131 div.content { /* Block element content. */
132 padding: 0;
135 /* Block element titles. */
136 div.title, caption.title {
137 color: #527bbd;
138 font-family: sans-serif;
139 font-weight: bold;
140 text-align: left;
141 margin-top: 1.0em;
142 margin-bottom: 0.5em;
144 div.title + * {
145 margin-top: 0;
148 td div.title:first-child {
149 margin-top: 0.0em;
151 div.content div.title:first-child {
152 margin-top: 0.0em;
154 div.content + div.title {
155 margin-top: 0.0em;
158 div.sidebarblock > div.content {
159 background: #ffffee;
160 border: 1px solid silver;
161 padding: 0.5em;
164 div.listingblock > div.content {
165 border: 1px solid silver;
166 background: #f4f4f4;
167 padding: 0.5em;
170 div.quoteblock, div.verseblock {
171 padding-left: 1.0em;
172 margin-left: 1.0em;
173 margin-right: 10%;
174 border-left: 5px solid #dddddd;
175 color: #777777;
178 div.quoteblock > div.attribution {
179 padding-top: 0.5em;
180 text-align: right;
183 div.verseblock > div.content {
184 white-space: pre;
186 div.verseblock > div.attribution {
187 padding-top: 0.75em;
188 text-align: left;
190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 div.verseblock + div.attribution {
192 text-align: left;
195 div.admonitionblock .icon {
196 vertical-align: top;
197 font-size: 1.1em;
198 font-weight: bold;
199 text-decoration: underline;
200 color: #527bbd;
201 padding-right: 0.5em;
203 div.admonitionblock td.content {
204 padding-left: 0.5em;
205 border-left: 3px solid #dddddd;
208 div.exampleblock > div.content {
209 border-left: 3px solid #dddddd;
210 padding-left: 0.5em;
213 div.imageblock div.content { padding-left: 0; }
214 span.image img { border-style: none; }
215 a.image:visited { color: white; }
217 dl {
218 margin-top: 0.8em;
219 margin-bottom: 0.8em;
221 dt {
222 margin-top: 0.5em;
223 margin-bottom: 0;
224 font-style: normal;
225 color: navy;
227 dd > *:first-child {
228 margin-top: 0.1em;
231 ul, ol {
232 list-style-position: outside;
234 ol.arabic {
235 list-style-type: decimal;
237 ol.loweralpha {
238 list-style-type: lower-alpha;
240 ol.upperalpha {
241 list-style-type: upper-alpha;
243 ol.lowerroman {
244 list-style-type: lower-roman;
246 ol.upperroman {
247 list-style-type: upper-roman;
250 div.compact ul, div.compact ol,
251 div.compact p, div.compact p,
252 div.compact div, div.compact div {
253 margin-top: 0.1em;
254 margin-bottom: 0.1em;
257 div.tableblock > table {
258 border: 3px solid #527bbd;
260 thead, p.table.header {
261 font-family: sans-serif;
262 font-weight: bold;
264 tfoot {
265 font-weight: bold;
267 td > div.verse {
268 white-space: pre;
270 p.table {
271 margin-top: 0;
273 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 div.tableblock > table[frame="void"] {
275 border-style: none;
277 div.tableblock > table[frame="hsides"] {
278 border-left-style: none;
279 border-right-style: none;
281 div.tableblock > table[frame="vsides"] {
282 border-top-style: none;
283 border-bottom-style: none;
287 div.hdlist {
288 margin-top: 0.8em;
289 margin-bottom: 0.8em;
291 div.hdlist tr {
292 padding-bottom: 15px;
294 dt.hdlist1.strong, td.hdlist1.strong {
295 font-weight: bold;
297 td.hdlist1 {
298 vertical-align: top;
299 font-style: normal;
300 padding-right: 0.8em;
301 color: navy;
303 td.hdlist2 {
304 vertical-align: top;
306 div.hdlist.compact tr {
307 margin: 0;
308 padding-bottom: 0;
311 .comment {
312 background: yellow;
315 .footnote, .footnoteref {
316 font-size: 0.8em;
319 span.footnote, span.footnoteref {
320 vertical-align: super;
323 #footnotes {
324 margin: 20px 0 20px 0;
325 padding: 7px 0 0 0;
328 #footnotes div.footnote {
329 margin: 0 0 5px 0;
332 #footnotes hr {
333 border: none;
334 border-top: 1px solid silver;
335 height: 1px;
336 text-align: left;
337 margin-left: 0;
338 width: 20%;
339 min-width: 100px;
343 @media print {
344 div#footer-badges { display: none; }
347 div#toc {
348 margin-bottom: 2.5em;
351 div#toctitle {
352 color: #527bbd;
353 font-family: sans-serif;
354 font-size: 1.1em;
355 font-weight: bold;
356 margin-top: 1.0em;
357 margin-bottom: 0.1em;
360 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
361 margin-top: 0;
362 margin-bottom: 0;
364 div.toclevel2 {
365 margin-left: 2em;
366 font-size: 0.9em;
368 div.toclevel3 {
369 margin-left: 4em;
370 font-size: 0.9em;
372 div.toclevel4 {
373 margin-left: 6em;
374 font-size: 0.9em;
376 /* Overrides for manpage documents */
377 h1 {
378 padding-top: 0.5em;
379 padding-bottom: 0.5em;
380 border-top: 2px solid silver;
381 border-bottom: 2px solid silver;
383 h2 {
384 border-style: none;
386 div.sectionbody {
387 margin-left: 5%;
390 @media print {
391 div#toc { display: none; }
394 /* Workarounds for IE6's broken and incomplete CSS2. */
396 div.sidebar-content {
397 background: #ffffee;
398 border: 1px solid silver;
399 padding: 0.5em;
401 div.sidebar-title, div.image-title {
402 color: #527bbd;
403 font-family: sans-serif;
404 font-weight: bold;
405 margin-top: 0.0em;
406 margin-bottom: 0.5em;
409 div.listingblock div.content {
410 border: 1px solid silver;
411 background: #f4f4f4;
412 padding: 0.5em;
415 div.quoteblock-attribution {
416 padding-top: 0.5em;
417 text-align: right;
420 div.verseblock-content {
421 white-space: pre;
423 div.verseblock-attribution {
424 padding-top: 0.75em;
425 text-align: left;
428 div.exampleblock-content {
429 border-left: 3px solid #dddddd;
430 padding-left: 0.5em;
433 /* IE6 sets dynamically generated links as visited. */
434 div#toc a:visited { color: blue; }
435 </style>
436 <script type="text/javascript">
437 /*<![CDATA[*/
438 window.onload = function(){asciidoc.footnotes();}
439 var asciidoc = { // Namespace.
441 /////////////////////////////////////////////////////////////////////
442 // Table Of Contents generator
443 /////////////////////////////////////////////////////////////////////
445 /* Author: Mihai Bazon, September 2002
446 * http://students.infoiasi.ro/~mishoo
448 * Table Of Content generator
449 * Version: 0.4
451 * Feel free to use this script under the terms of the GNU General Public
452 * License, as long as you do not remove or alter this notice.
455 /* modified by Troy D. Hanson, September 2006. License: GPL */
456 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
458 // toclevels = 1..4.
459 toc: function (toclevels) {
461 function getText(el) {
462 var text = "";
463 for (var i = el.firstChild; i != null; i = i.nextSibling) {
464 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
465 text += i.data;
466 else if (i.firstChild != null)
467 text += getText(i);
469 return text;
472 function TocEntry(el, text, toclevel) {
473 this.element = el;
474 this.text = text;
475 this.toclevel = toclevel;
478 function tocEntries(el, toclevels) {
479 var result = new Array;
480 var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
481 // Function that scans the DOM tree for header elements (the DOM2
482 // nodeIterator API would be a better technique but not supported by all
483 // browsers).
484 var iterate = function (el) {
485 for (var i = el.firstChild; i != null; i = i.nextSibling) {
486 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
487 var mo = re.exec(i.tagName);
488 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
489 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
491 iterate(i);
495 iterate(el);
496 return result;
499 var toc = document.getElementById("toc");
500 var entries = tocEntries(document.getElementById("content"), toclevels);
501 for (var i = 0; i < entries.length; ++i) {
502 var entry = entries[i];
503 if (entry.element.id == "")
504 entry.element.id = "_toc_" + i;
505 var a = document.createElement("a");
506 a.href = "#" + entry.element.id;
507 a.appendChild(document.createTextNode(entry.text));
508 var div = document.createElement("div");
509 div.appendChild(a);
510 div.className = "toclevel" + entry.toclevel;
511 toc.appendChild(div);
513 if (entries.length == 0)
514 toc.parentNode.removeChild(toc);
518 /////////////////////////////////////////////////////////////////////
519 // Footnotes generator
520 /////////////////////////////////////////////////////////////////////
522 /* Based on footnote generation code from:
523 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
526 footnotes: function () {
527 var cont = document.getElementById("content");
528 var noteholder = document.getElementById("footnotes");
529 var spans = cont.getElementsByTagName("span");
530 var refs = {};
531 var n = 0;
532 for (i=0; i<spans.length; i++) {
533 if (spans[i].className == "footnote") {
534 n++;
535 // Use [\s\S] in place of . so multi-line matches work.
536 // Because JavaScript has no s (dotall) regex flag.
537 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
538 noteholder.innerHTML +=
539 "<div class='footnote' id='_footnote_" + n + "'>" +
540 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
541 n + "</a>. " + note + "</div>";
542 spans[i].innerHTML =
543 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
544 "' title='View footnote' class='footnote'>" + n + "</a>]";
545 var id =spans[i].getAttribute("id");
546 if (id != null) refs["#"+id] = n;
549 if (n == 0)
550 noteholder.parentNode.removeChild(noteholder);
551 else {
552 // Process footnoterefs.
553 for (i=0; i<spans.length; i++) {
554 if (spans[i].className == "footnoteref") {
555 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
556 href = href.match(/#.*/)[0]; // Because IE return full URL.
557 n = refs[href];
558 spans[i].innerHTML =
559 "[<a href='#_footnote_" + n +
560 "' title='View footnote' class='footnote'>" + n + "</a>]";
567 /*]]>*/
568 </script>
569 </head>
570 <body>
571 <div id="header">
572 <h1>
573 git-rerere(1) Manual Page
574 </h1>
575 <h2>NAME</h2>
576 <div class="sectionbody">
577 <p>git-rerere -
578 Reuse recorded resolution of conflicted merges
579 </p>
580 </div>
581 </div>
582 <div id="content">
583 <h2 id="_synopsis">SYNOPSIS</h2>
584 <div class="sectionbody">
585 <div class="verseblock">
586 <div class="verseblock-content"><em>git rerere</em> [<em>clear</em>|<em>forget</em> &lt;pathspec&gt;|<em>diff</em>|<em>status</em>|<em>gc</em>]</div>
587 <div class="verseblock-attribution">
588 </div></div>
589 </div>
590 <h2 id="_description">DESCRIPTION</h2>
591 <div class="sectionbody">
592 <div class="paragraph"><p>In a workflow employing relatively long lived topic branches,
593 the developer sometimes needs to resolve the same conflicts over
594 and over again until the topic branches are done (either merged
595 to the "release" branch, or sent out and accepted upstream).</p></div>
596 <div class="paragraph"><p>This command assists the developer in this process by recording
597 conflicted automerge results and corresponding hand resolve results
598 on the initial manual merge, and applying previously recorded
599 hand resolutions to their corresponding automerge results.</p></div>
600 <div class="admonitionblock">
601 <table><tr>
602 <td class="icon">
603 <div class="title">Note</div>
604 </td>
605 <td class="content">You need to set the configuration variable rerere.enabled in order to
606 enable this command.</td>
607 </tr></table>
608 </div>
609 </div>
610 <h2 id="_commands">COMMANDS</h2>
611 <div class="sectionbody">
612 <div class="paragraph"><p>Normally, <em>git rerere</em> is run without arguments or user-intervention.
613 However, it has several commands that allow it to interact with
614 its working state.</p></div>
615 <div class="dlist"><dl>
616 <dt class="hdlist1">
617 <em>clear</em>
618 </dt>
619 <dd>
621 This resets the metadata used by rerere if a merge resolution is to be
622 aborted. Calling <em>git am [--skip|--abort]</em> or <em>git rebase [--skip|--abort]</em>
623 will automatically invoke this command.
624 </p>
625 </dd>
626 <dt class="hdlist1">
627 <em>forget</em> &lt;pathspec&gt;
628 </dt>
629 <dd>
631 This resets the conflict resolutions which rerere has recorded for the current
632 conflict in &lt;pathspec&gt;.
633 </p>
634 </dd>
635 <dt class="hdlist1">
636 <em>diff</em>
637 </dt>
638 <dd>
640 This displays diffs for the current state of the resolution. It is
641 useful for tracking what has changed while the user is resolving
642 conflicts. Additional arguments are passed directly to the system
643 <em>diff</em> command installed in PATH.
644 </p>
645 </dd>
646 <dt class="hdlist1">
647 <em>status</em>
648 </dt>
649 <dd>
651 Like <em>diff</em>, but this only prints the filenames that will be tracked
652 for resolutions.
653 </p>
654 </dd>
655 <dt class="hdlist1">
656 <em>gc</em>
657 </dt>
658 <dd>
660 This prunes records of conflicted merges that
661 occurred a long time ago. By default, unresolved conflicts older
662 than 15 days and resolved conflicts older than 60
663 days are pruned. These defaults are controlled via the
664 <tt>gc.rerereunresolved</tt> and <tt>gc.rerereresolved</tt> configuration
665 variables respectively.
666 </p>
667 </dd>
668 </dl></div>
669 </div>
670 <h2 id="_discussion">DISCUSSION</h2>
671 <div class="sectionbody">
672 <div class="paragraph"><p>When your topic branch modifies an overlapping area that your
673 master branch (or upstream) touched since your topic branch
674 forked from it, you may want to test it with the latest master,
675 even before your topic branch is ready to be pushed upstream:</p></div>
676 <div class="listingblock">
677 <div class="content">
678 <pre><tt> o---*---o topic
680 o---o---o---*---o---o master</tt></pre>
681 </div></div>
682 <div class="paragraph"><p>For such a test, you need to merge master and topic somehow.
683 One way to do it is to pull master into the topic branch:</p></div>
684 <div class="listingblock">
685 <div class="content">
686 <pre><tt> $ git checkout topic
687 $ git merge master
689 o---*---o---+ topic
691 o---o---o---*---o---o master</tt></pre>
692 </div></div>
693 <div class="paragraph"><p>The commits marked with <tt>*</tt> touch the same area in the same
694 file; you need to resolve the conflicts when creating the commit
695 marked with <tt>&#43;</tt>. Then you can test the result to make sure your
696 work-in-progress still works with what is in the latest master.</p></div>
697 <div class="paragraph"><p>After this test merge, there are two ways to continue your work
698 on the topic. The easiest is to build on top of the test merge
699 commit <tt>&#43;</tt>, and when your work in the topic branch is finally
700 ready, pull the topic branch into master, and/or ask the
701 upstream to pull from you. By that time, however, the master or
702 the upstream might have been advanced since the test merge <tt>&#43;</tt>,
703 in which case the final commit graph would look like this:</p></div>
704 <div class="listingblock">
705 <div class="content">
706 <pre><tt> $ git checkout topic
707 $ git merge master
708 $ ... work on both topic and master branches
709 $ git checkout master
710 $ git merge topic
712 o---*---o---+---o---o topic
713 / / \
714 o---o---o---*---o---o---o---o---+ master</tt></pre>
715 </div></div>
716 <div class="paragraph"><p>When your topic branch is long-lived, however, your topic branch
717 would end up having many such "Merge from master" commits on it,
718 which would unnecessarily clutter the development history.
719 Readers of the Linux kernel mailing list may remember that Linus
720 complained about such too frequent test merges when a subsystem
721 maintainer asked to pull from a branch full of "useless merges".</p></div>
722 <div class="paragraph"><p>As an alternative, to keep the topic branch clean of test
723 merges, you could blow away the test merge, and keep building on
724 top of the tip before the test merge:</p></div>
725 <div class="listingblock">
726 <div class="content">
727 <pre><tt> $ git checkout topic
728 $ git merge master
729 $ git reset --hard HEAD^ ;# rewind the test merge
730 $ ... work on both topic and master branches
731 $ git checkout master
732 $ git merge topic
734 o---*---o-------o---o topic
736 o---o---o---*---o---o---o---o---+ master</tt></pre>
737 </div></div>
738 <div class="paragraph"><p>This would leave only one merge commit when your topic branch is
739 finally ready and merged into the master branch. This merge
740 would require you to resolve the conflict, introduced by the
741 commits marked with <tt>*</tt>. However, this conflict is often the
742 same conflict you resolved when you created the test merge you
743 blew away. <em>git rerere</em> helps you resolve this final
744 conflicted merge using the information from your earlier hand
745 resolve.</p></div>
746 <div class="paragraph"><p>Running the <em>git rerere</em> command immediately after a conflicted
747 automerge records the conflicted working tree files, with the
748 usual conflict markers <tt>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</tt>, <tt>=======</tt>, and <tt>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</tt> in
749 them. Later, after you are done resolving the conflicts,
750 running <em>git rerere</em> again will record the resolved state of these
751 files. Suppose you did this when you created the test merge of
752 master into the topic branch.</p></div>
753 <div class="paragraph"><p>Next time, after seeing the same conflicted automerge,
754 running <em>git rerere</em> will perform a three-way merge between the
755 earlier conflicted automerge, the earlier manual resolution, and
756 the current conflicted automerge.
757 If this three-way merge resolves cleanly, the result is written
758 out to your working tree file, so you do not have to manually
759 resolve it. Note that <em>git rerere</em> leaves the index file alone,
760 so you still need to do the final sanity checks with <tt>git diff</tt>
761 (or <tt>git diff -c</tt>) and <em>git add</em> when you are satisfied.</p></div>
762 <div class="paragraph"><p>As a convenience measure, <em>git merge</em> automatically invokes
763 <em>git rerere</em> upon exiting with a failed automerge and <em>git rerere</em>
764 records the hand resolve when it is a new conflict, or reuses the earlier hand
765 resolve when it is not. <em>git commit</em> also invokes <em>git rerere</em>
766 when committing a merge result. What this means is that you do
767 not have to do anything special yourself (besides enabling
768 the rerere.enabled config variable).</p></div>
769 <div class="paragraph"><p>In our example, when you do the test merge, the manual
770 resolution is recorded, and it will be reused when you do the
771 actual merge later with the updated master and topic branch, as long
772 as the recorded resolution is still applicable.</p></div>
773 <div class="paragraph"><p>The information <em>git rerere</em> records is also used when running
774 <em>git rebase</em>. After blowing away the test merge and continuing
775 development on the topic branch:</p></div>
776 <div class="listingblock">
777 <div class="content">
778 <pre><tt> o---*---o-------o---o topic
780 o---o---o---*---o---o---o---o master
782 $ git rebase master topic
784 o---*---o-------o---o topic
786 o---o---o---*---o---o---o---o master</tt></pre>
787 </div></div>
788 <div class="paragraph"><p>you could run <tt>git rebase master topic</tt>, to bring yourself
789 up-to-date before your topic is ready to be sent upstream.
790 This would result in falling back to a three-way merge, and it
791 would conflict the same way as the test merge you resolved earlier.
792 <em>git rerere</em> will be run by <em>git rebase</em> to help you resolve this
793 conflict.</p></div>
794 </div>
795 <h2 id="_git">GIT</h2>
796 <div class="sectionbody">
797 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
798 </div>
799 </div>
800 <div id="footnotes"><hr /></div>
801 <div id="footer">
802 <div id="footer-text">
803 Last updated 2011-09-21 23:01:14 PDT
804 </div>
805 </div>
806 </body>
807 </html>