1 .\"
2 .\" Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
3 .\"
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd $Mdocdate$
17 .Dt GIT-REPOSITORY 5
18 .Os
19 .Sh NAME
20 .Nm git-repository
21 .Nd Git repository format
22 .Sh DESCRIPTION
23 A Git repository stores a series of versioned snapshots of a file hierarchy.
24 Conceptually, the repository's data model is a directed acyclic graph which
25 contains three types of objects as nodes:
26 .Bl -tag -width Ds
27 .It Blobs
28 The content of tracked files is stored in objects of type
29 .Em blob .
30 .It Trees
31 A
32 .Em tree
33 object points to any number of such blobs, and also to other trees in
34 order to represent a hierarchy of files and directories.
35 .It Commits
36 A
37 .Em commit
38 object points to the root element of one tree, and thus records the
39 state of this entire tree as a snapshot.
40 Commit objects are chained together to form lines of version control history.
41 Most commits have just one successor commit, but commits may be succeeded by
42 an arbitrary number of subsequent commits so that diverging lines of version
43 control history, known as
44 .Em branches ,
45 can be represented.
46 A commit which precedes another commit is referred to as that other commit's
47 .Em parent commit .
48 A commit with multiple parents unites disparate lines of history and is
49 known as a
50 .Em merge commit .
51 .Pp
52 .El
53 Each object is identified by a SHA1 hash calculated over both the object's
54 header and the data stored in the object.
55 .Sh OBJECT STORAGE
56 Loose objects are stored as individual files beneath the directory
57 .Pa objects ,
58 spread across 256 sub-directories named after the 256 possible hexadecimal
59 values of the first byte of an object identifier.
60 The name of the loose object file corresponds to the remaining hexadecimal
61 byte values of the object's identifier.
62 .Pp
63 A loose object file begins with a header which specifies the type of object
64 as an ASCII string, followed by an ASCII space character, followed by the
65 object data's size encoded as an ASCII number string.
66 The header is terminated by a
67 .Sy NUL
68 character, and the remainder of the file contains object data.
69 Loose objects files are compressed with
70 .Xr deflate 3 .
71 .Pp
72 Multiple objects can be bundled in a
73 .Em pack file
74 for better disk space efficiency and increased run-time performance.
75 The pack file format knows two additional types of objects in addition
76 to blobs, trees, and commits:
77 .Bl -tag -width Ds
78 .It Offset Delta Objects
79 This object is represented as a delta against another object in the
80 same pack file.
81 This other object is referred to by its offset in the pack file.
82 .It Reference Delta Objects
83 This object is represented as a delta against another object in the
84 same pack file.
85 The other object is referred to by its SHA1 object identifier.
86 .El
87 .Pp
88 Pack files are self-contained and may not refer to loose objects or
89 objects stored in other pack files.
90 Deltified objects may refer to other deltified objects as their delta base,
91 forming chains of deltas.
92 The ultimate base of a delta chain must be an object of the same type as
93 the original object which is stored in deltified form.
94 .Pp
95 Each pack file is accompanied by a corresponding
96 .Em pack index
97 file, which lists the IDs and offsets of all objects contained in the
98 pack file.
99 .Sh FILES
100 .Bl -tag -width packed-refs -compact
101 .It Pa HEAD
102 The current head commit of the Git work tree.
103 In bare repositories, this files serves as a default reference.
104 .It Pa ORIG_HEAD
105 The previous head commit of the Git work tree.
106 .It Pa FETCH_HEAD
107 The commit most recently fetched from another repository.
108 .It Pa branches/
109 Legacy directory used by the deprectated Gogito Git interface.
110 .It Pa config
111 Git configuration file. See
112 .Xr git-config 1 .
113 .It Pa description
114 A human-readable description of the repository.
115 .It Pa hooks/
116 This directory contains hook scripts to run when certain events occur.
117 .It Pa index
118 The file index used by
119 .Xr git 1 .
120 This file is not used by
121 .Xr got 1 ,
122 which uses the
123 .Xr got-worktree 5
124 file index instead.
125 .It Pa info
126 Various configuration items.
127 .It Pa logs/
128 Directory where reflogs are stored.
129 .It Pa objects/
130 Loose and packed objects are stored in this directory.
131 .It Pa packed-refs
132 A file which stores references.
133 Corresponding references found on disk take precedence over packed references.
134 .It Pa refs/
135 The default directory to store references in.
136 .El
137 .Sh SEE ALSO
138 .Xr got 1 ,
139 .Xr deflate 3 ,
140 .Xr SHA1 3 ,
141 .Xr got-worktree 5
142 .Sh HISTORY
143 The Git repository format was initially designed by Linus Torvalds in 2005
144 and has since been extended by various people involved in the development
145 of the Git version control system.