Blob


1 <!DOCTYPE html>
2 <html>
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.
17 -->
18 <head>
19 <meta charset="utf-8"/>
20 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
21 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
22 <title>GIT-REPOSITORY(5)</title>
23 </head>
24 <body>
25 <table class="head">
26 <tr>
27 <td class="head-ltitle">GIT-REPOSITORY(5)</td>
28 <td class="head-vol">File Formats Manual</td>
29 <td class="head-rtitle">GIT-REPOSITORY(5)</td>
30 </tr>
31 </table>
32 <div class="manual-text">
33 <section class="Sh">
34 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
35 <p class="Pp"><code class="Nm">git-repository</code> &#x2014;
36 <span class="Nd">Git repository format</span></p>
37 </section>
38 <section class="Sh">
39 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
40 <p class="Pp">A Git repository stores a series of versioned snapshots of a file
41 hierarchy. Conceptually, the repository's data model is a directed acyclic
42 graph which contains three types of objects as nodes:</p>
43 <dl class="Bl-tag">
44 <dt id="blob">Blobs</dt>
45 <dd>The content of tracked files is stored in objects of type
46 <a class="permalink" href="#blob"><i class="Em">blob</i></a>.</dd>
47 <dt id="tree">Trees</dt>
48 <dd>A <a class="permalink" href="#tree"><i class="Em">tree</i></a> object
49 points to any number of such blobs, and also to other trees in order to
50 represent a hierarchy of files and directories.</dd>
51 <dt id="commit">Commits</dt>
52 <dd>A <a class="permalink" href="#commit"><i class="Em">commit</i></a> object
53 points to the root element of one tree, and thus records the state of this
54 entire tree as a snapshot. Commit objects are chained together to form
55 lines of version control history. Most commits have just one successor
56 commit, but commits may be succeeded by an arbitrary number of subsequent
57 commits so that diverging lines of version control history, known as
58 <a class="permalink" href="#branches"><i class="Em" id="branches">branches</i></a>,
59 can be represented. A commit which precedes another commit is referred to
60 as that other commit's
61 <a class="permalink" href="#parent"><i class="Em" id="parent">parent
62 commit</i></a>. A commit with multiple parents unites disparate lines of
63 history and is known as a
64 <a class="permalink" href="#merge"><i class="Em" id="merge">merge
65 commit</i></a>.</dd>
66 <dt id="tag">Tags</dt>
67 <dd>A <a class="permalink" href="#tag"><i class="Em">tag</i></a> object
68 associates a user-defined label with another object, which is typically a
69 commit object. Tag objects also contain a tag message, as well as author
70 and timestamp information.</dd>
71 </dl>
72 <p class="Pp">Each object is identified by a SHA1 hash calculated over both the
73 object's header and the data stored in the object.</p>
74 </section>
75 <section class="Sh">
76 <h1 class="Sh" id="OBJECT_STORAGE"><a class="permalink" href="#OBJECT_STORAGE">OBJECT
77 STORAGE</a></h1>
78 <p class="Pp">Loose objects are stored as individual files beneath the directory
79 <span class="Pa">objects</span>, spread across 256 sub-directories named
80 after the 256 possible hexadecimal values of the first byte of an object
81 identifier. The name of the loose object file corresponds to the remaining
82 hexadecimal byte values of the object's identifier.</p>
83 <p class="Pp" id="NUL">A loose object file begins with a header which specifies
84 the type of object as an ASCII string, followed by an ASCII space character,
85 followed by the object data's size encoded as an ASCII number string. The
86 header is terminated by a
87 <a class="permalink" href="#NUL"><b class="Sy">NUL</b></a> character, and
88 the remainder of the file contains object data. Loose objects files are
89 compressed with <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 introduces two additional types of objects:</p>
93 <dl class="Bl-tag">
94 <dt>Offset Delta Objects</dt>
95 <dd>This object is represented as a delta against another object in the same
96 pack file. This other object is referred to by its offset in the pack
97 file.</dd>
98 <dt>Reference Delta Objects</dt>
99 <dd>This object is represented as a delta against another object in the same
100 pack file. The other object is referred to by its SHA1 object
101 identifier.</dd>
102 </dl>
103 <p class="Pp">Pack files are self-contained and may not refer to loose objects
104 or objects stored in other pack files. Deltified objects may refer to other
105 deltified objects as their delta base, forming chains of deltas. The
106 ultimate base of a delta chain must be an object of the same type as the
107 original object which is stored in deltified form.</p>
108 <p class="Pp">Each pack file is accompanied by a corresponding
109 <i class="Em">pack index</i> file, which lists the IDs and offsets of all
110 objects contained in the pack file.</p>
111 </section>
112 <section class="Sh">
113 <h1 class="Sh" id="REFERENCES"><a class="permalink" href="#REFERENCES">REFERENCES</a></h1>
114 <p class="Pp">A reference associates a name with an object ID. A prominent use
115 of references is providing names to branches in the repository by pointing
116 at commit objects which represent the current tip commit of a branch.
117 Because references may point to arbitrary object IDs their use is not
118 limited to branches.</p>
119 <p class="Pp">The name is a UTF-8 string with the following disallowed
120 characters: &#x2018;&#x00A0;&#x2019; (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
127 use.</p>
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
131 reference.</p>
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 or
138 <code class="Cm">gotadmin cleanup</code>.</p>
139 </section>
140 <section class="Sh">
141 <h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
142 <dl class="Bl-tag Bl-compact">
143 <dt><span class="Pa">HEAD</span></dt>
144 <dd>A reference to the current head commit of the Git work tree. In bare
145 repositories, this files serves as a default reference.</dd>
146 <dt><span class="Pa">ORIG_HEAD</span></dt>
147 <dd>Reference to original head commit. Set by some Git operations.</dd>
148 <dt><span class="Pa">FETCH_HEAD</span></dt>
149 <dd>Reference to a branch tip commit most recently fetched from another
150 repository.</dd>
151 <dt><span class="Pa">branches/</span></dt>
152 <dd>Legacy directory used by the deprecated Gogito Git interface.</dd>
153 <dt><span class="Pa">config</span></dt>
154 <dd>Git configuration file. See <a class="Xr">git-config(1)</a>.</dd>
155 <dt><span class="Pa">description</span></dt>
156 <dd>A human-readable description of the repository.</dd>
157 <dt><span class="Pa">got.conf</span></dt>
158 <dd>Configuration file for <a class="Xr">got(1)</a>. See
159 <a class="Xr">got.conf(5)</a>.</dd>
160 <dt><span class="Pa">hooks/</span></dt>
161 <dd>This directory contains hook scripts to run when certain events
162 occur.</dd>
163 <dt><span class="Pa">index</span></dt>
164 <dd>The file index used by <a class="Xr">git(1)</a>. This file is not used by
165 <a class="Xr">got(1)</a>, which uses the <a class="Xr">got-worktree(5)</a>
166 file index instead.</dd>
167 <dt><span class="Pa">info</span></dt>
168 <dd>Various configuration items.</dd>
169 <dt><span class="Pa">logs/</span></dt>
170 <dd>Directory where reflogs are stored.</dd>
171 <dt><span class="Pa">objects/</span></dt>
172 <dd>Loose and packed objects are stored in this directory.</dd>
173 <dt><span class="Pa">packed-refs</span></dt>
174 <dd>A file which stores references. Corresponding on-disk references take
175 precedence over those stored here.</dd>
176 <dt><span class="Pa">refs/</span></dt>
177 <dd>The default directory to store references in.</dd>
178 </dl>
179 <p class="Pp">A typical Git repository exposes a work tree which allows the user
180 to make changes to versioned files and create new commits. When a Git work
181 tree is present, the actual repository data is stored in a
182 <span class="Pa">.git</span> subfolder of the repository's root directory. A
183 Git repository without a work tree is known as a &#x201C;bare&#x201D;
184 repository. <a class="Xr">got(1)</a> does not make use of Git's work tree
185 and treats every repository as if it was bare.</p>
186 </section>
187 <section class="Sh">
188 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
189 ALSO</a></h1>
190 <p class="Pp"><a class="Xr">got(1)</a>, <a class="Xr">gotadmin(1)</a>,
191 <a class="Xr">deflate(3)</a>, <a class="Xr">SHA1(3)</a>,
192 <a class="Xr">got-worktree(5)</a>, <a class="Xr">got.conf(5)</a></p>
193 </section>
194 <section class="Sh">
195 <h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
196 <p class="Pp">The Git repository format was initially designed by Linus Torvalds
197 in 2005 and has since been extended by various people involved in the
198 development of the Git version control system.</p>
199 </section>
200 <section class="Sh">
201 <h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
202 <p class="Pp">The particular set of disallowed characters in reference names is
203 a consequence of design choices made for the command-line interface of
204 <a class="Xr">git(1)</a>. The same characters are disallowed by Got for
205 compatibility purposes. Got additionally prevents users from creating
206 reference names with a leading - (dash) character, because this is rarely
207 intended and not considered useful.</p>
208 </section>
209 </div>
210 <table class="foot">
211 <tr>
212 <td class="foot-date">November 23, 2021</td>
213 <td class="foot-os">OpenBSD 7.0</td>
214 </tr>
215 </table>
216 </body>
217 </html>