3 <!-- This is an automatically generated file. Do not edit.
4 Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
6 Permission to use, copy, modify, and distribute this software for any
7 purpose with or without fee is hereby granted, provided that the above
8 copyright notice and this permission notice appear in all copies.
10 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 <meta charset="utf-8"/>
21 table.head, table.foot { width: 100%; }
22 td.head-rtitle, td.foot-os { text-align: right; }
23 td.head-vol { text-align: center; }
24 div.Pp { margin: 1ex 0ex; }
25 div.Nd, div.Bf, div.Op { display: inline; }
26 span.Pa, span.Ad { font-style: italic; }
27 span.Ms { font-weight: bold; }
28 dl.Bl-diag > dt { font-weight: bold; }
29 code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn,
30 code.Cd { font-weight: bold; font-family: inherit; }
32 <title>GIT-REPOSITORY(5)</title>
37 <td class="head-ltitle">GIT-REPOSITORY(5)</td>
38 <td class="head-vol">File Formats Manual</td>
39 <td class="head-rtitle">GIT-REPOSITORY(5)</td>
42 <div class="manual-text">
44 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
45 <code class="Nm">git-repository</code> —
46 <div class="Nd">Git repository format</div>
49 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
50 A Git repository stores a series of versioned snapshots of a file hierarchy.
51 Conceptually, the repository's data model is a directed acyclic graph which
52 contains three types of objects as nodes:
55 <dd>The content of tracked files is stored in objects of type
56 <i class="Em">blob</i>.</dd>
58 <dd>A <i class="Em">tree</i> object points to any number of such blobs, and
59 also to other trees in order to represent a hierarchy of files and
62 <dd>A <i class="Em">commit</i> object points to the root element of one tree,
63 and thus records the state of this entire tree as a snapshot. Commit
64 objects are chained together to form lines of version control history.
65 Most commits have just one successor commit, but commits may be succeeded
66 by an arbitrary number of subsequent commits so that diverging lines of
67 version control history, known as <i class="Em">branches</i>, can be
68 represented. A commit which precedes another commit is referred to as that
69 other commit's <i class="Em">parent commit</i>. A commit with multiple
70 parents unites disparate lines of history and is known as a
71 <i class="Em">merge commit</i>.</dd>
73 <p class="Pp">Each object is identified by a SHA1 hash calculated over both the
74 object's header and the data stored in the object.</p>
77 <h1 class="Sh" id="OBJECT_STORAGE"><a class="permalink" href="#OBJECT_STORAGE">OBJECT
79 Loose objects are stored as individual files beneath the directory
80 <span class="Pa">objects</span>, spread across 256 sub-directories named after
81 the 256 possible hexadecimal values of the first byte of an object identifier.
82 The name of the loose object file corresponds to the remaining hexadecimal
83 byte values of the object's identifier.
84 <p class="Pp">A loose object file begins with a header which specifies the type
85 of object as an ASCII string, followed by an ASCII space character, followed
86 by the object data's size encoded as an ASCII number string. The header is
87 terminated by a <b class="Sy">NUL</b> character, and the remainder of the
88 file contains object data. Loose objects files are compressed with
89 <a class="Xr">deflate(3)</a>.</p>
90 <p class="Pp">Multiple objects can be bundled in a <i class="Em">pack file</i>
91 for better disk space efficiency and increased run-time performance. The
92 pack file format knows two additional types of objects in addition to blobs,
93 trees, and commits:</p>
95 <dt>Offset Delta Objects</dt>
96 <dd>This object is represented as a delta against another object in the same
97 pack file. This other object is referred to by its offset in the pack
99 <dt>Reference Delta Objects</dt>
100 <dd>This object is represented as a delta against another object in the same
101 pack file. The other object is referred to by its SHA1 object
104 <p class="Pp">Pack files are self-contained and may not refer to loose objects
105 or objects stored in other pack files. Deltified objects may refer to other
106 deltified objects as their delta base, forming chains of deltas. The
107 ultimate base of a delta chain must be an object of the same type as the
108 original object which is stored in deltified form.</p>
109 <p class="Pp">Each pack file is accompanied by a corresponding
110 <i class="Em">pack index</i> file, which lists the IDs and offsets of all
111 objects contained in the pack file.</p>
114 <h1 class="Sh" id="REFERENCES"><a class="permalink" href="#REFERENCES">REFERENCES</a></h1>
115 A reference associates a name with an object ID. A prominent use of references
116 is providing names to branches in the repository by pointing at commit objects
117 which represent the current tip commit of a branch. Because references may
118 point to arbitrary object IDs their use is not limited to branches.
119 <p class="Pp">The name is a UTF-8 string with the following disallowed
120 characters: ‘ ’ (space), ~ (tilde), ^ (caret), :
121 (colon), ? (question mark), * (asterisk), [ (opening square bracket), \
122 (backslash). Additionally, the name may not contain the two-character
123 sequences //, .. , and @{.</p>
124 <p class="Pp">Reference names may optionally have multiple components separated
125 by the / (slash) character, forming a hierarchy of reference namespaces. Got
126 reserves the <span class="Pa">got/</span> reference namespace for internal
128 <p class="Pp">A symbolic reference associates a name with the name of another
129 reference. The most prominent example is the <span class="Pa">HEAD</span>
130 reference which points at the name of the repository's default branch
132 <p class="Pp">References are stored either as a plain file within the
133 repository, typically under the <span class="Pa">refs/</span> directory, or
134 in the <span class="Pa">packed-refs</span> file which contains one reference
135 definition per line.</p>
136 <p class="Pp">Any object which is not directly or indirectly reachable via a
137 reference is subject to deletion by Git's garbage collector.</p>
140 <h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
141 <dl class="Bl-tag Bl-compact">
142 <dt><span class="Pa">HEAD</span></dt>
143 <dd>A reference to the current head commit of the Git work tree. In bare
144 repositories, this files serves as a default reference.</dd>
145 <dt><span class="Pa">ORIG_HEAD</span></dt>
146 <dd>Reference to original head commit. Set by some Git operations.</dd>
147 <dt><span class="Pa">FETCH_HEAD</span></dt>
148 <dd>Reference to a branch tip commit most recently fetched from another
150 <dt><span class="Pa">branches/</span></dt>
151 <dd>Legacy directory used by the deprecated Gogito Git interface.</dd>
152 <dt><span class="Pa">config</span></dt>
153 <dd>Git configuration file. See <a class="Xr">git-config(1)</a>.</dd>
154 <dt><span class="Pa">description</span></dt>
155 <dd>A human-readable description of the repository.</dd>
156 <dt><span class="Pa">hooks/</span></dt>
157 <dd>This directory contains hook scripts to run when certain events
159 <dt><span class="Pa">index</span></dt>
160 <dd>The file index used by <a class="Xr">git(1)</a>. This file is not used by
161 <a class="Xr">got(1)</a>, which uses the <a class="Xr">got-worktree(5)</a>
162 file index instead.</dd>
163 <dt><span class="Pa">info</span></dt>
164 <dd>Various configuration items.</dd>
165 <dt><span class="Pa">logs/</span></dt>
166 <dd>Directory where reflogs are stored.</dd>
167 <dt><span class="Pa">objects/</span></dt>
168 <dd>Loose and packed objects are stored in this directory.</dd>
169 <dt><span class="Pa">packed-refs</span></dt>
170 <dd>A file which stores references. Corresponding on-disk references take
171 precedence over those stored here.</dd>
172 <dt><span class="Pa">refs/</span></dt>
173 <dd>The default directory to store references in.</dd>
175 <p class="Pp">A typical Git repository exposes a work tree which allows the user
176 to make changes to versioned files and create new commits. When a Git work
177 tree is present, the actual repository data is stored in a
178 <span class="Pa">.git</span> subfolder of the repository's root directory. A
179 Git repository without a work tree is known as a “bare”
180 repository. <a class="Xr">got(1)</a> does not make use of Git's work tree
181 and treats every repository as if it was bare.</p>
184 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
186 <a class="Xr">got(1)</a>, <a class="Xr">deflate(3)</a>,
187 <a class="Xr">SHA1(3)</a>, <a class="Xr">got-worktree(5)</a>
190 <h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
191 The Git repository format was initially designed by Linus Torvalds in 2005 and
192 has since been extended by various people involved in the development of the
193 Git version control system.
196 <h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
197 The particular set of disallowed characters in reference names is a consequence
198 of design choices made for the command-line interface of
199 <a class="Xr">git(1)</a>. The same characters are disallowed by Got for
200 compatibility purposes. Got additionaly prevents users from creating reference
201 names with a leading - (dash) character, because this is rarely intended and
202 not considered useful.
207 <td class="foot-date">August 5, 2019</td>
208 <td class="foot-os">OpenBSD 6.5</td>
