2 .\" Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
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.
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.
21 .Nd Game of Trees work tree format
25 stores a file hierarchy which corresponds to a versioned
26 snapshot stored in a Git repository.
27 The work tree's meta data is stored in the
30 A work tree is created with
32 and is required to make changes to a Git repository with
35 A work tree stores the path to its Git repository, the name of a reference
36 to the branch which files were checked out from, and the ID of a commit on
37 this branch known as the
40 File meta-data is stored in a structured file called the
42 which tracks the status of file modifications, additions, and deletions,
43 relative to the base commit in the repository.
44 The file index contains a series of records, and each such record contains
45 the following status information for a particular file:
47 .It Copy of filesystem meta-data
48 Timestamp, file size, and file ownership information from
50 This is only used to detect file modifications and is never applied
51 back to the filesystem.
52 File permissions are not tracked, except for the executable bit.
53 When versioned files are checked out into the work tree, the current
57 The SHA1 hash of the blob object which corresponds to the contents
58 of this file in the repository.
59 The hash is stored as binary data.
61 The SHA1 hash of the commit object the file was checked out from.
62 The hash is stored as binary data.
63 This data is used to detect past incomplete update operations.
64 Entries which do not match the work tree's base commit may still need
65 to be updated to match file content stored in the base commit.
67 This field contains the length, according to
69 of path data which follows, and the following flags:
72 Reflects the added, modified, or deleted staged state of a path staged with
75 The entry was added to the file index in memory and does not exist in file
76 index data read from disk.
77 This happens to files which are added to the work tree while operations
87 This flag is always cleared before the entry is written to disk.
89 The entry's on-disk file content in the work tree is not based on
90 a blob in the repository.
91 The blob object ID of this entry must be considered invalid.
92 This happens when unversioned files are added with
94 and when files are added to the work tree by operations such as
101 The entry is not based on a commit in the repository.
102 The commit object ID of this entry must be considered invalid.
103 This happens when unversioned files are added with
105 and when files are added to the work tree by operations such as
112 The entry has no corresponding on-disk file in the work tree.
113 This happens when files are removed with
117 The path of the entry, relative to the work tree root.
118 Path data is of variable length and NUL-padded to a multiple of 8 bytes.
119 .It Staged blob object ID
120 The SHA1 hash of a blob object containing file content which has been
122 The hash is stored as binary data.
123 Only present if a file addition or modification has been staged with
127 A corrupt or missing file index can be recreated on demand as follows:
129 .Dl $ mv .got/file-index .got/file-index.bad
130 .Dl $ got update # re-create .got/file-index
131 .Dl $ find\ . -type f -exec touch {}\ + # update timestamp of all files
132 .Dl $ got update # sync timestamps
134 When the file index is modified, it is read into memory in its entirety,
135 modified in place, and written to a temporary file.
136 This temporary file is then moved on top of the old file index with
138 This ensures that no other processes see an inconsistent file index
139 which is in the process of being written.
141 Work tree meta data must only be modified while the work tree's
143 file has been exclusively locked with
146 Each work tree has a universal unique identifier.
147 When a work tree is checked out or updated, this identifier is used to
148 create a reference to the current base commit in the Git repository.
149 The presence of this reference prevents the Git garbage collector and
151 from discarding the base commit and any objects it refers to.
152 When a work tree is no longer needed, its reference can be deleted from
153 the Git repository with
156 .Bl -tag -width path-prefix -compact
158 Meta-data directory where all files listed below reside.
160 SHA1 hex-string representation of the current base commit.
162 File status information.
164 Work tree format number.
166 Configuration file for
171 Name of the reference to the current branch.
173 Lock file to obtain exclusive write access to meta data.
175 Path inside repository the work tree was checked out from.
177 Path to the repository the work tree was checked out from.
179 A universal unique identifier for the work tree.
187 .Xr git-repository 5 ,
