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