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 an hash calculated over both the
70 object's header and the data stored in the object. The hashing algorithm
71 used is specified in the repository <span class="Pa">config</span> file for
72 newer repositories while older ones use SHA1 implicitly.</p>
75 <h2 class="Sh" id="OBJECT_STORAGE"><a class="permalink" href="#OBJECT_STORAGE">OBJECT
77 <p class="Pp">Loose objects are stored as individual files beneath the directory
78 <span class="Pa">objects</span>, spread across 256 sub-directories named
79 after the 256 possible hexadecimal values of the first byte of an object
80 identifier. The name of the loose object file corresponds to the remaining
81 hexadecimal byte values of the object's identifier.</p>
82 <p class="Pp" id="NUL">A loose object file begins with a header which specifies
83 the type of object as an ASCII string, followed by an ASCII space character,
84 followed by the object data's size encoded as an ASCII number string. The
85 header is terminated by a
86 <a class="permalink" href="#NUL"><b class="Sy">NUL</b></a> character, and
87 the remainder of the file contains object data. Loose objects files are
88 compressed with <a class="Xr" aria-label="deflate, section
89 3">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>
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
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 object identifier.</dd>
102 <p class="Pp">Pack files are self-contained and may not refer to loose objects
103 or objects stored in other pack files. Deltified objects may refer to other
104 deltified objects as their delta base, forming chains of deltas. The
105 ultimate base of a delta chain must be an object of the same type as the
106 original object which is stored in deltified form.</p>
107 <p class="Pp">Each pack file is accompanied by a corresponding
108 <i class="Em">pack index</i> file, which lists the IDs and offsets of all
109 objects contained in the pack file.</p>
112 <h2 class="Sh" id="REFERENCES"><a class="permalink" href="#REFERENCES">REFERENCES</a></h2>
113 <p class="Pp">A reference associates a name with an object ID. A prominent use
114 of references is providing names to branches in the repository by pointing
115 at commit objects which represent the current tip commit of a branch.
116 Because references may point to arbitrary object IDs, their use is not
117 limited to branches.</p>
118 <p class="Pp">The name is a UTF-8 string with the following disallowed
119 characters: ‘ ’ (space), ~ (tilde), ^ (caret), :
120 (colon), ? (question mark), * (asterisk), [ (opening square bracket), \
121 (backslash). Additionally, the name may not contain the two-character
122 sequences //, .. , and @{.</p>
123 <p class="Pp">Reference names may optionally have multiple components separated
124 by the / (slash) character, forming a hierarchy of reference namespaces. Got
125 reserves the <span class="Pa">refs/got/</span> reference namespace for
127 <p class="Pp">A symbolic reference associates a name with the name of another
128 reference. The most prominent example is the <span class="Pa">HEAD</span>
129 reference which points at the name of the repository's default branch
131 <p class="Pp">References are stored either as a plain file within the
132 repository, typically under the <span class="Pa">refs/</span> directory, or
133 in the <span class="Pa">packed-refs</span> file which contains one reference
134 definition per line.</p>
135 <p class="Pp">Any object which is not directly or indirectly reachable via a
136 reference is subject to deletion by Git's garbage collector or
137 <code class="Cm">gotadmin cleanup</code>.</p>
140 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
141 <dl class="Bl-tag Bl-compact">
142 <dt><span class="Pa">HEAD</span></dt>
143 <dd>A reference to the current head commit of the Git work tree. In bare
144 repositories, this files serves as a default reference.</dd>
145 <dt><span class="Pa">ORIG_HEAD</span></dt>
146 <dd>Reference to original head commit. Set by some Git operations.</dd>
147 <dt><span class="Pa">FETCH_HEAD</span></dt>
148 <dd>Reference to a branch tip commit most recently fetched from another
150 <dt><span class="Pa">branches/</span></dt>
151 <dd>Legacy directory used by the deprecated Gogito Git interface.</dd>
152 <dt><span class="Pa">config</span></dt>
153 <dd>Git configuration file. See <a class="Xr" aria-label="git-config, section
154 1">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" aria-label="got, section
159 1">got(1)</a>. See <a class="Xr" aria-label="got.conf, section
160 5">got.conf(5)</a>.</dd>
161 <dt><span class="Pa">hooks/</span></dt>
162 <dd>This directory contains hook scripts to run when certain events
164 <dt><span class="Pa">index</span></dt>
165 <dd>The file index used by <a class="Xr" aria-label="git, section
166 1">git(1)</a>. This file is not used by <a class="Xr" aria-label="got,
167 section 1">got(1)</a>, which uses the
168 <a class="Xr" aria-label="got-worktree, section 5">got-worktree(5)</a>
169 file index instead.</dd>
170 <dt><span class="Pa">info</span></dt>
171 <dd>Various configuration items.</dd>
172 <dt><span class="Pa">logs/</span></dt>
173 <dd>Directory where reflogs are stored.</dd>
174 <dt><span class="Pa">objects/</span></dt>
175 <dd>Loose and packed objects are stored in this directory.</dd>
176 <dt><span class="Pa">packed-refs</span></dt>
177 <dd>A file which stores references. Corresponding on-disk references take
178 precedence over those stored here.</dd>
179 <dt><span class="Pa">refs/</span></dt>
180 <dd>The default directory to store references in.</dd>
182 <p class="Pp">A typical Git repository exposes a work tree which allows the user
183 to make changes to versioned files and create new commits. When a Git work
184 tree is present, the actual repository data is stored in a
185 <span class="Pa">.git</span> subfolder of the repository's root directory. A
186 Git repository without a work tree is known as a “bare”
187 repository. <a class="Xr" aria-label="got, section 1">got(1)</a> does not
188 make use of Git's work tree and treats every repository as if it was
192 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
194 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
195 <a class="Xr" aria-label="gotadmin, section 1">gotadmin(1)</a>,
196 <a class="Xr" aria-label="deflate, section 3">deflate(3)</a>,
197 <a class="Xr" aria-label="SHA1, section 3">SHA1(3)</a>,
198 <a class="Xr" aria-label="got-worktree, section 5">got-worktree(5)</a>,
199 <a class="Xr" aria-label="got.conf, section 5">got.conf(5)</a></p>
202 <h2 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h2>
203 <p class="Pp">The Git repository format was initially designed by Linus Torvalds
204 in 2005 and has since been extended by various people involved in the
205 development of the Git version control system.</p>
208 <h2 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h2>
209 <p class="Pp">The particular set of disallowed characters in reference names is
210 a consequence of design choices made for the command-line interface of
211 <a class="Xr" aria-label="git, section 1">git(1)</a>. The same characters
212 are disallowed by Got for compatibility purposes. Got additionally prevents
213 users from creating reference names with a leading - (dash) character,
214 because this is rarely intended and not considered useful.</p>
217 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
218 line"><span class="foot-left"></span><span class="foot-date">November 21,
219 2024</span> <span class="foot-os">OpenBSD 7.6</span></div>
