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 9eba2c58 2020-04-19 stsp object associates a user-defined label with another object, which is
55 b3cd068e 2019-08-22 stsp typically a commit object.
56 ef9e2ed7 2020-04-19 stsp Tag objects also contain 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 089fc4e0 2020-03-20 stsp The pack file format introduces two additional types of objects:
83 03301f46 2019-03-26 stsp .Bl -tag -width Ds
84 03301f46 2019-03-26 stsp .It Offset Delta Objects
85 3d50f291 2019-03-26 stsp This object is represented as a delta against another object in the
86 3d50f291 2019-03-26 stsp same pack file.
87 3d50f291 2019-03-26 stsp This other object is referred to by its offset in the pack file.
88 03301f46 2019-03-26 stsp .It Reference Delta Objects
89 3d50f291 2019-03-26 stsp This object is represented as a delta against another object in the
90 3d50f291 2019-03-26 stsp same pack file.
91 3d50f291 2019-03-26 stsp The other object is referred to by its SHA1 object identifier.
94 03301f46 2019-03-26 stsp Pack files are self-contained and may not refer to loose objects or
95 03301f46 2019-03-26 stsp objects stored in other pack files.
96 03301f46 2019-03-26 stsp Deltified objects may refer to other deltified objects as their delta base,
97 03301f46 2019-03-26 stsp forming chains of deltas.
98 03301f46 2019-03-26 stsp The ultimate base of a delta chain must be an object of the same type as
99 03301f46 2019-03-26 stsp the original object which is stored in deltified form.
101 03301f46 2019-03-26 stsp Each pack file is accompanied by a corresponding
102 03301f46 2019-03-26 stsp .Em pack index
103 03301f46 2019-03-26 stsp file, which lists the IDs and offsets of all objects contained in the
105 569f7b63 2019-07-14 stsp .Sh REFERENCES
106 569f7b63 2019-07-14 stsp A reference associates a name with an object ID.
107 569f7b63 2019-07-14 stsp A prominent use of references is providing names to branches in the
108 569f7b63 2019-07-14 stsp repository by pointing at commit objects which represent the current
109 569f7b63 2019-07-14 stsp tip commit of a branch.
110 e38d4cde 2022-03-21 naddy Because references may point to arbitrary object IDs, their use
111 569f7b63 2019-07-14 stsp is not limited to branches.
113 569f7b63 2019-07-14 stsp The name is a UTF-8 string with the following disallowed characters:
114 1dd86744 2019-08-12 anthony .Sq \ \&
116 1dd86744 2019-08-12 anthony \(a~ (tilde),
117 1dd86744 2019-08-12 anthony \(a^ (caret),
119 569f7b63 2019-07-14 stsp ? (question mark),
120 569f7b63 2019-07-14 stsp * (asterisk),
121 569f7b63 2019-07-14 stsp [ (opening square bracket),
122 569f7b63 2019-07-14 stsp \\ (backslash).
123 569f7b63 2019-07-14 stsp Additionally, the name may not contain the two-character sequences
124 569f7b63 2019-07-14 stsp //, .. , and @{.
126 569f7b63 2019-07-14 stsp Reference names may optionally have multiple components separated by
127 569f7b63 2019-07-14 stsp the / (slash) character, forming a hierarchy of reference namespaces.
128 569f7b63 2019-07-14 stsp Got reserves the
129 d2ff61d7 2023-04-20 stsp .Pa refs/got/
130 569f7b63 2019-07-14 stsp reference namespace for internal use.
132 569f7b63 2019-07-14 stsp A symbolic reference associates a name with the name of another reference.
133 569f7b63 2019-07-14 stsp The most prominent example is the
135 569f7b63 2019-07-14 stsp reference which points at the name of the repository's default branch
138 569f7b63 2019-07-14 stsp References are stored either as a plain file within the repository,
139 569f7b63 2019-07-14 stsp typically under the
141 569f7b63 2019-07-14 stsp directory, or in the
142 569f7b63 2019-07-14 stsp .Pa packed-refs
143 569f7b63 2019-07-14 stsp file which contains one reference definition per line.
145 d3de4379 2019-07-15 stsp Any object which is not directly or indirectly reachable via a reference
146 e6786710 2021-07-03 stsp is subject to deletion by Git's garbage collector or
147 e6786710 2021-07-03 stsp .Cm gotadmin cleanup .
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 50b0790e 2020-09-11 stsp .It Pa got.conf
167 50b0790e 2020-09-11 stsp Configuration file for
168 50b0790e 2020-09-11 stsp .Xr got 1 .
170 50b0790e 2020-09-11 stsp .Xr got.conf 5 .
171 5e5560e1 2018-08-01 stsp .It Pa hooks/
172 03301f46 2019-03-26 stsp This directory contains hook scripts to run when certain events occur.
173 5e5560e1 2018-08-01 stsp .It Pa index
174 03301f46 2019-03-26 stsp The file index used by
175 03301f46 2019-03-26 stsp .Xr git 1 .
176 03301f46 2019-03-26 stsp This file is not used by
177 03301f46 2019-03-26 stsp .Xr got 1 ,
178 03301f46 2019-03-26 stsp which uses the
179 03301f46 2019-03-26 stsp .Xr got-worktree 5
180 03301f46 2019-03-26 stsp file index instead.
181 5e5560e1 2018-08-01 stsp .It Pa info
182 03301f46 2019-03-26 stsp Various configuration items.
183 5e5560e1 2018-08-01 stsp .It Pa logs/
184 03301f46 2019-03-26 stsp Directory where reflogs are stored.
185 5e5560e1 2018-08-01 stsp .It Pa objects/
186 03301f46 2019-03-26 stsp Loose and packed objects are stored in this directory.
187 5e5560e1 2018-08-01 stsp .It Pa packed-refs
188 03301f46 2019-03-26 stsp A file which stores references.
189 a3a2b44e 2019-03-26 stsp Corresponding on-disk references take precedence over those stored here.
190 5e5560e1 2018-08-01 stsp .It Pa refs/
191 03301f46 2019-03-26 stsp The default directory to store references in.
194 4dfb2f0f 2019-03-26 stsp A typical Git repository exposes a work tree which allows the user to make
195 4dfb2f0f 2019-03-26 stsp changes to versioned files and create new commits.
196 4dfb2f0f 2019-03-26 stsp When a Git work tree is present, the actual repository data is stored in a
198 4dfb2f0f 2019-03-26 stsp subfolder of the repository's root directory.
199 4dfb2f0f 2019-03-26 stsp A Git repository without a work tree is known as a
201 4dfb2f0f 2019-03-26 stsp repository.
203 4dfb2f0f 2019-03-26 stsp does not make use of Git's work tree and treats every repository as if it
205 5e5560e1 2018-08-01 stsp .Sh SEE ALSO
206 5e5560e1 2018-08-01 stsp .Xr got 1 ,
207 0a79feb1 2021-04-10 stsp .Xr gotadmin 1 ,
208 5e5560e1 2018-08-01 stsp .Xr deflate 3 ,
209 4639d500 2018-08-01 stsp .Xr SHA1 3 ,
210 6c19a3dc 2021-04-10 stsp .Xr got-worktree 5 ,
211 50b0790e 2020-09-11 stsp .Xr got.conf 5
212 5e5560e1 2018-08-01 stsp .Sh HISTORY
213 4639d500 2018-08-01 stsp The Git repository format was initially designed by Linus Torvalds in 2005
214 4639d500 2018-08-01 stsp and has since been extended by various people involved in the development
215 4639d500 2018-08-01 stsp of the Git version control system.
216 569f7b63 2019-07-14 stsp .Sh CAVEATS
217 569f7b63 2019-07-14 stsp The particular set of disallowed characters in reference names is a
218 569f7b63 2019-07-14 stsp consequence of design choices made for the command-line interface of
219 569f7b63 2019-07-14 stsp .Xr git 1 .
220 569f7b63 2019-07-14 stsp The same characters are disallowed by Got for compatibility purposes.
221 bc3056e3 2019-08-18 stsp Got additionally prevents users from creating reference names with
222 569f7b63 2019-07-14 stsp a leading - (dash) character, because this is rarely intended and
223 569f7b63 2019-07-14 stsp not considered useful.
