Blame


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