2 5e5560e1 2018-08-01 stsp .\" Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
4 5e5560e1 2018-08-01 stsp .\" Permission to use, copy, modify, and distribute this software for any
5 5e5560e1 2018-08-01 stsp .\" purpose with or without fee is hereby granted, provided that the above
6 5e5560e1 2018-08-01 stsp .\" copyright notice and this permission notice appear in all copies.
8 5e5560e1 2018-08-01 stsp .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 5e5560e1 2018-08-01 stsp .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 5e5560e1 2018-08-01 stsp .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 5e5560e1 2018-08-01 stsp .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 5e5560e1 2018-08-01 stsp .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 5e5560e1 2018-08-01 stsp .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 5e5560e1 2018-08-01 stsp .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 5e5560e1 2018-08-01 stsp .Dd $Mdocdate$
17 5e5560e1 2018-08-01 stsp .Dt GIT-REPOSITORY 5
20 5e5560e1 2018-08-01 stsp .Nm git-repository
21 4639d500 2018-08-01 stsp .Nd Git repository format
22 5e5560e1 2018-08-01 stsp .Sh DESCRIPTION
23 4639d500 2018-08-01 stsp A Git repository stores a series of versioned snapshots of a file hierarchy.
24 03301f46 2019-03-26 stsp Conceptually, the repository's data model is a directed acyclic graph which
25 03301f46 2019-03-26 stsp contains three types of objects as nodes:
26 03301f46 2019-03-26 stsp .Bl -tag -width Ds
28 5e5560e1 2018-08-01 stsp The content of tracked files is stored in objects of type
33 5e5560e1 2018-08-01 stsp object points to any number of such blobs, and also to other trees in
34 4639d500 2018-08-01 stsp order to represent a hierarchy of files and directories.
38 5e5560e1 2018-08-01 stsp object points to the root element of one tree, and thus records the
39 5e5560e1 2018-08-01 stsp state of this entire tree as a snapshot.
40 03301f46 2019-03-26 stsp Commit objects are chained together to form lines of version control history.
41 03301f46 2019-03-26 stsp Most commits have just one successor commit, but commits may be succeeded by
42 03301f46 2019-03-26 stsp an arbitrary number of subsequent commits so that diverging lines of version
43 03301f46 2019-03-26 stsp control history, known as
44 5e5560e1 2018-08-01 stsp .Em branches ,
45 5e5560e1 2018-08-01 stsp can be represented.
46 03301f46 2019-03-26 stsp A commit which precedes another commit is referred to as that other commit's
47 5e5560e1 2018-08-01 stsp .Em parent commit .
48 03301f46 2019-03-26 stsp A commit with multiple parents unites disparate lines of history and is
50 5e5560e1 2018-08-01 stsp .Em merge commit .
53 03301f46 2019-03-26 stsp Each object is identified by a SHA1 hash calculated over both the object's
54 4639d500 2018-08-01 stsp header and the data stored in the object.
55 4639d500 2018-08-01 stsp .Sh OBJECT STORAGE
56 4639d500 2018-08-01 stsp Loose objects are stored as individual files beneath the directory
57 4639d500 2018-08-01 stsp .Pa objects ,
58 4639d500 2018-08-01 stsp spread across 256 sub-directories named after the 256 possible hexadecimal
59 4639d500 2018-08-01 stsp values of the first byte of an object identifier.
60 e0486a23 2018-08-01 stsp The name of the loose object file corresponds to the remaining hexadecimal
61 e0486a23 2018-08-01 stsp byte values of the object's identifier.
63 4639d500 2018-08-01 stsp A loose object file begins with a header which specifies the type of object
64 4639d500 2018-08-01 stsp as an ASCII string, followed by an ASCII space character, followed by the
65 4639d500 2018-08-01 stsp object data's size encoded as an ASCII number string.
66 4639d500 2018-08-01 stsp The header is terminated by a
68 4639d500 2018-08-01 stsp character, and the remainder of the file contains object data.
69 4639d500 2018-08-01 stsp Loose objects files are compressed with
70 5e5560e1 2018-08-01 stsp .Xr deflate 3 .
72 4639d500 2018-08-01 stsp Multiple objects can be bundled in a
73 5e5560e1 2018-08-01 stsp .Em pack file
74 4639d500 2018-08-01 stsp for better disk space efficiency and increased run-time performance.
75 03301f46 2019-03-26 stsp The pack file format knows two additional types of objects in addition
76 03301f46 2019-03-26 stsp to blobs, trees, and commits:
77 03301f46 2019-03-26 stsp .Bl -tag -width Ds
78 03301f46 2019-03-26 stsp .It Offset Delta Objects
79 3d50f291 2019-03-26 stsp This object is represented as a delta against another object in the
80 3d50f291 2019-03-26 stsp same pack file.
81 3d50f291 2019-03-26 stsp This other object is referred to by its offset in the pack file.
82 03301f46 2019-03-26 stsp .It Reference Delta Objects
83 3d50f291 2019-03-26 stsp This object is represented as a delta against another object in the
84 3d50f291 2019-03-26 stsp same pack file.
85 3d50f291 2019-03-26 stsp The other object is referred to by its SHA1 object identifier.
88 03301f46 2019-03-26 stsp Pack files are self-contained and may not refer to loose objects or
89 03301f46 2019-03-26 stsp objects stored in other pack files.
90 03301f46 2019-03-26 stsp Deltified objects may refer to other deltified objects as their delta base,
91 03301f46 2019-03-26 stsp forming chains of deltas.
92 03301f46 2019-03-26 stsp The ultimate base of a delta chain must be an object of the same type as
93 03301f46 2019-03-26 stsp the original object which is stored in deltified form.
95 03301f46 2019-03-26 stsp Each pack file is accompanied by a corresponding
96 03301f46 2019-03-26 stsp .Em pack index
97 03301f46 2019-03-26 stsp file, which lists the IDs and offsets of all objects contained in the
99 569f7b63 2019-07-14 stsp .Sh REFERENCES
100 569f7b63 2019-07-14 stsp A reference associates a name with an object ID.
101 569f7b63 2019-07-14 stsp A prominent use of references is providing names to branches in the
102 569f7b63 2019-07-14 stsp repository by pointing at commit objects which represent the current
103 569f7b63 2019-07-14 stsp tip commit of a branch.
104 569f7b63 2019-07-14 stsp Because references may point to arbitrary object IDs their use
105 569f7b63 2019-07-14 stsp is not limited to branches.
107 569f7b63 2019-07-14 stsp The name is a UTF-8 string with the following disallowed characters:
113 569f7b63 2019-07-14 stsp ? (question mark),
114 569f7b63 2019-07-14 stsp * (asterisk),
115 569f7b63 2019-07-14 stsp [ (opening square bracket),
116 569f7b63 2019-07-14 stsp \\ (backslash).
117 569f7b63 2019-07-14 stsp Additionally, the name may not contain the two-character sequences
118 569f7b63 2019-07-14 stsp //, .. , and @{.
120 569f7b63 2019-07-14 stsp Reference names may optionally have multiple components separated by
121 569f7b63 2019-07-14 stsp the / (slash) character, forming a hierarchy of reference namespaces.
122 569f7b63 2019-07-14 stsp Got reserves the
124 569f7b63 2019-07-14 stsp reference namespace for internal use.
126 569f7b63 2019-07-14 stsp A symbolic reference associates a name with the name of another reference.
127 569f7b63 2019-07-14 stsp The most prominent example is the
129 569f7b63 2019-07-14 stsp reference which points at the name of the repository's default branch
132 569f7b63 2019-07-14 stsp References are stored either as a plain file within the repository,
133 569f7b63 2019-07-14 stsp typically under the
135 569f7b63 2019-07-14 stsp directory, or in the
136 569f7b63 2019-07-14 stsp .Pa packed-refs
137 569f7b63 2019-07-14 stsp file which contains one reference definition per line.
139 d3de4379 2019-07-15 stsp Any object which is not directly or indirectly reachable via a reference
140 d3de4379 2019-07-15 stsp is subject to deletion by Git's garbage collector.
142 03301f46 2019-03-26 stsp .Bl -tag -width packed-refs -compact
143 5e5560e1 2018-08-01 stsp .It Pa HEAD
144 a3a2b44e 2019-03-26 stsp A reference to the current head commit of the Git work tree.
145 03301f46 2019-03-26 stsp In bare repositories, this files serves as a default reference.
146 5e5560e1 2018-08-01 stsp .It Pa ORIG_HEAD
147 a3a2b44e 2019-03-26 stsp Reference to original head commit.
148 a3a2b44e 2019-03-26 stsp Set by some Git operations.
149 5e5560e1 2018-08-01 stsp .It Pa FETCH_HEAD
150 18779d58 2019-05-10 jcs Reference to a branch tip commit most recently fetched from another repository.
151 5e5560e1 2018-08-01 stsp .It Pa branches/
152 3190d68a 2019-07-14 stsp Legacy directory used by the deprecated Gogito Git interface.
153 5e5560e1 2018-08-01 stsp .It Pa config
154 03301f46 2019-03-26 stsp Git configuration file. See
155 03301f46 2019-03-26 stsp .Xr git-config 1 .
156 5e5560e1 2018-08-01 stsp .It Pa description
157 03301f46 2019-03-26 stsp A human-readable description of the repository.
158 5e5560e1 2018-08-01 stsp .It Pa hooks/
159 03301f46 2019-03-26 stsp This directory contains hook scripts to run when certain events occur.
160 5e5560e1 2018-08-01 stsp .It Pa index
161 03301f46 2019-03-26 stsp The file index used by
162 03301f46 2019-03-26 stsp .Xr git 1 .
163 03301f46 2019-03-26 stsp This file is not used by
164 03301f46 2019-03-26 stsp .Xr got 1 ,
165 03301f46 2019-03-26 stsp which uses the
166 03301f46 2019-03-26 stsp .Xr got-worktree 5
167 03301f46 2019-03-26 stsp file index instead.
168 5e5560e1 2018-08-01 stsp .It Pa info
169 03301f46 2019-03-26 stsp Various configuration items.
170 5e5560e1 2018-08-01 stsp .It Pa logs/
171 03301f46 2019-03-26 stsp Directory where reflogs are stored.
172 5e5560e1 2018-08-01 stsp .It Pa objects/
173 03301f46 2019-03-26 stsp Loose and packed objects are stored in this directory.
174 5e5560e1 2018-08-01 stsp .It Pa packed-refs
175 03301f46 2019-03-26 stsp A file which stores references.
176 a3a2b44e 2019-03-26 stsp Corresponding on-disk references take precedence over those stored here.
177 5e5560e1 2018-08-01 stsp .It Pa refs/
178 03301f46 2019-03-26 stsp The default directory to store references in.
181 4dfb2f0f 2019-03-26 stsp A typical Git repository exposes a work tree which allows the user to make
182 4dfb2f0f 2019-03-26 stsp changes to versioned files and create new commits.
183 4dfb2f0f 2019-03-26 stsp When a Git work tree is present, the actual repository data is stored in a
185 4dfb2f0f 2019-03-26 stsp subfolder of the repository's root directory.
186 4dfb2f0f 2019-03-26 stsp A Git repository without a work tree is known as a
188 4dfb2f0f 2019-03-26 stsp repository.
190 4dfb2f0f 2019-03-26 stsp does not make use of Git's work tree and treats every repository as if it
192 5e5560e1 2018-08-01 stsp .Sh SEE ALSO
193 5e5560e1 2018-08-01 stsp .Xr got 1 ,
194 5e5560e1 2018-08-01 stsp .Xr deflate 3 ,
195 4639d500 2018-08-01 stsp .Xr SHA1 3 ,
196 5e5560e1 2018-08-01 stsp .Xr got-worktree 5
197 5e5560e1 2018-08-01 stsp .Sh HISTORY
198 4639d500 2018-08-01 stsp The Git repository format was initially designed by Linus Torvalds in 2005
199 4639d500 2018-08-01 stsp and has since been extended by various people involved in the development
200 4639d500 2018-08-01 stsp of the Git version control system.
201 569f7b63 2019-07-14 stsp .Sh CAVEATS
202 569f7b63 2019-07-14 stsp The particular set of disallowed characters in reference names is a
203 569f7b63 2019-07-14 stsp consequence of design choices made for the command-line interface of
204 569f7b63 2019-07-14 stsp .Xr git 1 .
205 569f7b63 2019-07-14 stsp The same characters are disallowed by Got for compatibility purposes.
206 569f7b63 2019-07-14 stsp Got additionaly prevents users from creating reference names with
207 569f7b63 2019-07-14 stsp a leading - (dash) character, because this is rarely intended and
208 569f7b63 2019-07-14 stsp not considered useful.
