Autogenerated HTML docs for v2.42.0-398-ga9ecd
[git-htmldocs.git] / gitrepository-layout.html
blobbd1714a54e181d31ec621da1c45685bc12edfe9f
1 <?xml version="1.0" encoding="UTF-8"?>
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" />
7 <meta name="generator" content="AsciiDoc 10.2.0" />
8 <title>gitrepository-layout(5)</title>
9 <style type="text/css">
10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
12 /* Default font. */
13 body {
14 font-family: Georgia,serif;
17 /* Title font. */
18 h1, h2, h3, h4, h5, h6,
19 div.title, caption.title,
20 thead, p.table.header,
21 #toctitle,
22 #author, #revnumber, #revdate, #revremark,
23 #footer {
24 font-family: Arial,Helvetica,sans-serif;
27 body {
28 margin: 1em 5% 1em 5%;
31 a {
32 color: blue;
33 text-decoration: underline;
35 a:visited {
36 color: fuchsia;
39 em {
40 font-style: italic;
41 color: navy;
44 strong {
45 font-weight: bold;
46 color: #083194;
49 h1, h2, h3, h4, h5, h6 {
50 color: #527bbd;
51 margin-top: 1.2em;
52 margin-bottom: 0.5em;
53 line-height: 1.3;
56 h1, h2, h3 {
57 border-bottom: 2px solid silver;
59 h2 {
60 padding-top: 0.5em;
62 h3 {
63 float: left;
65 h3 + * {
66 clear: left;
68 h5 {
69 font-size: 1.0em;
72 div.sectionbody {
73 margin-left: 0;
76 hr {
77 border: 1px solid silver;
80 p {
81 margin-top: 0.5em;
82 margin-bottom: 0.5em;
85 ul, ol, li > p {
86 margin-top: 0;
88 ul > li { color: #aaa; }
89 ul > li > * { color: black; }
91 .monospaced, code, pre {
92 font-family: "Courier New", Courier, monospace;
93 font-size: inherit;
94 color: navy;
95 padding: 0;
96 margin: 0;
98 pre {
99 white-space: pre-wrap;
102 #author {
103 color: #527bbd;
104 font-weight: bold;
105 font-size: 1.1em;
107 #email {
109 #revnumber, #revdate, #revremark {
112 #footer {
113 font-size: small;
114 border-top: 2px solid silver;
115 padding-top: 0.5em;
116 margin-top: 4.0em;
118 #footer-text {
119 float: left;
120 padding-bottom: 0.5em;
122 #footer-badges {
123 float: right;
124 padding-bottom: 0.5em;
127 #preamble {
128 margin-top: 1.5em;
129 margin-bottom: 1.5em;
131 div.imageblock, div.exampleblock, div.verseblock,
132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
133 div.admonitionblock {
134 margin-top: 1.0em;
135 margin-bottom: 1.5em;
137 div.admonitionblock {
138 margin-top: 2.0em;
139 margin-bottom: 2.0em;
140 margin-right: 10%;
141 color: #606060;
144 div.content { /* Block element content. */
145 padding: 0;
148 /* Block element titles. */
149 div.title, caption.title {
150 color: #527bbd;
151 font-weight: bold;
152 text-align: left;
153 margin-top: 1.0em;
154 margin-bottom: 0.5em;
156 div.title + * {
157 margin-top: 0;
160 td div.title:first-child {
161 margin-top: 0.0em;
163 div.content div.title:first-child {
164 margin-top: 0.0em;
166 div.content + div.title {
167 margin-top: 0.0em;
170 div.sidebarblock > div.content {
171 background: #ffffee;
172 border: 1px solid #dddddd;
173 border-left: 4px solid #f0f0f0;
174 padding: 0.5em;
177 div.listingblock > div.content {
178 border: 1px solid #dddddd;
179 border-left: 5px solid #f0f0f0;
180 background: #f8f8f8;
181 padding: 0.5em;
184 div.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;
192 div.quoteblock > div.attribution {
193 padding-top: 0.5em;
194 text-align: right;
197 div.verseblock > pre.content {
198 font-family: inherit;
199 font-size: inherit;
201 div.verseblock > div.attribution {
202 padding-top: 0.75em;
203 text-align: left;
205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
206 div.verseblock + div.attribution {
207 text-align: left;
210 div.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;
218 div.admonitionblock td.content {
219 padding-left: 0.5em;
220 border-left: 3px solid #dddddd;
223 div.exampleblock > div.content {
224 border-left: 3px solid #dddddd;
225 padding-left: 0.5em;
228 div.imageblock div.content { padding-left: 0; }
229 span.image img { border-style: none; vertical-align: text-bottom; }
230 a.image:visited { color: white; }
232 dl {
233 margin-top: 0.8em;
234 margin-bottom: 0.8em;
236 dt {
237 margin-top: 0.5em;
238 margin-bottom: 0;
239 font-style: normal;
240 color: navy;
242 dd > *:first-child {
243 margin-top: 0.1em;
246 ul, ol {
247 list-style-position: outside;
249 ol.arabic {
250 list-style-type: decimal;
252 ol.loweralpha {
253 list-style-type: lower-alpha;
255 ol.upperalpha {
256 list-style-type: upper-alpha;
258 ol.lowerroman {
259 list-style-type: lower-roman;
261 ol.upperroman {
262 list-style-type: upper-roman;
265 div.compact ul, div.compact ol,
266 div.compact p, div.compact p,
267 div.compact div, div.compact div {
268 margin-top: 0.1em;
269 margin-bottom: 0.1em;
272 tfoot {
273 font-weight: bold;
275 td > div.verse {
276 white-space: pre;
279 div.hdlist {
280 margin-top: 0.8em;
281 margin-bottom: 0.8em;
283 div.hdlist tr {
284 padding-bottom: 15px;
286 dt.hdlist1.strong, td.hdlist1.strong {
287 font-weight: bold;
289 td.hdlist1 {
290 vertical-align: top;
291 font-style: normal;
292 padding-right: 0.8em;
293 color: navy;
295 td.hdlist2 {
296 vertical-align: top;
298 div.hdlist.compact tr {
299 margin: 0;
300 padding-bottom: 0;
303 .comment {
304 background: yellow;
307 .footnote, .footnoteref {
308 font-size: 0.8em;
311 span.footnote, span.footnoteref {
312 vertical-align: super;
315 #footnotes {
316 margin: 20px 0 20px 0;
317 padding: 7px 0 0 0;
320 #footnotes div.footnote {
321 margin: 0 0 5px 0;
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;
334 div.colist td {
335 padding-right: 0.5em;
336 padding-bottom: 0.3em;
337 vertical-align: top;
339 div.colist td img {
340 margin-top: 0.3em;
343 @media print {
344 #footer-badges { display: none; }
347 #toc {
348 margin-bottom: 2.5em;
351 #toctitle {
352 color: #527bbd;
353 font-size: 1.1em;
354 font-weight: bold;
355 margin-top: 1.0em;
356 margin-bottom: 0.1em;
359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
360 margin-top: 0;
361 margin-bottom: 0;
363 div.toclevel2 {
364 margin-left: 2em;
365 font-size: 0.9em;
367 div.toclevel3 {
368 margin-left: 4em;
369 font-size: 0.9em;
371 div.toclevel4 {
372 margin-left: 6em;
373 font-size: 0.9em;
376 span.aqua { color: aqua; }
377 span.black { color: black; }
378 span.blue { color: blue; }
379 span.fuchsia { color: fuchsia; }
380 span.gray { color: gray; }
381 span.green { color: green; }
382 span.lime { color: lime; }
383 span.maroon { color: maroon; }
384 span.navy { color: navy; }
385 span.olive { color: olive; }
386 span.purple { color: purple; }
387 span.red { color: red; }
388 span.silver { color: silver; }
389 span.teal { color: teal; }
390 span.white { color: white; }
391 span.yellow { color: yellow; }
393 span.aqua-background { background: aqua; }
394 span.black-background { background: black; }
395 span.blue-background { background: blue; }
396 span.fuchsia-background { background: fuchsia; }
397 span.gray-background { background: gray; }
398 span.green-background { background: green; }
399 span.lime-background { background: lime; }
400 span.maroon-background { background: maroon; }
401 span.navy-background { background: navy; }
402 span.olive-background { background: olive; }
403 span.purple-background { background: purple; }
404 span.red-background { background: red; }
405 span.silver-background { background: silver; }
406 span.teal-background { background: teal; }
407 span.white-background { background: white; }
408 span.yellow-background { background: yellow; }
410 span.big { font-size: 2em; }
411 span.small { font-size: 0.6em; }
413 span.underline { text-decoration: underline; }
414 span.overline { text-decoration: overline; }
415 span.line-through { text-decoration: line-through; }
417 div.unbreakable { page-break-inside: avoid; }
421 * xhtml11 specific
423 * */
425 div.tableblock {
426 margin-top: 1.0em;
427 margin-bottom: 1.5em;
429 div.tableblock > table {
430 border: 3px solid #527bbd;
432 thead, p.table.header {
433 font-weight: bold;
434 color: #527bbd;
436 p.table {
437 margin-top: 0;
439 /* Because the table frame attribute is overridden by CSS in most browsers. */
440 div.tableblock > table[frame="void"] {
441 border-style: none;
443 div.tableblock > table[frame="hsides"] {
444 border-left-style: none;
445 border-right-style: none;
447 div.tableblock > table[frame="vsides"] {
448 border-top-style: none;
449 border-bottom-style: none;
454 * html5 specific
456 * */
458 table.tableblock {
459 margin-top: 1.0em;
460 margin-bottom: 1.5em;
462 thead, p.tableblock.header {
463 font-weight: bold;
464 color: #527bbd;
466 p.tableblock {
467 margin-top: 0;
469 table.tableblock {
470 border-width: 3px;
471 border-spacing: 0px;
472 border-style: solid;
473 border-color: #527bbd;
474 border-collapse: collapse;
476 th.tableblock, td.tableblock {
477 border-width: 1px;
478 padding: 4px;
479 border-style: solid;
480 border-color: #527bbd;
483 table.tableblock.frame-topbot {
484 border-left-style: hidden;
485 border-right-style: hidden;
487 table.tableblock.frame-sides {
488 border-top-style: hidden;
489 border-bottom-style: hidden;
491 table.tableblock.frame-none {
492 border-style: hidden;
495 th.tableblock.halign-left, td.tableblock.halign-left {
496 text-align: left;
498 th.tableblock.halign-center, td.tableblock.halign-center {
499 text-align: center;
501 th.tableblock.halign-right, td.tableblock.halign-right {
502 text-align: right;
505 th.tableblock.valign-top, td.tableblock.valign-top {
506 vertical-align: top;
508 th.tableblock.valign-middle, td.tableblock.valign-middle {
509 vertical-align: middle;
511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
512 vertical-align: bottom;
517 * manpage specific
519 * */
521 body.manpage h1 {
522 padding-top: 0.5em;
523 padding-bottom: 0.5em;
524 border-top: 2px solid silver;
525 border-bottom: 2px solid silver;
527 body.manpage h2 {
528 border-style: none;
530 body.manpage div.sectionbody {
531 margin-left: 3em;
534 @media print {
535 body.manpage div#toc { display: none; }
539 </style>
540 <script type="text/javascript">
541 /*<![CDATA[*/
542 var asciidoc = { // Namespace.
544 /////////////////////////////////////////////////////////////////////
545 // Table Of Contents generator
546 /////////////////////////////////////////////////////////////////////
548 /* Author: Mihai Bazon, September 2002
549 * http://students.infoiasi.ro/~mishoo
551 * Table Of Content generator
552 * Version: 0.4
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.
558 /* modified by Troy D. Hanson, September 2006. License: GPL */
559 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
561 // toclevels = 1..4.
562 toc: function (toclevels) {
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);
572 return text;
575 function TocEntry(el, text, toclevel) {
576 this.element = el;
577 this.text = text;
578 this.toclevel = toclevel;
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);
594 iterate(i);
598 iterate(el);
599 return result;
602 var toc = document.getElementById("toc");
603 if (!toc) {
604 return;
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);
617 for (i = 0; i < tocEntriesToRemove.length; i++) {
618 toc.removeChild(tocEntriesToRemove[i]);
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);
635 if (entries.length == 0)
636 toc.parentNode.removeChild(toc);
640 /////////////////////////////////////////////////////////////////////
641 // Footnotes generator
642 /////////////////////////////////////////////////////////////////////
644 /* Based on footnote generation code from:
645 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
648 footnotes: 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;
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);
661 for (i = 0; i < entriesToRemove.length; i++) {
662 noteholder.removeChild(entriesToRemove[i]);
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);
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;
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>]";
708 install: function(toclevels) {
709 var timerId;
711 function reinstall() {
712 asciidoc.footnotes();
713 if (toclevels) {
714 asciidoc.toc(toclevels);
718 function reinstallAndRemoveTimer() {
719 clearInterval(timerId);
720 reinstall();
723 timerId = setInterval(reinstall, 500);
724 if (document.addEventListener)
725 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
726 else
727 window.onload = reinstallAndRemoveTimer;
731 asciidoc.install();
732 /*]]>*/
733 </script>
734 </head>
735 <body class="manpage">
736 <div id="header">
737 <h1>
738 gitrepository-layout(5) Manual Page
739 </h1>
740 <h2>NAME</h2>
741 <div class="sectionbody">
742 <p>gitrepository-layout -
743 Git Repository Layout
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="paragraph"><p>$GIT_DIR/*</p></div>
752 </div>
753 </div>
754 <div class="sect1">
755 <h2 id="_description">DESCRIPTION</h2>
756 <div class="sectionbody">
757 <div class="paragraph"><p>A Git repository comes in two different flavours:</p></div>
758 <div class="ulist"><ul>
759 <li>
761 a <code>.git</code> directory at the root of the working tree;
762 </p>
763 </li>
764 <li>
766 a <code>&lt;project&gt;.git</code> directory that is a <em>bare</em> repository
767 (i.e. without its own working tree), that is typically used for
768 exchanging histories with others by pushing into it and fetching
769 from it.
770 </p>
771 </li>
772 </ul></div>
773 <div class="paragraph"><p><strong>Note</strong>: Also you can have a plain text file <code>.git</code> at the root of
774 your working tree, containing <code>gitdir: &lt;path&gt;</code> to point at the real
775 directory that has the repository. This mechanism is often used for
776 a working tree of a submodule checkout, to allow you in the
777 containing superproject to <code>git checkout</code> a branch that does not
778 have the submodule. The <code>checkout</code> has to remove the entire
779 submodule working tree, without losing the submodule repository.</p></div>
780 <div class="paragraph"><p>These things may exist in a Git repository.</p></div>
781 <div class="dlist"><dl>
782 <dt class="hdlist1">
783 objects
784 </dt>
785 <dd>
787 Object store associated with this repository. Usually
788 an object store is self sufficient (i.e. all the objects
789 that are referred to by an object found in it are also
790 found in it), but there are a few ways to violate it.
791 </p>
792 <div class="olist arabic"><ol class="arabic">
793 <li>
795 You could have an incomplete but locally usable repository
796 by creating a shallow clone. See <a href="git-clone.html">git-clone(1)</a>.
797 </p>
798 </li>
799 <li>
801 You could be using the <code>objects/info/alternates</code> or
802 <code>$GIT_ALTERNATE_OBJECT_DIRECTORIES</code> mechanisms to <em>borrow</em>
803 objects from other object stores. A repository with this kind
804 of incomplete object store is not suitable to be published for
805 use with dumb transports but otherwise is OK as long as
806 <code>objects/info/alternates</code> points at the object stores it
807 borrows from.
808 </p>
809 <div class="paragraph"><p>This directory is ignored if $GIT_COMMON_DIR is set and
810 "$GIT_COMMON_DIR/objects" will be used instead.</p></div>
811 </li>
812 </ol></div>
813 </dd>
814 <dt class="hdlist1">
815 objects/[0-9a-f][0-9a-f]
816 </dt>
817 <dd>
819 A newly created object is stored in its own file.
820 The objects are splayed over 256 subdirectories using
821 the first two characters of the sha1 object name to
822 keep the number of directory entries in <code>objects</code>
823 itself to a manageable number. Objects found
824 here are often called <em>unpacked</em> (or <em>loose</em>) objects.
825 </p>
826 </dd>
827 <dt class="hdlist1">
828 objects/pack
829 </dt>
830 <dd>
832 Packs (files that store many objects in compressed form,
833 along with index files to allow them to be randomly
834 accessed) are found in this directory.
835 </p>
836 </dd>
837 <dt class="hdlist1">
838 objects/info
839 </dt>
840 <dd>
842 Additional information about the object store is
843 recorded in this directory.
844 </p>
845 </dd>
846 <dt class="hdlist1">
847 objects/info/packs
848 </dt>
849 <dd>
851 This file is to help dumb transports discover what packs
852 are available in this object store. Whenever a pack is
853 added or removed, <code>git update-server-info</code> should be run
854 to keep this file up to date if the repository is
855 published for dumb transports. <em>git repack</em> does this
856 by default.
857 </p>
858 </dd>
859 <dt class="hdlist1">
860 objects/info/alternates
861 </dt>
862 <dd>
864 This file records paths to alternate object stores that
865 this object store borrows objects from, one pathname per
866 line. Note that not only native Git tools use it locally,
867 but the HTTP fetcher also tries to use it remotely; this
868 will usually work if you have relative paths (relative
869 to the object database, not to the repository!) in your
870 alternates file, but it will not work if you use absolute
871 paths unless the absolute path in filesystem and web URL
872 is the same. See also <code>objects/info/http-alternates</code>.
873 </p>
874 </dd>
875 <dt class="hdlist1">
876 objects/info/http-alternates
877 </dt>
878 <dd>
880 This file records URLs to alternate object stores that
881 this object store borrows objects from, to be used when
882 the repository is fetched over HTTP.
883 </p>
884 </dd>
885 <dt class="hdlist1">
886 refs
887 </dt>
888 <dd>
890 References are stored in subdirectories of this
891 directory. The <em>git prune</em> command knows to preserve
892 objects reachable from refs found in this directory and
893 its subdirectories.
894 This directory is ignored (except refs/bisect,
895 refs/rewritten and refs/worktree) if $GIT_COMMON_DIR is
896 set and "$GIT_COMMON_DIR/refs" will be used instead.
897 </p>
898 </dd>
899 <dt class="hdlist1">
900 refs/heads/<code>name</code>
901 </dt>
902 <dd>
904 records tip-of-the-tree commit objects of branch <code>name</code>
905 </p>
906 </dd>
907 <dt class="hdlist1">
908 refs/tags/<code>name</code>
909 </dt>
910 <dd>
912 records any object name (not necessarily a commit
913 object, or a tag object that points at a commit object).
914 </p>
915 </dd>
916 <dt class="hdlist1">
917 refs/remotes/<code>name</code>
918 </dt>
919 <dd>
921 records tip-of-the-tree commit objects of branches copied
922 from a remote repository.
923 </p>
924 </dd>
925 <dt class="hdlist1">
926 refs/replace/<code>&lt;obj-sha1&gt;</code>
927 </dt>
928 <dd>
930 records the SHA-1 of the object that replaces <code>&lt;obj-sha1&gt;</code>.
931 This is similar to info/grafts and is internally used and
932 maintained by <a href="git-replace.html">git-replace(1)</a>. Such refs can be exchanged
933 between repositories while grafts are not.
934 </p>
935 </dd>
936 <dt class="hdlist1">
937 packed-refs
938 </dt>
939 <dd>
941 records the same information as refs/heads/, refs/tags/,
942 and friends record in a more efficient way. See
943 <a href="git-pack-refs.html">git-pack-refs(1)</a>. This file is ignored if $GIT_COMMON_DIR
944 is set and "$GIT_COMMON_DIR/packed-refs" will be used instead.
945 </p>
946 </dd>
947 <dt class="hdlist1">
948 HEAD
949 </dt>
950 <dd>
952 A symref (see glossary) to the <code>refs/heads/</code> namespace
953 describing the currently active branch. It does not mean
954 much if the repository is not associated with any working tree
955 (i.e. a <em>bare</em> repository), but a valid Git repository
956 <strong>must</strong> have the HEAD file; some porcelains may use it to
957 guess the designated "default" branch of the repository
958 (usually <em>master</em>). It is legal if the named branch
959 <em>name</em> does not (yet) exist. In some legacy setups, it is
960 a symbolic link instead of a symref that points at the current
961 branch.
962 </p>
963 <div class="paragraph"><p>HEAD can also record a specific commit directly, instead of
964 being a symref to point at the current branch. Such a state
965 is often called <em>detached HEAD.</em> See <a href="git-checkout.html">git-checkout(1)</a>
966 for details.</p></div>
967 </dd>
968 <dt class="hdlist1">
969 config
970 </dt>
971 <dd>
973 Repository specific configuration file. This file is ignored
974 if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be
975 used instead.
976 </p>
977 </dd>
978 <dt class="hdlist1">
979 config.worktree
980 </dt>
981 <dd>
983 Working directory specific configuration file for the main
984 working directory in multiple working directory setup (see
985 <a href="git-worktree.html">git-worktree(1)</a>).
986 </p>
987 </dd>
988 <dt class="hdlist1">
989 branches
990 </dt>
991 <dd>
993 A slightly deprecated way to store shorthands to be used
994 to specify a URL to <em>git fetch</em>, <em>git pull</em> and <em>git push</em>.
995 A file can be stored as <code>branches/&lt;name&gt;</code> and then
996 <em>name</em> can be given to these commands in place of
997 <em>repository</em> argument. See the REMOTES section in
998 <a href="git-fetch.html">git-fetch(1)</a> for details. This mechanism is legacy
999 and not likely to be found in modern repositories. This
1000 directory is ignored if $GIT_COMMON_DIR is set and
1001 "$GIT_COMMON_DIR/branches" will be used instead.
1002 </p>
1003 </dd>
1004 <dt class="hdlist1">
1005 hooks
1006 </dt>
1007 <dd>
1009 Hooks are customization scripts used by various Git
1010 commands. A handful of sample hooks are installed when
1011 <em>git init</em> is run, but all of them are disabled by
1012 default. To enable, the <code>.sample</code> suffix has to be
1013 removed from the filename by renaming.
1014 Read <a href="githooks.html">githooks(5)</a> for more details about
1015 each hook. This directory is ignored if $GIT_COMMON_DIR is set
1016 and "$GIT_COMMON_DIR/hooks" will be used instead.
1017 </p>
1018 </dd>
1019 <dt class="hdlist1">
1020 common
1021 </dt>
1022 <dd>
1024 When multiple working trees are used, most of files in
1025 $GIT_DIR are per-worktree with a few known exceptions. All
1026 files under <em>common</em> however will be shared between all
1027 working trees.
1028 </p>
1029 </dd>
1030 <dt class="hdlist1">
1031 index
1032 </dt>
1033 <dd>
1035 The current index file for the repository. It is
1036 usually not found in a bare repository.
1037 </p>
1038 </dd>
1039 <dt class="hdlist1">
1040 sharedindex.&lt;SHA-1&gt;
1041 </dt>
1042 <dd>
1044 The shared index part, to be referenced by $GIT_DIR/index and
1045 other temporary index files. Only valid in split index mode.
1046 </p>
1047 </dd>
1048 <dt class="hdlist1">
1049 info
1050 </dt>
1051 <dd>
1053 Additional information about the repository is recorded
1054 in this directory. This directory is ignored if $GIT_COMMON_DIR
1055 is set and "$GIT_COMMON_DIR/info" will be used instead.
1056 </p>
1057 </dd>
1058 <dt class="hdlist1">
1059 info/refs
1060 </dt>
1061 <dd>
1063 This file helps dumb transports discover what refs are
1064 available in this repository. If the repository is
1065 published for dumb transports, this file should be
1066 regenerated by <em>git update-server-info</em> every time a tag
1067 or branch is created or modified. This is normally done
1068 from the <code>hooks/update</code> hook, which is run by the
1069 <em>git-receive-pack</em> command when you <em>git push</em> into the
1070 repository.
1071 </p>
1072 </dd>
1073 <dt class="hdlist1">
1074 info/grafts
1075 </dt>
1076 <dd>
1078 This file records fake commit ancestry information, to
1079 pretend the set of parents a commit has is different
1080 from how the commit was actually created. One record
1081 per line describes a commit and its fake parents by
1082 listing their 40-byte hexadecimal object names separated
1083 by a space and terminated by a newline.
1084 </p>
1085 <div class="paragraph"><p>Note that the grafts mechanism is outdated and can lead to problems
1086 transferring objects between repositories; see <a href="git-replace.html">git-replace(1)</a>
1087 for a more flexible and robust system to do the same thing.</p></div>
1088 </dd>
1089 <dt class="hdlist1">
1090 info/exclude
1091 </dt>
1092 <dd>
1094 This file, by convention among Porcelains, stores the
1095 exclude pattern list. <code>.gitignore</code> is the per-directory
1096 ignore file. <em>git status</em>, <em>git add</em>, <em>git rm</em> and
1097 <em>git clean</em> look at it but the core Git commands do not look
1098 at it. See also: <a href="gitignore.html">gitignore(5)</a>.
1099 </p>
1100 </dd>
1101 <dt class="hdlist1">
1102 info/attributes
1103 </dt>
1104 <dd>
1106 Defines which attributes to assign to a path, similar to per-directory
1107 <code>.gitattributes</code> files. See also: <a href="gitattributes.html">gitattributes(5)</a>.
1108 </p>
1109 </dd>
1110 <dt class="hdlist1">
1111 info/sparse-checkout
1112 </dt>
1113 <dd>
1115 This file stores sparse checkout patterns.
1116 See also: <a href="git-read-tree.html">git-read-tree(1)</a>.
1117 </p>
1118 </dd>
1119 <dt class="hdlist1">
1120 remotes
1121 </dt>
1122 <dd>
1124 Stores shorthands for URL and default refnames for use
1125 when interacting with remote repositories via <em>git fetch</em>,
1126 <em>git pull</em> and <em>git push</em> commands. See the REMOTES section
1127 in <a href="git-fetch.html">git-fetch(1)</a> for details. This mechanism is legacy
1128 and not likely to be found in modern repositories. This
1129 directory is ignored if $GIT_COMMON_DIR is set and
1130 "$GIT_COMMON_DIR/remotes" will be used instead.
1131 </p>
1132 </dd>
1133 <dt class="hdlist1">
1134 logs
1135 </dt>
1136 <dd>
1138 Records of changes made to refs are stored in this directory.
1139 See <a href="git-update-ref.html">git-update-ref(1)</a> for more information. This
1140 directory is ignored (except logs/HEAD) if $GIT_COMMON_DIR is
1141 set and "$GIT_COMMON_DIR/logs" will be used instead.
1142 </p>
1143 </dd>
1144 <dt class="hdlist1">
1145 logs/refs/heads/<code>name</code>
1146 </dt>
1147 <dd>
1149 Records all changes made to the branch tip named <code>name</code>.
1150 </p>
1151 </dd>
1152 <dt class="hdlist1">
1153 logs/refs/tags/<code>name</code>
1154 </dt>
1155 <dd>
1157 Records all changes made to the tag named <code>name</code>.
1158 </p>
1159 </dd>
1160 <dt class="hdlist1">
1161 shallow
1162 </dt>
1163 <dd>
1165 This is similar to <code>info/grafts</code> but is internally used
1166 and maintained by shallow clone mechanism. See <code>--depth</code>
1167 option to <a href="git-clone.html">git-clone(1)</a> and <a href="git-fetch.html">git-fetch(1)</a>. This
1168 file is ignored if $GIT_COMMON_DIR is set and
1169 "$GIT_COMMON_DIR/shallow" will be used instead.
1170 </p>
1171 </dd>
1172 <dt class="hdlist1">
1173 commondir
1174 </dt>
1175 <dd>
1177 If this file exists, $GIT_COMMON_DIR (see <a href="git.html">git(1)</a>) will
1178 be set to the path specified in this file if it is not
1179 explicitly set. If the specified path is relative, it is
1180 relative to $GIT_DIR. The repository with commondir is
1181 incomplete without the repository pointed by "commondir".
1182 </p>
1183 </dd>
1184 <dt class="hdlist1">
1185 modules
1186 </dt>
1187 <dd>
1189 Contains the git-repositories of the submodules.
1190 </p>
1191 </dd>
1192 <dt class="hdlist1">
1193 worktrees
1194 </dt>
1195 <dd>
1197 Contains administrative data for linked
1198 working trees. Each subdirectory contains the working tree-related
1199 part of a linked working tree. This directory is ignored if
1200 $GIT_COMMON_DIR is set, in which case
1201 "$GIT_COMMON_DIR/worktrees" will be used instead.
1202 </p>
1203 </dd>
1204 <dt class="hdlist1">
1205 worktrees/&lt;id&gt;/gitdir
1206 </dt>
1207 <dd>
1209 A text file containing the absolute path back to the .git file
1210 that points to here. This is used to check if the linked
1211 repository has been manually removed and there is no need to
1212 keep this directory any more. The mtime of this file should be
1213 updated every time the linked repository is accessed.
1214 </p>
1215 </dd>
1216 <dt class="hdlist1">
1217 worktrees/&lt;id&gt;/locked
1218 </dt>
1219 <dd>
1221 If this file exists, the linked working tree may be on a
1222 portable device and not available. The presence of this file
1223 prevents <code>worktrees/&lt;id&gt;</code> from being pruned either automatically
1224 or manually by <code>git worktree prune</code>. The file may contain a string
1225 explaining why the repository is locked.
1226 </p>
1227 </dd>
1228 <dt class="hdlist1">
1229 worktrees/&lt;id&gt;/config.worktree
1230 </dt>
1231 <dd>
1233 Working directory specific configuration file.
1234 </p>
1235 </dd>
1236 </dl></div>
1237 </div>
1238 </div>
1239 <div class="sect1">
1240 <h2 id="_git_repository_format_versions">Git Repository Format Versions</h2>
1241 <div class="sectionbody">
1242 <div class="paragraph"><p>Every git repository is marked with a numeric version in the
1243 <code>core.repositoryformatversion</code> key of its <code>config</code> file. This version
1244 specifies the rules for operating on the on-disk repository data. An
1245 implementation of git which does not understand a particular version
1246 advertised by an on-disk repository MUST NOT operate on that repository;
1247 doing so risks not only producing wrong results, but actually losing
1248 data.</p></div>
1249 <div class="paragraph"><p>Because of this rule, version bumps should be kept to an absolute
1250 minimum. Instead, we generally prefer these strategies:</p></div>
1251 <div class="ulist"><ul>
1252 <li>
1254 bumping format version numbers of individual data files (e.g.,
1255 index, packfiles, etc). This restricts the incompatibilities only to
1256 those files.
1257 </p>
1258 </li>
1259 <li>
1261 introducing new data that gracefully degrades when used by older
1262 clients (e.g., pack bitmap files are ignored by older clients, which
1263 simply do not take advantage of the optimization they provide).
1264 </p>
1265 </li>
1266 </ul></div>
1267 <div class="paragraph"><p>A whole-repository format version bump should only be part of a change
1268 that cannot be independently versioned. For instance, if one were to
1269 change the reachability rules for objects, or the rules for locking
1270 refs, that would require a bump of the repository format version.</p></div>
1271 <div class="paragraph"><p>Note that this applies only to accessing the repository&#8217;s disk contents
1272 directly. An older client which understands only format <code>0</code> may still
1273 connect via <code>git://</code> to a repository using format <code>1</code>, as long as the
1274 server process understands format <code>1</code>.</p></div>
1275 <div class="paragraph"><p>The preferred strategy for rolling out a version bump (whether whole
1276 repository or for a single file) is to teach git to read the new format,
1277 and allow writing the new format with a config switch or command line
1278 option (for experimentation or for those who do not care about backwards
1279 compatibility with older gits). Then after a long period to allow the
1280 reading capability to become common, we may switch to writing the new
1281 format by default.</p></div>
1282 <div class="paragraph"><p>The currently defined format versions are:</p></div>
1283 <div class="sect2">
1284 <h3 id="_version_code_0_code">Version <code>0</code></h3>
1285 <div class="paragraph"><p>This is the format defined by the initial version of git, including but
1286 not limited to the format of the repository directory, the repository
1287 configuration file, and the object and ref storage. Specifying the
1288 complete behavior of git is beyond the scope of this document.</p></div>
1289 </div>
1290 <div class="sect2">
1291 <h3 id="_version_code_1_code">Version <code>1</code></h3>
1292 <div class="paragraph"><p>This format is identical to version <code>0</code>, with the following exceptions:</p></div>
1293 <div class="olist arabic"><ol class="arabic">
1294 <li>
1296 When reading the <code>core.repositoryformatversion</code> variable, a git
1297 implementation which supports version 1 MUST also read any
1298 configuration keys found in the <code>extensions</code> section of the
1299 configuration file.
1300 </p>
1301 </li>
1302 <li>
1304 If a version-1 repository specifies any <code>extensions.*</code> keys that
1305 the running git has not implemented, the operation MUST NOT
1306 proceed. Similarly, if the value of any known key is not understood
1307 by the implementation, the operation MUST NOT proceed.
1308 </p>
1309 </li>
1310 </ol></div>
1311 <div class="paragraph"><p>Note that if no extensions are specified in the config file, then
1312 <code>core.repositoryformatversion</code> SHOULD be set to <code>0</code> (setting it to <code>1</code>
1313 provides no benefit, and makes the repository incompatible with older
1314 implementations of git).</p></div>
1315 <div class="paragraph"><p>This document will serve as the master list for extensions. Any
1316 implementation wishing to define a new extension should make a note of
1317 it here, in order to claim the name.</p></div>
1318 <div class="paragraph"><p>The defined extensions are:</p></div>
1319 <div class="sect3">
1320 <h4 id="_code_noop_code"><code>noop</code></h4>
1321 <div class="paragraph"><p>This extension does not change git&#8217;s behavior at all. It is useful only
1322 for testing format-1 compatibility.</p></div>
1323 </div>
1324 <div class="sect3">
1325 <h4 id="_code_preciousobjects_code"><code>preciousObjects</code></h4>
1326 <div class="paragraph"><p>When the config key <code>extensions.preciousObjects</code> is set to <code>true</code>,
1327 objects in the repository MUST NOT be deleted (e.g., by <code>git-prune</code> or
1328 <code>git repack -d</code>).</p></div>
1329 </div>
1330 <div class="sect3">
1331 <h4 id="_code_partialclone_code"><code>partialClone</code></h4>
1332 <div class="paragraph"><p>When the config key <code>extensions.partialClone</code> is set, it indicates
1333 that the repo was created with a partial clone (or later performed
1334 a partial fetch) and that the remote may have omitted sending
1335 certain unwanted objects. Such a remote is called a "promisor remote"
1336 and it promises that all such omitted objects can be fetched from it
1337 in the future.</p></div>
1338 <div class="paragraph"><p>The value of this key is the name of the promisor remote.</p></div>
1339 </div>
1340 <div class="sect3">
1341 <h4 id="_code_worktreeconfig_code"><code>worktreeConfig</code></h4>
1342 <div class="paragraph"><p>If set, by default "git config" reads from both "config" and
1343 "config.worktree" file from GIT_DIR in that order. In
1344 multiple working directory mode, "config" file is shared while
1345 "config.worktree" is per-working directory (i.e., it&#8217;s in
1346 GIT_COMMON_DIR/worktrees/&lt;id&gt;/config.worktree)</p></div>
1347 </div>
1348 </div>
1349 </div>
1350 </div>
1351 <div class="sect1">
1352 <h2 id="_see_also">SEE ALSO</h2>
1353 <div class="sectionbody">
1354 <div class="paragraph"><p><a href="git-init.html">git-init(1)</a>,
1355 <a href="git-clone.html">git-clone(1)</a>,
1356 <a href="git-fetch.html">git-fetch(1)</a>,
1357 <a href="git-pack-refs.html">git-pack-refs(1)</a>,
1358 <a href="git-gc.html">git-gc(1)</a>,
1359 <a href="git-checkout.html">git-checkout(1)</a>,
1360 <a href="gitglossary.html">gitglossary(7)</a>,
1361 <a href="user-manual.html">The Git User&#8217;s Manual</a></p></div>
1362 </div>
1363 </div>
1364 <div class="sect1">
1365 <h2 id="_git">GIT</h2>
1366 <div class="sectionbody">
1367 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1368 </div>
1369 </div>
1370 </div>
1371 <div id="footnotes"><hr /></div>
1372 <div id="footer">
1373 <div id="footer-text">
1374 Last updated
1375 2020-03-10 15:02:33 PDT
1376 </div>
1377 </div>
1378 </body>
1379 </html>