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 The repository's core data model is a directed acyclic graph which
25 contains three types of objects as nodes.
26 .Pp
27 The content of tracked files is stored in objects of type
28 .Em blob .
29 .Pp
30 A
31 .Em tree
32 object points to any number of such blobs, and also to other trees in
33 order to represent a hierarchy of files and directories.
34 .Pp
35 A
36 .Em commit
37 object points to the root element of one tree, and thus records the
38 state of this entire tree as a snapshot.
39 Commit objects are chained together to form a line of history of snapshots.
40 A given commit can be suceeded by an arbitrary number of subsequent commits,
41 such that diverging lines of version control history, known as
42 .Em branches ,
43 can be represented.
44 A commit which preceeds another commit is referred to as that other commit's
45 .Em parent commit .
46 A commit with multiple parents reunites diverged lines of history and is
47 known as a
48 .Em merge commit .
49 .Pp
50 Each object is identified by a SHA1 hash calculated over the object's
51 header and the data stored in the object.
52 .Sh OBJECT STORAGE
53 Loose objects are stored as individual files beneath the directory
54 .Pa objects ,
55 spread across 256 sub-directories named after the 256 possible hexadecimal
56 values of the first byte of an object identifier.
57 The name of the loose object file corresponds to the remaining hexadecimal
58 byte values of the object's identifier.
59 .Pp
60 A loose object file begins with a header which specifies the type of object
61 as an ASCII string, followed by an ASCII space character, followed by the
62 object data's size encoded as an ASCII number string.
63 The header is terminated by a
64 .Sy NUL
65 character, and the remainder of the file contains object data.
66 Loose objects files are compressed with
67 .Xr deflate 3 .
68 .Pp
69 Multiple objects can be bundled in a
70 .Em pack file
71 for better disk space efficiency and increased run-time performance.
72 The pack file format adds two additional types of objects:
73 offset delta objects and reference delta objects.
74 .Pp
75 TODO describe pack file format
76 .Pp
77 .Sh FILES
78 .Bl -tag -width /etc/rpc -compact
79 .It Pa HEAD
80 .It Pa ORIG_HEAD
81 .It Pa FETCH_HEAD
82 .It Pa branches/
83 .It Pa config
84 .It Pa description
85 .It Pa hooks/
86 .It Pa index
87 .It Pa info
88 .It Pa logs/
89 .It Pa objects/
90 .It Pa packed-refs
91 .It Pa refs/
92 .El
93 .Sh SEE ALSO
94 .Xr got 1 ,
95 .Xr deflate 3 ,
96 .Xr SHA1 3 ,
97 .Xr got-worktree 5
98 .Sh HISTORY
99 The Git repository format was initially designed by Linus Torvalds in 2005
100 and has since been extended by various people involved in the development
101 of the Git version control system.