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