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