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 .
54 b3cd068e 2019-08-22 stsp object associates an user-defined label with another object, which is
55 b3cd068e 2019-08-22 stsp typically a commit object.
56 b3cd068e 2019-08-22 stsp Tag objects also contains a tag message, as well as author and
57 b3cd068e 2019-08-22 stsp timestamp information.
60 03301f46 2019-03-26 stsp Each object is identified by a SHA1 hash calculated over both the object's
61 4639d500 2018-08-01 stsp header and the data stored in the object.
62 4639d500 2018-08-01 stsp .Sh OBJECT STORAGE
63 4639d500 2018-08-01 stsp Loose objects are stored as individual files beneath the directory
64 4639d500 2018-08-01 stsp .Pa objects ,
65 4639d500 2018-08-01 stsp spread across 256 sub-directories named after the 256 possible hexadecimal
66 4639d500 2018-08-01 stsp values of the first byte of an object identifier.
67 e0486a23 2018-08-01 stsp The name of the loose object file corresponds to the remaining hexadecimal
68 e0486a23 2018-08-01 stsp byte values of the object's identifier.
70 4639d500 2018-08-01 stsp A loose object file begins with a header which specifies the type of object
71 4639d500 2018-08-01 stsp as an ASCII string, followed by an ASCII space character, followed by the
72 4639d500 2018-08-01 stsp object data's size encoded as an ASCII number string.
73 4639d500 2018-08-01 stsp The header is terminated by a
75 4639d500 2018-08-01 stsp character, and the remainder of the file contains object data.
76 4639d500 2018-08-01 stsp Loose objects files are compressed with
77 5e5560e1 2018-08-01 stsp .Xr deflate 3 .
79 4639d500 2018-08-01 stsp Multiple objects can be bundled in a
80 5e5560e1 2018-08-01 stsp .Em pack file
81 4639d500 2018-08-01 stsp for better disk space efficiency and increased run-time performance.
82 03301f46 2019-03-26 stsp The pack file format knows two additional types of objects in addition
83 03301f46 2019-03-26 stsp to blobs, trees, and commits:
84 03301f46 2019-03-26 stsp .Bl -tag -width Ds
85 03301f46 2019-03-26 stsp .It Offset Delta Objects
86 3d50f291 2019-03-26 stsp This object is represented as a delta against another object in the
87 3d50f291 2019-03-26 stsp same pack file.
88 3d50f291 2019-03-26 stsp This other object is referred to by its offset in the pack file.
89 03301f46 2019-03-26 stsp .It Reference Delta Objects
90 3d50f291 2019-03-26 stsp This object is represented as a delta against another object in the
91 3d50f291 2019-03-26 stsp same pack file.
92 3d50f291 2019-03-26 stsp The other object is referred to by its SHA1 object identifier.
95 03301f46 2019-03-26 stsp Pack files are self-contained and may not refer to loose objects or
96 03301f46 2019-03-26 stsp objects stored in other pack files.
97 03301f46 2019-03-26 stsp Deltified objects may refer to other deltified objects as their delta base,
98 03301f46 2019-03-26 stsp forming chains of deltas.
99 03301f46 2019-03-26 stsp The ultimate base of a delta chain must be an object of the same type as
100 03301f46 2019-03-26 stsp the original object which is stored in deltified form.
102 03301f46 2019-03-26 stsp Each pack file is accompanied by a corresponding
103 03301f46 2019-03-26 stsp .Em pack index
104 03301f46 2019-03-26 stsp file, which lists the IDs and offsets of all objects contained in the
106 569f7b63 2019-07-14 stsp .Sh REFERENCES
107 569f7b63 2019-07-14 stsp A reference associates a name with an object ID.
108 569f7b63 2019-07-14 stsp A prominent use of references is providing names to branches in the
109 569f7b63 2019-07-14 stsp repository by pointing at commit objects which represent the current
110 569f7b63 2019-07-14 stsp tip commit of a branch.
111 569f7b63 2019-07-14 stsp Because references may point to arbitrary object IDs their use
112 569f7b63 2019-07-14 stsp is not limited to branches.
114 569f7b63 2019-07-14 stsp The name is a UTF-8 string with the following disallowed characters:
115 1dd86744 2019-08-12 anthony .Sq \ \&
117 1dd86744 2019-08-12 anthony \(a~ (tilde),
118 1dd86744 2019-08-12 anthony \(a^ (caret),
120 569f7b63 2019-07-14 stsp ? (question mark),
121 569f7b63 2019-07-14 stsp * (asterisk),
122 569f7b63 2019-07-14 stsp [ (opening square bracket),
123 569f7b63 2019-07-14 stsp \\ (backslash).
124 569f7b63 2019-07-14 stsp Additionally, the name may not contain the two-character sequences
125 569f7b63 2019-07-14 stsp //, .. , and @{.
127 569f7b63 2019-07-14 stsp Reference names may optionally have multiple components separated by
128 569f7b63 2019-07-14 stsp the / (slash) character, forming a hierarchy of reference namespaces.
129 569f7b63 2019-07-14 stsp Got reserves the
131 569f7b63 2019-07-14 stsp reference namespace for internal use.
133 569f7b63 2019-07-14 stsp A symbolic reference associates a name with the name of another reference.
134 569f7b63 2019-07-14 stsp The most prominent example is the
136 569f7b63 2019-07-14 stsp reference which points at the name of the repository's default branch
139 569f7b63 2019-07-14 stsp References are stored either as a plain file within the repository,
140 569f7b63 2019-07-14 stsp typically under the
142 569f7b63 2019-07-14 stsp directory, or in the
143 569f7b63 2019-07-14 stsp .Pa packed-refs
144 569f7b63 2019-07-14 stsp file which contains one reference definition per line.
146 d3de4379 2019-07-15 stsp Any object which is not directly or indirectly reachable via a reference
147 d3de4379 2019-07-15 stsp is subject to deletion by Git's garbage collector.
149 03301f46 2019-03-26 stsp .Bl -tag -width packed-refs -compact
150 5e5560e1 2018-08-01 stsp .It Pa HEAD
151 a3a2b44e 2019-03-26 stsp A reference to the current head commit of the Git work tree.
152 03301f46 2019-03-26 stsp In bare repositories, this files serves as a default reference.
153 5e5560e1 2018-08-01 stsp .It Pa ORIG_HEAD
154 a3a2b44e 2019-03-26 stsp Reference to original head commit.
155 a3a2b44e 2019-03-26 stsp Set by some Git operations.
156 5e5560e1 2018-08-01 stsp .It Pa FETCH_HEAD
157 18779d58 2019-05-10 jcs Reference to a branch tip commit most recently fetched from another repository.
158 5e5560e1 2018-08-01 stsp .It Pa branches/
159 3190d68a 2019-07-14 stsp Legacy directory used by the deprecated Gogito Git interface.
160 5e5560e1 2018-08-01 stsp .It Pa config
161 1dd86744 2019-08-12 anthony Git configuration file.
163 03301f46 2019-03-26 stsp .Xr git-config 1 .
164 5e5560e1 2018-08-01 stsp .It Pa description
165 03301f46 2019-03-26 stsp A human-readable description of the repository.
166 5e5560e1 2018-08-01 stsp .It Pa hooks/
167 03301f46 2019-03-26 stsp This directory contains hook scripts to run when certain events occur.
168 5e5560e1 2018-08-01 stsp .It Pa index
169 03301f46 2019-03-26 stsp The file index used by
170 03301f46 2019-03-26 stsp .Xr git 1 .
171 03301f46 2019-03-26 stsp This file is not used by
172 03301f46 2019-03-26 stsp .Xr got 1 ,
173 03301f46 2019-03-26 stsp which uses the
174 03301f46 2019-03-26 stsp .Xr got-worktree 5
175 03301f46 2019-03-26 stsp file index instead.
176 5e5560e1 2018-08-01 stsp .It Pa info
177 03301f46 2019-03-26 stsp Various configuration items.
178 5e5560e1 2018-08-01 stsp .It Pa logs/
179 03301f46 2019-03-26 stsp Directory where reflogs are stored.
180 5e5560e1 2018-08-01 stsp .It Pa objects/
181 03301f46 2019-03-26 stsp Loose and packed objects are stored in this directory.
182 5e5560e1 2018-08-01 stsp .It Pa packed-refs
183 03301f46 2019-03-26 stsp A file which stores references.
184 a3a2b44e 2019-03-26 stsp Corresponding on-disk references take precedence over those stored here.
185 5e5560e1 2018-08-01 stsp .It Pa refs/
186 03301f46 2019-03-26 stsp The default directory to store references in.
189 4dfb2f0f 2019-03-26 stsp A typical Git repository exposes a work tree which allows the user to make
190 4dfb2f0f 2019-03-26 stsp changes to versioned files and create new commits.
191 4dfb2f0f 2019-03-26 stsp When a Git work tree is present, the actual repository data is stored in a
193 4dfb2f0f 2019-03-26 stsp subfolder of the repository's root directory.
194 4dfb2f0f 2019-03-26 stsp A Git repository without a work tree is known as a
196 4dfb2f0f 2019-03-26 stsp repository.
198 4dfb2f0f 2019-03-26 stsp does not make use of Git's work tree and treats every repository as if it
200 5e5560e1 2018-08-01 stsp .Sh SEE ALSO
201 5e5560e1 2018-08-01 stsp .Xr got 1 ,
202 5e5560e1 2018-08-01 stsp .Xr deflate 3 ,
203 4639d500 2018-08-01 stsp .Xr SHA1 3 ,
204 5e5560e1 2018-08-01 stsp .Xr got-worktree 5
205 5e5560e1 2018-08-01 stsp .Sh HISTORY
206 4639d500 2018-08-01 stsp The Git repository format was initially designed by Linus Torvalds in 2005
207 4639d500 2018-08-01 stsp and has since been extended by various people involved in the development
208 4639d500 2018-08-01 stsp of the Git version control system.
209 569f7b63 2019-07-14 stsp .Sh CAVEATS
210 569f7b63 2019-07-14 stsp The particular set of disallowed characters in reference names is a
211 569f7b63 2019-07-14 stsp consequence of design choices made for the command-line interface of
212 569f7b63 2019-07-14 stsp .Xr git 1 .
213 569f7b63 2019-07-14 stsp The same characters are disallowed by Got for compatibility purposes.
214 bc3056e3 2019-08-18 stsp Got additionally prevents users from creating reference names with
215 569f7b63 2019-07-14 stsp a leading - (dash) character, because this is rarely intended and
216 569f7b63 2019-07-14 stsp not considered useful.
