Google Git
Sign in
chromium / external / gitster / git-htmldocs / a65c1f44a0fb82bf498be0911b85fa42bb70147f / . / git-worktree.html
blob: 81913b9943dec62dd8aeb52114d9024edc1a9930 [file] [log] [blame]
Junio C Hamano96153bf2018-04-25 08:25:34[diff] [blame]1<?xml version="1.0" encoding="UTF-8"?>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
3 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
5<head>
6<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
Junio C Hamano98c882d2020-08-13 22:06:57[diff] [blame]7<meta name="generator" content="AsciiDoc 9.0.0rc2" />
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]8<title>git-worktree(1)</title>
9<style type="text/css">
10/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
11
12/* Default font. */
13body {
14 font-family: Georgia,serif;
15}
16
17/* Title font. */
18h1, h2, h3, h4, h5, h6,
19div.title, caption.title,
20thead, p.table.header,
21#toctitle,
22#author, #revnumber, #revdate, #revremark,
23#footer {
24 font-family: Arial,Helvetica,sans-serif;
25}
26
27body {
28 margin: 1em 5% 1em 5%;
29}
30
31a {
32 color: blue;
33 text-decoration: underline;
34}
35a:visited {
36 color: fuchsia;
37}
38
39em {
40 font-style: italic;
41 color: navy;
42}
43
44strong {
45 font-weight: bold;
46 color: #083194;
47}
48
49h1, h2, h3, h4, h5, h6 {
50 color: #527bbd;
51 margin-top: 1.2em;
52 margin-bottom: 0.5em;
53 line-height: 1.3;
54}
55
56h1, h2, h3 {
57 border-bottom: 2px solid silver;
58}
59h2 {
60 padding-top: 0.5em;
61}
62h3 {
63 float: left;
64}
65h3 + * {
66 clear: left;
67}
68h5 {
69 font-size: 1.0em;
70}
71
72div.sectionbody {
73 margin-left: 0;
74}
75
76hr {
77 border: 1px solid silver;
78}
79
80p {
81 margin-top: 0.5em;
82 margin-bottom: 0.5em;
83}
84
85ul, ol, li > p {
86 margin-top: 0;
87}
88ul > li { color: #aaa; }
89ul > li > * { color: black; }
90
91.monospaced, code, pre {
92 font-family: "Courier New", Courier, monospace;
93 font-size: inherit;
94 color: navy;
95 padding: 0;
96 margin: 0;
97}
98pre {
99 white-space: pre-wrap;
100}
101
102#author {
103 color: #527bbd;
104 font-weight: bold;
105 font-size: 1.1em;
106}
107#email {
108}
109#revnumber, #revdate, #revremark {
110}
111
112#footer {
113 font-size: small;
114 border-top: 2px solid silver;
115 padding-top: 0.5em;
116 margin-top: 4.0em;
117}
118#footer-text {
119 float: left;
120 padding-bottom: 0.5em;
121}
122#footer-badges {
123 float: right;
124 padding-bottom: 0.5em;
125}
126
127#preamble {
128 margin-top: 1.5em;
129 margin-bottom: 1.5em;
130}
131div.imageblock, div.exampleblock, div.verseblock,
132div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
133div.admonitionblock {
134 margin-top: 1.0em;
135 margin-bottom: 1.5em;
136}
137div.admonitionblock {
138 margin-top: 2.0em;
139 margin-bottom: 2.0em;
140 margin-right: 10%;
141 color: #606060;
142}
143
144div.content { /* Block element content. */
145 padding: 0;
146}
147
148/* Block element titles. */
149div.title, caption.title {
150 color: #527bbd;
151 font-weight: bold;
152 text-align: left;
153 margin-top: 1.0em;
154 margin-bottom: 0.5em;
155}
156div.title + * {
157 margin-top: 0;
158}
159
160td div.title:first-child {
161 margin-top: 0.0em;
162}
163div.content div.title:first-child {
164 margin-top: 0.0em;
165}
166div.content + div.title {
167 margin-top: 0.0em;
168}
169
170div.sidebarblock > div.content {
171 background: #ffffee;
172 border: 1px solid #dddddd;
173 border-left: 4px solid #f0f0f0;
174 padding: 0.5em;
175}
176
177div.listingblock > div.content {
178 border: 1px solid #dddddd;
179 border-left: 5px solid #f0f0f0;
180 background: #f8f8f8;
181 padding: 0.5em;
182}
183
184div.quoteblock, div.verseblock {
185 padding-left: 1.0em;
186 margin-left: 1.0em;
187 margin-right: 10%;
188 border-left: 5px solid #f0f0f0;
189 color: #888;
190}
191
192div.quoteblock > div.attribution {
193 padding-top: 0.5em;
194 text-align: right;
195}
196
197div.verseblock > pre.content {
198 font-family: inherit;
199 font-size: inherit;
200}
201div.verseblock > div.attribution {
202 padding-top: 0.75em;
203 text-align: left;
204}
205/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
206div.verseblock + div.attribution {
207 text-align: left;
208}
209
210div.admonitionblock .icon {
211 vertical-align: top;
212 font-size: 1.1em;
213 font-weight: bold;
214 text-decoration: underline;
215 color: #527bbd;
216 padding-right: 0.5em;
217}
218div.admonitionblock td.content {
219 padding-left: 0.5em;
220 border-left: 3px solid #dddddd;
221}
222
223div.exampleblock > div.content {
224 border-left: 3px solid #dddddd;
225 padding-left: 0.5em;
226}
227
228div.imageblock div.content { padding-left: 0; }
229span.image img { border-style: none; vertical-align: text-bottom; }
230a.image:visited { color: white; }
231
232dl {
233 margin-top: 0.8em;
234 margin-bottom: 0.8em;
235}
236dt {
237 margin-top: 0.5em;
238 margin-bottom: 0;
239 font-style: normal;
240 color: navy;
241}
242dd > *:first-child {
243 margin-top: 0.1em;
244}
245
246ul, ol {
247 list-style-position: outside;
248}
249ol.arabic {
250 list-style-type: decimal;
251}
252ol.loweralpha {
253 list-style-type: lower-alpha;
254}
255ol.upperalpha {
256 list-style-type: upper-alpha;
257}
258ol.lowerroman {
259 list-style-type: lower-roman;
260}
261ol.upperroman {
262 list-style-type: upper-roman;
263}
264
265div.compact ul, div.compact ol,
266div.compact p, div.compact p,
267div.compact div, div.compact div {
268 margin-top: 0.1em;
269 margin-bottom: 0.1em;
270}
271
272tfoot {
273 font-weight: bold;
274}
275td > div.verse {
276 white-space: pre;
277}
278
279div.hdlist {
280 margin-top: 0.8em;
281 margin-bottom: 0.8em;
282}
283div.hdlist tr {
284 padding-bottom: 15px;
285}
286dt.hdlist1.strong, td.hdlist1.strong {
287 font-weight: bold;
288}
289td.hdlist1 {
290 vertical-align: top;
291 font-style: normal;
292 padding-right: 0.8em;
293 color: navy;
294}
295td.hdlist2 {
296 vertical-align: top;
297}
298div.hdlist.compact tr {
299 margin: 0;
300 padding-bottom: 0;
301}
302
303.comment {
304 background: yellow;
305}
306
307.footnote, .footnoteref {
308 font-size: 0.8em;
309}
310
311span.footnote, span.footnoteref {
312 vertical-align: super;
313}
314
315#footnotes {
316 margin: 20px 0 20px 0;
317 padding: 7px 0 0 0;
318}
319
320#footnotes div.footnote {
321 margin: 0 0 5px 0;
322}
323
324#footnotes hr {
325 border: none;
326 border-top: 1px solid silver;
327 height: 1px;
328 text-align: left;
329 margin-left: 0;
330 width: 20%;
331 min-width: 100px;
332}
333
334div.colist td {
335 padding-right: 0.5em;
336 padding-bottom: 0.3em;
337 vertical-align: top;
338}
339div.colist td img {
340 margin-top: 0.3em;
341}
342
343@media print {
344 #footer-badges { display: none; }
345}
346
347#toc {
348 margin-bottom: 2.5em;
349}
350
351#toctitle {
352 color: #527bbd;
353 font-size: 1.1em;
354 font-weight: bold;
355 margin-top: 1.0em;
356 margin-bottom: 0.1em;
357}
358
359div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
360 margin-top: 0;
361 margin-bottom: 0;
362}
363div.toclevel2 {
364 margin-left: 2em;
365 font-size: 0.9em;
366}
367div.toclevel3 {
368 margin-left: 4em;
369 font-size: 0.9em;
370}
371div.toclevel4 {
372 margin-left: 6em;
373 font-size: 0.9em;
374}
375
376span.aqua { color: aqua; }
377span.black { color: black; }
378span.blue { color: blue; }
379span.fuchsia { color: fuchsia; }
380span.gray { color: gray; }
381span.green { color: green; }
382span.lime { color: lime; }
383span.maroon { color: maroon; }
384span.navy { color: navy; }
385span.olive { color: olive; }
386span.purple { color: purple; }
387span.red { color: red; }
388span.silver { color: silver; }
389span.teal { color: teal; }
390span.white { color: white; }
391span.yellow { color: yellow; }
392
393span.aqua-background { background: aqua; }
394span.black-background { background: black; }
395span.blue-background { background: blue; }
396span.fuchsia-background { background: fuchsia; }
397span.gray-background { background: gray; }
398span.green-background { background: green; }
399span.lime-background { background: lime; }
400span.maroon-background { background: maroon; }
401span.navy-background { background: navy; }
402span.olive-background { background: olive; }
403span.purple-background { background: purple; }
404span.red-background { background: red; }
405span.silver-background { background: silver; }
406span.teal-background { background: teal; }
407span.white-background { background: white; }
408span.yellow-background { background: yellow; }
409
410span.big { font-size: 2em; }
411span.small { font-size: 0.6em; }
412
413span.underline { text-decoration: underline; }
414span.overline { text-decoration: overline; }
415span.line-through { text-decoration: line-through; }
416
417div.unbreakable { page-break-inside: avoid; }
418
419
420/*
421 * xhtml11 specific
422 *
423 * */
424
425div.tableblock {
426 margin-top: 1.0em;
427 margin-bottom: 1.5em;
428}
429div.tableblock > table {
430 border: 3px solid #527bbd;
431}
432thead, p.table.header {
433 font-weight: bold;
434 color: #527bbd;
435}
436p.table {
437 margin-top: 0;
438}
Junio C Hamano725b0da2020-01-22 22:02:40[diff] [blame]439/* Because the table frame attribute is overridden by CSS in most browsers. */
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]440div.tableblock > table[frame="void"] {
441 border-style: none;
442}
443div.tableblock > table[frame="hsides"] {
444 border-left-style: none;
445 border-right-style: none;
446}
447div.tableblock > table[frame="vsides"] {
448 border-top-style: none;
449 border-bottom-style: none;
450}
451
452
453/*
454 * html5 specific
455 *
456 * */
457
458table.tableblock {
459 margin-top: 1.0em;
460 margin-bottom: 1.5em;
461}
462thead, p.tableblock.header {
463 font-weight: bold;
464 color: #527bbd;
465}
466p.tableblock {
467 margin-top: 0;
468}
469table.tableblock {
470 border-width: 3px;
471 border-spacing: 0px;
472 border-style: solid;
473 border-color: #527bbd;
474 border-collapse: collapse;
475}
476th.tableblock, td.tableblock {
477 border-width: 1px;
478 padding: 4px;
479 border-style: solid;
480 border-color: #527bbd;
481}
482
483table.tableblock.frame-topbot {
484 border-left-style: hidden;
485 border-right-style: hidden;
486}
487table.tableblock.frame-sides {
488 border-top-style: hidden;
489 border-bottom-style: hidden;
490}
491table.tableblock.frame-none {
492 border-style: hidden;
493}
494
495th.tableblock.halign-left, td.tableblock.halign-left {
496 text-align: left;
497}
498th.tableblock.halign-center, td.tableblock.halign-center {
499 text-align: center;
500}
501th.tableblock.halign-right, td.tableblock.halign-right {
502 text-align: right;
503}
504
505th.tableblock.valign-top, td.tableblock.valign-top {
506 vertical-align: top;
507}
508th.tableblock.valign-middle, td.tableblock.valign-middle {
509 vertical-align: middle;
510}
511th.tableblock.valign-bottom, td.tableblock.valign-bottom {
512 vertical-align: bottom;
513}
514
515
516/*
517 * manpage specific
518 *
519 * */
520
521body.manpage h1 {
522 padding-top: 0.5em;
523 padding-bottom: 0.5em;
524 border-top: 2px solid silver;
525 border-bottom: 2px solid silver;
526}
527body.manpage h2 {
528 border-style: none;
529}
530body.manpage div.sectionbody {
531 margin-left: 3em;
532}
533
534@media print {
535 body.manpage div#toc { display: none; }
536}
537
538
539</style>
540<script type="text/javascript">
541/*<![CDATA[*/
542var asciidoc = { // Namespace.
543
544/////////////////////////////////////////////////////////////////////
545// Table Of Contents generator
546/////////////////////////////////////////////////////////////////////
547
548/* Author: Mihai Bazon, September 2002
549 * http://students.infoiasi.ro/~mishoo
550 *
551 * Table Of Content generator
552 * Version: 0.4
553 *
554 * Feel free to use this script under the terms of the GNU General Public
555 * License, as long as you do not remove or alter this notice.
556 */
557
558 /* modified by Troy D. Hanson, September 2006. License: GPL */
559 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
560
561// toclevels = 1..4.
562toc: function (toclevels) {
563
564 function getText(el) {
565 var text = "";
566 for (var i = el.firstChild; i != null; i = i.nextSibling) {
567 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
568 text += i.data;
569 else if (i.firstChild != null)
570 text += getText(i);
571 }
572 return text;
573 }
574
575 function TocEntry(el, text, toclevel) {
576 this.element = el;
577 this.text = text;
578 this.toclevel = toclevel;
579 }
580
581 function tocEntries(el, toclevels) {
582 var result = new Array;
583 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
584 // Function that scans the DOM tree for header elements (the DOM2
585 // nodeIterator API would be a better technique but not supported by all
586 // browsers).
587 var iterate = function (el) {
588 for (var i = el.firstChild; i != null; i = i.nextSibling) {
589 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
590 var mo = re.exec(i.tagName);
591 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
592 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
593 }
594 iterate(i);
595 }
596 }
597 }
598 iterate(el);
599 return result;
600 }
601
602 var toc = document.getElementById("toc");
603 if (!toc) {
604 return;
605 }
606
607 // Delete existing TOC entries in case we're reloading the TOC.
608 var tocEntriesToRemove = [];
609 var i;
610 for (i = 0; i < toc.childNodes.length; i++) {
611 var entry = toc.childNodes[i];
612 if (entry.nodeName.toLowerCase() == 'div'
613 && entry.getAttribute("class")
614 && entry.getAttribute("class").match(/^toclevel/))
615 tocEntriesToRemove.push(entry);
616 }
617 for (i = 0; i < tocEntriesToRemove.length; i++) {
618 toc.removeChild(tocEntriesToRemove[i]);
619 }
620
621 // Rebuild TOC entries.
622 var entries = tocEntries(document.getElementById("content"), toclevels);
623 for (var i = 0; i < entries.length; ++i) {
624 var entry = entries[i];
625 if (entry.element.id == "")
626 entry.element.id = "_toc_" + i;
627 var a = document.createElement("a");
628 a.href = "#" + entry.element.id;
629 a.appendChild(document.createTextNode(entry.text));
630 var div = document.createElement("div");
631 div.appendChild(a);
632 div.className = "toclevel" + entry.toclevel;
633 toc.appendChild(div);
634 }
635 if (entries.length == 0)
636 toc.parentNode.removeChild(toc);
637},
638
639
640/////////////////////////////////////////////////////////////////////
641// Footnotes generator
642/////////////////////////////////////////////////////////////////////
643
644/* Based on footnote generation code from:
645 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
646 */
647
648footnotes: function () {
649 // Delete existing footnote entries in case we're reloading the footnodes.
650 var i;
651 var noteholder = document.getElementById("footnotes");
652 if (!noteholder) {
653 return;
654 }
655 var entriesToRemove = [];
656 for (i = 0; i < noteholder.childNodes.length; i++) {
657 var entry = noteholder.childNodes[i];
658 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
659 entriesToRemove.push(entry);
660 }
661 for (i = 0; i < entriesToRemove.length; i++) {
662 noteholder.removeChild(entriesToRemove[i]);
663 }
664
665 // Rebuild footnote entries.
666 var cont = document.getElementById("content");
667 var spans = cont.getElementsByTagName("span");
668 var refs = {};
669 var n = 0;
670 for (i=0; i<spans.length; i++) {
671 if (spans[i].className == "footnote") {
672 n++;
673 var note = spans[i].getAttribute("data-note");
674 if (!note) {
675 // Use [\s\S] in place of . so multi-line matches work.
676 // Because JavaScript has no s (dotall) regex flag.
677 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
678 spans[i].innerHTML =
679 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
680 "' title='View footnote' class='footnote'>" + n + "</a>]";
681 spans[i].setAttribute("data-note", note);
682 }
683 noteholder.innerHTML +=
684 "<div class='footnote' id='_footnote_" + n + "'>" +
685 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
686 n + "</a>. " + note + "</div>";
687 var id =spans[i].getAttribute("id");
688 if (id != null) refs["#"+id] = n;
689 }
690 }
691 if (n == 0)
692 noteholder.parentNode.removeChild(noteholder);
693 else {
694 // Process footnoterefs.
695 for (i=0; i<spans.length; i++) {
696 if (spans[i].className == "footnoteref") {
697 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
698 href = href.match(/#.*/)[0]; // Because IE return full URL.
699 n = refs[href];
700 spans[i].innerHTML =
701 "[<a href='#_footnote_" + n +
702 "' title='View footnote' class='footnote'>" + n + "</a>]";
703 }
704 }
705 }
706},
707
708install: function(toclevels) {
709 var timerId;
710
711 function reinstall() {
712 asciidoc.footnotes();
713 if (toclevels) {
714 asciidoc.toc(toclevels);
715 }
716 }
717
718 function reinstallAndRemoveTimer() {
719 clearInterval(timerId);
720 reinstall();
721 }
722
723 timerId = setInterval(reinstall, 500);
724 if (document.addEventListener)
725 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
726 else
727 window.onload = reinstallAndRemoveTimer;
728}
729
730}
731asciidoc.install();
732/*]]>*/
733</script>
734</head>
735<body class="manpage">
736<div id="header">
737<h1>
738git-worktree(1) Manual Page
739</h1>
740<h2>NAME</h2>
741<div class="sectionbody">
742<p>git-worktree -
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]743 Manage multiple working trees
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]744</p>
745</div>
746</div>
747<div id="content">
748<div class="sect1">
749<h2 id="_synopsis">SYNOPSIS</h2>
750<div class="sectionbody">
751<div class="verseblock">
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]752<pre class="content"><em>git worktree add</em> [-f] [--detach] [--checkout] [--lock] [-b &lt;new-branch&gt;] &lt;path&gt; [&lt;commit-ish&gt;]
Junio C Hamanoc6c919b2016-07-06 21:34:15[diff] [blame]753<em>git worktree list</em> [--porcelain]
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]754<em>git worktree lock</em> [--reason &lt;string&gt;] &lt;worktree&gt;
Junio C Hamano45badf02018-03-14 21:56:41[diff] [blame]755<em>git worktree move</em> &lt;worktree&gt; &lt;new-path&gt;
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]756<em>git worktree prune</em> [-n] [-v] [--expire &lt;expire&gt;]
Junio C Hamanoccb82522018-05-08 07:52:09[diff] [blame]757<em>git worktree remove</em> [-f] &lt;worktree&gt;
Junio C Hamanoa65d8e62020-09-09 22:27:44[diff] [blame]758<em>git worktree repair</em> [&lt;path&gt;&#8230;]
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]759<em>git worktree unlock</em> &lt;worktree&gt;</pre>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]760<div class="attribution">
761</div></div>
762</div>
763</div>
764<div class="sect1">
765<h2 id="_description">DESCRIPTION</h2>
766<div class="sectionbody">
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]767<div class="paragraph"><p>Manage multiple working trees attached to the same repository.</p></div>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]768<div class="paragraph"><p>A git repository can support multiple working trees, allowing you to check
Junio C Hamano1e4fff22015-07-17 22:44:48[diff] [blame]769out more than one branch at a time. With <code>git worktree add</code> a new working
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]770tree is associated with the repository. This new working tree is called a
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]771"linked working tree" as opposed to the "main working tree" prepared by
772<a href="git-init.html">git-init(1)</a> or <a href="git-clone.html">git-clone(1)</a>.
773A repository has one main working tree (if it&#8217;s not a
Junio C Hamano96153bf2018-04-25 08:25:34[diff] [blame]774bare repository) and zero or more linked working trees. When you are done
775with a linked working tree, remove it with <code>git worktree remove</code>.</p></div>
Junio C Hamano5093e582020-09-19 01:16:46[diff] [blame]776<div class="paragraph"><p>In its simplest form, <code>git worktree add &lt;path&gt;</code> automatically creates a
777new branch whose name is the final component of <code>&lt;path&gt;</code>, which is
778convenient if you plan to work on a new topic. For instance, <code>git
779worktree add ../hotfix</code> creates new branch <code>hotfix</code> and checks it out at
780path <code>../hotfix</code>. To instead work on an existing branch in a new working
781tree, use <code>git worktree add &lt;path&gt; &lt;branch&gt;</code>. On the other hand, if you
782just plan to make some experimental changes or do testing without
783disturbing existing development, it is often convenient to create a
784<em>throwaway</em> working tree not associated with any branch. For instance,
785<code>git worktree add -d &lt;path&gt;</code> creates a new working tree with a detached
786<code>HEAD</code> at the same commit as the current branch.</p></div>
Junio C Hamano96153bf2018-04-25 08:25:34[diff] [blame]787<div class="paragraph"><p>If a working tree is deleted without using <code>git worktree remove</code>, then
788its associated administrative files, which reside in the repository
789(see "DETAILS" below), will eventually be removed automatically (see
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]790<code>gc.worktreePruneExpire</code> in <a href="git-config.html">git-config(1)</a>), or you can run
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]791<code>git worktree prune</code> in the main or any linked working tree to
792clean up any stale administrative files.</p></div>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]793<div class="paragraph"><p>If a linked working tree is stored on a portable device or network share
794which is not always mounted, you can prevent its administrative files from
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]795being pruned by issuing the <code>git worktree lock</code> command, optionally
796specifying <code>--reason</code> to explain why the working tree is locked.</p></div>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]797</div>
798</div>
799<div class="sect1">
800<h2 id="_commands">COMMANDS</h2>
801<div class="sectionbody">
802<div class="dlist"><dl>
803<dt class="hdlist1">
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]804add &lt;path&gt; [&lt;commit-ish&gt;]
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]805</dt>
806<dd>
807<p>
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]808Create <code>&lt;path&gt;</code> and checkout <code>&lt;commit-ish&gt;</code> into it. The new working directory
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]809is linked to the current repository, sharing everything except working
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]810directory specific files such as <code>HEAD</code>, <code>index</code>, etc. As a convenience,
811<code>&lt;commit-ish&gt;</code> may be a bare "<code>-</code>", which is synonymous with <code>@{-1}</code>.
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]812</p>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]813<div class="paragraph"><p>If <code>&lt;commit-ish&gt;</code> is a branch name (call it <code>&lt;branch&gt;</code>) and is not found,
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]814and neither <code>-b</code> nor <code>-B</code> nor <code>--detach</code> are used, but there does
815exist a tracking branch in exactly one remote (call it <code>&lt;remote&gt;</code>)
Junio C Hamano615c3b32018-02-28 23:40:27[diff] [blame]816with a matching name, treat as equivalent to:</p></div>
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]817<div class="listingblock">
818<div class="content">
819<pre><code>$ git worktree add --track -b &lt;branch&gt; &lt;path&gt; &lt;remote&gt;/&lt;branch&gt;</code></pre>
820</div></div>
Junio C Hamanof09b7cd2018-08-02 23:01:45[diff] [blame]821<div class="paragraph"><p>If the branch exists in multiple remotes and one of them is named by
822the <code>checkout.defaultRemote</code> configuration variable, we&#8217;ll use that
823one for the purposes of disambiguation, even if the <code>&lt;branch&gt;</code> isn&#8217;t
824unique across all remotes. Set it to
825e.g. <code>checkout.defaultRemote=origin</code> to always checkout remote
826branches from there if <code>&lt;branch&gt;</code> is ambiguous but exists on the
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]827<code>origin</code> remote. See also <code>checkout.defaultRemote</code> in
Junio C Hamanof09b7cd2018-08-02 23:01:45[diff] [blame]828<a href="git-config.html">git-config(1)</a>.</p></div>
Junio C Hamano615c3b32018-02-28 23:40:27[diff] [blame]829<div class="paragraph"><p>If <code>&lt;commit-ish&gt;</code> is omitted and neither <code>-b</code> nor <code>-B</code> nor <code>--detach</code> used,
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]830then, as a convenience, the new working tree is associated with a branch
Junio C Hamanob9d9d902018-05-23 07:07:42[diff] [blame]831(call it <code>&lt;branch&gt;</code>) named after <code>$(basename &lt;path&gt;)</code>. If <code>&lt;branch&gt;</code>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]832doesn&#8217;t exist, a new branch based on <code>HEAD</code> is automatically created as
Junio C Hamanob9d9d902018-05-23 07:07:42[diff] [blame]833if <code>-b &lt;branch&gt;</code> was given. If <code>&lt;branch&gt;</code> does exist, it will be
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]834checked out in the new working tree, if it&#8217;s not checked out anywhere
835else, otherwise the command will refuse to create the working tree (unless
Junio C Hamanob9d9d902018-05-23 07:07:42[diff] [blame]836<code>--force</code> is used).</p></div>
Junio C Hamano615c3b32018-02-28 23:40:27[diff] [blame]837</dd>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]838<dt class="hdlist1">
Junio C Hamanodaf0aae2015-10-26 23:14:30[diff] [blame]839list
840</dt>
841<dd>
842<p>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]843List details of each working tree. The main working tree is listed first,
844followed by each of the linked working trees. The output details include
Junio C Hamano6a3d6652020-10-27 23:01:14[diff] [blame]845whether the working tree is bare, the revision currently checked out, the
846branch currently checked out (or "detached HEAD" if none), and "locked" if
847the worktree is locked.
Junio C Hamanodaf0aae2015-10-26 23:14:30[diff] [blame]848</p>
849</dd>
Junio C Hamanoc6c919b2016-07-06 21:34:15[diff] [blame]850<dt class="hdlist1">
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]851lock
852</dt>
853<dd>
854<p>
855If a working tree is on a portable device or network share which
856is not always mounted, lock it to prevent its administrative
857files from being pruned automatically. This also prevents it from
858being moved or deleted. Optionally, specify a reason for the lock
859with <code>--reason</code>.
860</p>
861</dd>
862<dt class="hdlist1">
Junio C Hamano45badf02018-03-14 21:56:41[diff] [blame]863move
864</dt>
865<dd>
866<p>
867Move a working tree to a new location. Note that the main working tree
Junio C Hamanoa65d8e62020-09-09 22:27:44[diff] [blame]868or linked working trees containing submodules cannot be moved with this
869command. (The <code>git worktree repair</code> command, however, can reestablish
870the connection with linked working trees if you move the main working
871tree manually.)
Junio C Hamano45badf02018-03-14 21:56:41[diff] [blame]872</p>
873</dd>
874<dt class="hdlist1">
Junio C Hamanoc6c919b2016-07-06 21:34:15[diff] [blame]875prune
876</dt>
877<dd>
878<p>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]879Prune working tree information in <code>$GIT_DIR/worktrees</code>.
Junio C Hamanoc6c919b2016-07-06 21:34:15[diff] [blame]880</p>
881</dd>
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]882<dt class="hdlist1">
Junio C Hamano45badf02018-03-14 21:56:41[diff] [blame]883remove
884</dt>
885<dd>
886<p>
887Remove a working tree. Only clean working trees (no untracked files
888and no modification in tracked files) can be removed. Unclean working
889trees or ones with submodules can be removed with <code>--force</code>. The main
890working tree cannot be removed.
891</p>
892</dd>
893<dt class="hdlist1">
Junio C Hamanoa65d8e62020-09-09 22:27:44[diff] [blame]894repair [&lt;path&gt;&#8230;]
895</dt>
896<dd>
897<p>
898Repair working tree administrative files, if possible, if they have
899become corrupted or outdated due to external factors.
900</p>
901<div class="paragraph"><p>For instance, if the main working tree (or bare repository) is moved,
902linked working trees will be unable to locate it. Running <code>repair</code> in
903the main working tree will reestablish the connection from linked
904working trees back to the main working tree.</p></div>
905<div class="paragraph"><p>Similarly, if a linked working tree is moved without using <code>git worktree
906move</code>, the main working tree (or bare repository) will be unable to
907locate it. Running <code>repair</code> within the recently-moved working tree will
908reestablish the connection. If multiple linked working trees are moved,
909running <code>repair</code> from any working tree with each tree&#8217;s new <code>&lt;path&gt;</code> as
910an argument, will reestablish the connection to all the specified paths.</p></div>
911</dd>
912<dt class="hdlist1">
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]913unlock
914</dt>
915<dd>
916<p>
917Unlock a working tree, allowing it to be pruned, moved or deleted.
918</p>
919</dd>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]920</dl></div>
921</div>
922</div>
923<div class="sect1">
924<h2 id="_options">OPTIONS</h2>
925<div class="sectionbody">
926<div class="dlist"><dl>
927<dt class="hdlist1">
928-f
929</dt>
930<dt class="hdlist1">
931--force
932</dt>
933<dd>
934<p>
Junio C Hamano45badf02018-03-14 21:56:41[diff] [blame]935 By default, <code>add</code> refuses to create a new working tree when
936 <code>&lt;commit-ish&gt;</code> is a branch name and is already checked out by
Junio C Hamano980e61e2018-09-17 22:45:52[diff] [blame]937 another working tree, or if <code>&lt;path&gt;</code> is already assigned to some
938 working tree but is missing (for instance, if <code>&lt;path&gt;</code> was deleted
939 manually). This option overrides these safeguards. To add a missing but
940 locked working tree path, specify <code>--force</code> twice.
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]941</p>
Junio C Hamano980e61e2018-09-17 22:45:52[diff] [blame]942<div class="paragraph"><p><code>move</code> refuses to move a locked working tree unless <code>--force</code> is specified
Junio C Hamano03e5f352020-06-22 23:59:49[diff] [blame]943twice. If the destination is already assigned to some other working tree but is
944missing (for instance, if <code>&lt;new-path&gt;</code> was deleted manually), then <code>--force</code>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]945allows the move to proceed; use <code>--force</code> twice if the destination is locked.</p></div>
Junio C Hamano980e61e2018-09-17 22:45:52[diff] [blame]946<div class="paragraph"><p><code>remove</code> refuses to remove an unclean working tree unless <code>--force</code> is used.
947To remove a locked working tree, specify <code>--force</code> twice.</p></div>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]948</dd>
949<dt class="hdlist1">
950-b &lt;new-branch&gt;
951</dt>
952<dt class="hdlist1">
953-B &lt;new-branch&gt;
954</dt>
955<dd>
956<p>
957 With <code>add</code>, create a new branch named <code>&lt;new-branch&gt;</code> starting at
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]958 <code>&lt;commit-ish&gt;</code>, and check out <code>&lt;new-branch&gt;</code> into the new working tree.
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]959 If <code>&lt;commit-ish&gt;</code> is omitted, it defaults to <code>HEAD</code>.
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]960 By default, <code>-b</code> refuses to create a new branch if it already
961 exists. <code>-B</code> overrides this safeguard, resetting <code>&lt;new-branch&gt;</code> to
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]962 <code>&lt;commit-ish&gt;</code>.
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]963</p>
964</dd>
965<dt class="hdlist1">
Junio C Hamano5093e582020-09-19 01:16:46[diff] [blame]966-d
967</dt>
968<dt class="hdlist1">
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]969--detach
970</dt>
971<dd>
972<p>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]973 With <code>add</code>, detach <code>HEAD</code> in the new working tree. See "DETACHED HEAD"
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]974 in <a href="git-checkout.html">git-checkout(1)</a>.
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]975</p>
976</dd>
977<dt class="hdlist1">
Junio C Hamano5996b672016-04-13 22:01:41[diff] [blame]978--[no-]checkout
979</dt>
980<dd>
981<p>
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]982 By default, <code>add</code> checks out <code>&lt;commit-ish&gt;</code>, however, <code>--no-checkout</code> can
Junio C Hamano5996b672016-04-13 22:01:41[diff] [blame]983 be used to suppress checkout in order to make customizations,
984 such as configuring sparse-checkout. See "Sparse checkout"
985 in <a href="git-read-tree.html">git-read-tree(1)</a>.
986</p>
987</dd>
988<dt class="hdlist1">
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]989--[no-]guess-remote
990</dt>
991<dd>
992<p>
993 With <code>worktree add &lt;path&gt;</code>, without <code>&lt;commit-ish&gt;</code>, instead
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]994 of creating a new branch from <code>HEAD</code>, if there exists a tracking
Junio C Hamano1861f8a2018-01-12 02:46:21[diff] [blame]995 branch in exactly one remote matching the basename of <code>&lt;path&gt;</code>,
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]996 base the new branch on the remote-tracking branch, and mark
997 the remote-tracking branch as "upstream" from the new branch.
998</p>
999<div class="paragraph"><p>This can also be set up as the default behaviour by using the
1000<code>worktree.guessRemote</code> config option.</p></div>
1001</dd>
1002<dt class="hdlist1">
1003--[no-]track
1004</dt>
1005<dd>
1006<p>
1007 When creating a new branch, if <code>&lt;commit-ish&gt;</code> is a branch,
1008 mark it as "upstream" from the new branch. This is the
1009 default if <code>&lt;commit-ish&gt;</code> is a remote-tracking branch. See
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1010 <code>--track</code> in <a href="git-branch.html">git-branch(1)</a> for details.
Junio C Hamano047135e2017-12-19 21:57:54[diff] [blame]1011</p>
1012</dd>
1013<dt class="hdlist1">
Junio C Hamanobeca3402017-04-27 02:21:51[diff] [blame]1014--lock
1015</dt>
1016<dd>
1017<p>
1018 Keep the working tree locked after creation. This is the
1019 equivalent of <code>git worktree lock</code> after <code>git worktree add</code>,
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1020 but without a race condition.
Junio C Hamanobeca3402017-04-27 02:21:51[diff] [blame]1021</p>
1022</dd>
1023<dt class="hdlist1">
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1024-n
1025</dt>
1026<dt class="hdlist1">
1027--dry-run
1028</dt>
1029<dd>
1030<p>
1031 With <code>prune</code>, do not remove anything; just report what it would
1032 remove.
1033</p>
1034</dd>
1035<dt class="hdlist1">
Junio C Hamanodaf0aae2015-10-26 23:14:30[diff] [blame]1036--porcelain
1037</dt>
1038<dd>
1039<p>
1040 With <code>list</code>, output in an easy-to-parse format for scripts.
1041 This format will remain stable across Git versions and regardless of user
1042 configuration. See below for details.
1043</p>
1044</dd>
1045<dt class="hdlist1">
Junio C Hamanoae66dc52018-08-27 21:57:40[diff] [blame]1046-q
1047</dt>
1048<dt class="hdlist1">
1049--quiet
1050</dt>
1051<dd>
1052<p>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1053 With <code>add</code>, suppress feedback messages.
Junio C Hamanoae66dc52018-08-27 21:57:40[diff] [blame]1054</p>
1055</dd>
1056<dt class="hdlist1">
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1057-v
1058</dt>
1059<dt class="hdlist1">
1060--verbose
1061</dt>
1062<dd>
1063<p>
1064 With <code>prune</code>, report all removals.
1065</p>
1066</dd>
1067<dt class="hdlist1">
1068--expire &lt;time&gt;
1069</dt>
1070<dd>
1071<p>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1072 With <code>prune</code>, only expire unused working trees older than <code>&lt;time&gt;</code>.
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1073</p>
1074</dd>
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]1075<dt class="hdlist1">
1076--reason &lt;string&gt;
1077</dt>
1078<dd>
1079<p>
1080 With <code>lock</code>, an explanation why the working tree is locked.
1081</p>
1082</dd>
1083<dt class="hdlist1">
1084&lt;worktree&gt;
1085</dt>
1086<dd>
1087<p>
1088 Working trees can be identified by path, either relative or
1089 absolute.
1090</p>
1091<div class="paragraph"><p>If the last path components in the working tree&#8217;s path is unique among
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1092working trees, it can be used to identify a working tree. For example if
1093you only have two working trees, at <code>/abc/def/ghi</code> and <code>/abc/def/ggg</code>,
1094then <code>ghi</code> or <code>def/ghi</code> is enough to point to the former working tree.</p></div>
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]1095</dd>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1096</dl></div>
1097</div>
1098</div>
1099<div class="sect1">
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1100<h2 id="_refs">REFS</h2>
1101<div class="sectionbody">
1102<div class="paragraph"><p>In multiple working trees, some refs may be shared between all working
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1103trees and some refs are local. One example is <code>HEAD</code> which is different for each
1104working tree. This section is about the sharing rules and how to access
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1105refs of one working tree from another.</p></div>
1106<div class="paragraph"><p>In general, all pseudo refs are per working tree and all refs starting
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1107with <code>refs/</code> are shared. Pseudo refs are ones like <code>HEAD</code> which are
1108directly under <code>$GIT_DIR</code> instead of inside <code>$GIT_DIR/refs</code>. There are
1109exceptions, however: refs inside <code>refs/bisect</code> and <code>refs/worktree</code> are not
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1110shared.</p></div>
1111<div class="paragraph"><p>Refs that are per working tree can still be accessed from another
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1112working tree via two special paths, <code>main-worktree</code> and <code>worktrees</code>. The
1113former gives access to per-working tree refs of the main working tree,
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1114while the latter to all linked working trees.</p></div>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1115<div class="paragraph"><p>For example, <code>main-worktree/HEAD</code> or <code>main-worktree/refs/bisect/good</code>
1116resolve to the same value as the main working tree&#8217;s <code>HEAD</code> and
1117<code>refs/bisect/good</code> respectively. Similarly, <code>worktrees/foo/HEAD</code> or
1118<code>worktrees/bar/refs/bisect/bad</code> are the same as
1119<code>$GIT_COMMON_DIR/worktrees/foo/HEAD</code> and
1120<code>$GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad</code>.</p></div>
1121<div class="paragraph"><p>To access refs, it&#8217;s best not to look inside <code>$GIT_DIR</code> directly. Instead
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1122use commands such as <a href="git-rev-parse.html">git-rev-parse(1)</a> or <a href="git-update-ref.html">git-update-ref(1)</a>
1123which will handle refs correctly.</p></div>
1124</div>
1125</div>
1126<div class="sect1">
1127<h2 id="_configuration_file">CONFIGURATION FILE</h2>
1128<div class="sectionbody">
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1129<div class="paragraph"><p>By default, the repository <code>config</code> file is shared across all working
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1130trees. If the config variables <code>core.bare</code> or <code>core.worktree</code> are
1131already present in the config file, they will be applied to the main
1132working trees only.</p></div>
1133<div class="paragraph"><p>In order to have configuration specific to working trees, you can turn
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1134on the <code>worktreeConfig</code> extension, e.g.:</p></div>
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1135<div class="listingblock">
1136<div class="content">
1137<pre><code>$ git config extensions.worktreeConfig true</code></pre>
1138</div></div>
1139<div class="paragraph"><p>In this mode, specific configuration stays in the path pointed by <code>git
1140rev-parse --git-path config.worktree</code>. You can add or update
1141configuration in this file with <code>git config --worktree</code>. Older Git
1142versions will refuse to access repositories with this extension.</p></div>
1143<div class="paragraph"><p>Note that in this file, the exception for <code>core.bare</code> and <code>core.worktree</code>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1144is gone. If they exist in <code>$GIT_DIR/config</code>, you must move
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1145them to the <code>config.worktree</code> of the main working tree. You may also
1146take this opportunity to review and move other configuration that you
1147do not want to share to all working trees:</p></div>
1148<div class="ulist"><ul>
1149<li>
1150<p>
1151<code>core.worktree</code> and <code>core.bare</code> should never be shared
1152</p>
1153</li>
1154<li>
1155<p>
1156<code>core.sparseCheckout</code> is recommended per working tree, unless you
1157 are sure you always use sparse checkout for all working trees.
1158</p>
1159</li>
1160</ul></div>
1161</div>
1162</div>
1163<div class="sect1">
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1164<h2 id="_details">DETAILS</h2>
1165<div class="sectionbody">
1166<div class="paragraph"><p>Each linked working tree has a private sub-directory in the repository&#8217;s
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1167<code>$GIT_DIR/worktrees</code> directory. The private sub-directory&#8217;s name is usually
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1168the base name of the linked working tree&#8217;s path, possibly appended with a
1169number to make it unique. For example, when <code>$GIT_DIR=/path/main/.git</code> the
Junio C Hamano1e4fff22015-07-17 22:44:48[diff] [blame]1170command <code>git worktree add /path/other/test-next next</code> creates the linked
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1171working tree in <code>/path/other/test-next</code> and also creates a
1172<code>$GIT_DIR/worktrees/test-next</code> directory (or <code>$GIT_DIR/worktrees/test-next1</code>
1173if <code>test-next</code> is already taken).</p></div>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1174<div class="paragraph"><p>Within a linked working tree, <code>$GIT_DIR</code> is set to point to this private
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1175directory (e.g. <code>/path/main/.git/worktrees/test-next</code> in the example) and
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1176<code>$GIT_COMMON_DIR</code> is set to point back to the main working tree&#8217;s <code>$GIT_DIR</code>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1177(e.g. <code>/path/main/.git</code>). These settings are made in a <code>.git</code> file located at
1178the top directory of the linked working tree.</p></div>
1179<div class="paragraph"><p>Path resolution via <code>git rev-parse --git-path</code> uses either
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1180<code>$GIT_DIR</code> or <code>$GIT_COMMON_DIR</code> depending on the path. For example, in the
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1181linked working tree <code>git rev-parse --git-path HEAD</code> returns
1182<code>/path/main/.git/worktrees/test-next/HEAD</code> (not
1183<code>/path/other/test-next/.git/HEAD</code> or <code>/path/main/.git/HEAD</code>) while <code>git
1184rev-parse --git-path refs/heads/master</code> uses
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1185<code>$GIT_COMMON_DIR</code> and returns <code>/path/main/.git/refs/heads/master</code>,
1186since refs are shared across all working trees, except <code>refs/bisect</code> and
1187<code>refs/worktree</code>.</p></div>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1188<div class="paragraph"><p>See <a href="gitrepository-layout.html">gitrepository-layout(5)</a> for more information. The rule of
1189thumb is do not make any assumption about whether a path belongs to
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1190<code>$GIT_DIR</code> or <code>$GIT_COMMON_DIR</code> when you need to directly access something
1191inside <code>$GIT_DIR</code>. Use <code>git rev-parse --git-path</code> to get the final path.</p></div>
1192<div class="paragraph"><p>If you manually move a linked working tree, you need to update the <code>gitdir</code> file
Junio C Hamano9099a7c2016-02-10 23:42:05[diff] [blame]1193in the entry&#8217;s directory. For example, if a linked working tree is moved
1194to <code>/newpath/test-next</code> and its <code>.git</code> file points to
1195<code>/path/main/.git/worktrees/test-next</code>, then update
1196<code>/path/main/.git/worktrees/test-next/gitdir</code> to reference <code>/newpath/test-next</code>
Junio C Hamanoa65d8e62020-09-09 22:27:44[diff] [blame]1197instead. Better yet, run <code>git worktree repair</code> to reestablish the connection
1198automatically.</p></div>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1199<div class="paragraph"><p>To prevent a <code>$GIT_DIR/worktrees</code> entry from being pruned (which
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1200can be useful in some situations, such as when the
Junio C Hamano51b095b2016-07-28 21:57:51[diff] [blame]1201entry&#8217;s working tree is stored on a portable device), use the
1202<code>git worktree lock</code> command, which adds a file named
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1203<code>locked</code> to the entry&#8217;s directory. The file contains the reason in
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1204plain text. For example, if a linked working tree&#8217;s <code>.git</code> file points
1205to <code>/path/main/.git/worktrees/test-next</code> then a file named
1206<code>/path/main/.git/worktrees/test-next/locked</code> will prevent the
1207<code>test-next</code> entry from being pruned. See
1208<a href="gitrepository-layout.html">gitrepository-layout(5)</a> for details.</p></div>
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1209<div class="paragraph"><p>When <code>extensions.worktreeConfig</code> is enabled, the config file
Junio C Hamano06ce83b2018-11-13 14:06:12[diff] [blame]1210<code>.git/worktrees/&lt;id&gt;/config.worktree</code> is read after <code>.git/config</code> is.</p></div>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1211</div>
1212</div>
1213<div class="sect1">
Junio C Hamanodaf0aae2015-10-26 23:14:30[diff] [blame]1214<h2 id="_list_output_format">LIST OUTPUT FORMAT</h2>
1215<div class="sectionbody">
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1216<div class="paragraph"><p>The <code>worktree list</code> command has two output formats. The default format shows the
Junio C Hamanodaf0aae2015-10-26 23:14:30[diff] [blame]1217details on a single line with columns. For example:</p></div>
1218<div class="listingblock">
1219<div class="content">
Junio C Hamano96153bf2018-04-25 08:25:34[diff] [blame]1220<pre><code>$ git worktree list
Junio C Hamanodaf0aae2015-10-26 23:14:30[diff] [blame]1221/path/to/bare-source (bare)
1222/path/to/linked-worktree abcd1234 [master]
1223/path/to/other-linked-worktree 1234abc (detached HEAD)</code></pre>
1224</div></div>
1225<div class="sect2">
1226<h3 id="_porcelain_format">Porcelain Format</h3>
1227<div class="paragraph"><p>The porcelain format has a line per attribute. Attributes are listed with a
Junio C Hamanoc425d102020-08-12 01:44:24[diff] [blame]1228label and value separated by a single space. Boolean attributes (like <code>bare</code>
1229and <code>detached</code>) are listed as a label only, and are present only
1230if the value is true. The first attribute of a working tree is always
1231<code>worktree</code>, an empty line indicates the end of the record. For example:</p></div>
Junio C Hamanodaf0aae2015-10-26 23:14:30[diff] [blame]1232<div class="listingblock">
1233<div class="content">
Junio C Hamano96153bf2018-04-25 08:25:34[diff] [blame]1234<pre><code>$ git worktree list --porcelain
Junio C Hamanodaf0aae2015-10-26 23:14:30[diff] [blame]1235worktree /path/to/bare-source
1236bare
1237
1238worktree /path/to/linked-worktree
1239HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
1240branch refs/heads/master
1241
1242worktree /path/to/other-linked-worktree
1243HEAD 1234abc1234abc1234abc1234abc1234abc1234a
1244detached</code></pre>
1245</div></div>
1246</div>
1247</div>
1248</div>
1249<div class="sect1">
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1250<h2 id="_examples">EXAMPLES</h2>
1251<div class="sectionbody">
1252<div class="paragraph"><p>You are in the middle of a refactoring session and your boss comes in and
1253demands that you fix something immediately. You might typically use
1254<a href="git-stash.html">git-stash(1)</a> to store your changes away temporarily, however, your
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]1255working tree is in such a state of disarray (with new, moved, and removed
1256files, and other bits and pieces strewn around) that you don&#8217;t want to risk
1257disturbing any of it. Instead, you create a temporary linked working tree to
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1258make the emergency fix, remove it when done, and then resume your earlier
1259refactoring session.</p></div>
1260<div class="listingblock">
1261<div class="content">
1262<pre><code>$ git worktree add -b emergency-fix ../temp master
1263$ pushd ../temp
1264# ... hack hack hack ...
1265$ git commit -a -m 'emergency fix for boss'
1266$ popd
Junio C Hamano96153bf2018-04-25 08:25:34[diff] [blame]1267$ git worktree remove ../temp</code></pre>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1268</div></div>
1269</div>
1270</div>
1271<div class="sect1">
1272<h2 id="_bugs">BUGS</h2>
1273<div class="sectionbody">
Junio C Hamano1e4fff22015-07-17 22:44:48[diff] [blame]1274<div class="paragraph"><p>Multiple checkout in general is still experimental, and the support
1275for submodules is incomplete. It is NOT recommended to make multiple
1276checkouts of a superproject.</p></div>
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1277</div>
1278</div>
1279<div class="sect1">
1280<h2 id="_git">GIT</h2>
1281<div class="sectionbody">
1282<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1283</div>
1284</div>
1285</div>
1286<div id="footnotes"><hr /></div>
1287<div id="footer">
1288<div id="footer-text">
Junio C Hamano2ef0ba32018-01-26 23:13:53[diff] [blame]1289Last updated
Junio C Hamano6a3d6652020-10-27 23:01:14[diff] [blame]1290 2020-10-27 15:58:27 PDT
Junio C Hamanob5dd60f2015-07-13 21:48:05[diff] [blame]1291</div>
1292</div>
1293</body>
1294</html>