2 84258ea0 2019-03-26 stsp .\" Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
4 84258ea0 2019-03-26 stsp .\" Permission to use, copy, modify, and distribute this software for any
5 84258ea0 2019-03-26 stsp .\" purpose with or without fee is hereby granted, provided that the above
6 84258ea0 2019-03-26 stsp .\" copyright notice and this permission notice appear in all copies.
8 84258ea0 2019-03-26 stsp .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 84258ea0 2019-03-26 stsp .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 84258ea0 2019-03-26 stsp .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 84258ea0 2019-03-26 stsp .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 84258ea0 2019-03-26 stsp .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 84258ea0 2019-03-26 stsp .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 84258ea0 2019-03-26 stsp .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 84258ea0 2019-03-26 stsp .Dd $Mdocdate$
17 84258ea0 2019-03-26 stsp .Dt GOT-WORKTREE 5
20 84258ea0 2019-03-26 stsp .Nm got-worktree
21 72862ecf 2020-09-16 stsp .Nd Game of Trees work tree format
22 84258ea0 2019-03-26 stsp .Sh DESCRIPTION
24 84258ea0 2019-03-26 stsp .Em work tree
25 84258ea0 2019-03-26 stsp stores a file hierarchy which corresponds to a versioned
26 84258ea0 2019-03-26 stsp snapshot stored in a Git repository.
27 84258ea0 2019-03-26 stsp The work tree's meta data is stored in the
30 84258ea0 2019-03-26 stsp A work tree is created with
31 84258ea0 2019-03-26 stsp .Cm got checkout
32 84258ea0 2019-03-26 stsp and is required to make changes to a Git repository with
35 84258ea0 2019-03-26 stsp A work tree stores the path to its Git repository, the name of a reference
36 84258ea0 2019-03-26 stsp to the branch which files were checked out from, and the ID of a commit on
37 84258ea0 2019-03-26 stsp this branch known as the
38 84258ea0 2019-03-26 stsp .Em base commit .
40 84258ea0 2019-03-26 stsp File meta-data is stored in a structured file called the
41 84258ea0 2019-03-26 stsp .Em file index
42 24f4521a 2019-08-06 stsp which tracks the status of file modifications, additions, and deletions,
43 84258ea0 2019-03-26 stsp relative to the base commit in the repository.
44 84258ea0 2019-03-26 stsp The file index contains a series of records, and each such record contains
45 84258ea0 2019-03-26 stsp the following status information for a particular file:
46 84258ea0 2019-03-26 stsp .Bl -tag -width Ds
47 84258ea0 2019-03-26 stsp .It Copy of filesystem meta-data
48 84258ea0 2019-03-26 stsp Timestamp, file size, and file ownership information from
49 84258ea0 2019-03-26 stsp .Xr stat 2 .
50 84258ea0 2019-03-26 stsp This is only used to detect file modifications and is never applied
51 84258ea0 2019-03-26 stsp back to the filesystem.
52 84258ea0 2019-03-26 stsp File permissions are not tracked, except for the executable bit.
53 84258ea0 2019-03-26 stsp When versioned files are checked out into the work tree, the current
56 84258ea0 2019-03-26 stsp .It Blob object ID
57 84258ea0 2019-03-26 stsp The SHA1 hash of the blob object which corresponds to the contents
58 84258ea0 2019-03-26 stsp of this file in the repository.
59 84258ea0 2019-03-26 stsp The hash is stored as binary data.
60 84258ea0 2019-03-26 stsp .It Commit object ID
61 84258ea0 2019-03-26 stsp The SHA1 hash of the commit object the file was checked out from.
62 84258ea0 2019-03-26 stsp The hash is stored as binary data.
63 84258ea0 2019-03-26 stsp This data is used to detect past incomplete update operations.
64 84258ea0 2019-03-26 stsp Entries which do not match the work tree's base commit may still need
65 84258ea0 2019-03-26 stsp to be updated to match file content stored in the base commit.
67 7fc00dff 2019-08-06 stsp This field contains the length, according to
68 7fc00dff 2019-08-06 stsp .Xr strlen 3 ,
69 7fc00dff 2019-08-06 stsp of path data which follows, and the following flags:
70 7fc00dff 2019-08-06 stsp .Bl -tag -width Ds
72 7fc00dff 2019-08-06 stsp Reflects the added, modified, or deleted staged state of a path staged with
73 7fc00dff 2019-08-06 stsp .Cm got stage .
74 7fc00dff 2019-08-06 stsp .It NOT_FLUSHED
75 7fc00dff 2019-08-06 stsp The entry was added to the file index in memory and does not exist in file
76 7fc00dff 2019-08-06 stsp index data read from disk.
77 7fc00dff 2019-08-06 stsp This happens to files which are added to the work tree while operations
79 7fc00dff 2019-08-06 stsp .Cm got checkout ,
80 7fc00dff 2019-08-06 stsp .Cm got update ,
81 1dd86744 2019-08-12 anthony .Cm got cherrypick ,
82 1dd86744 2019-08-12 anthony .Cm got backout ,
83 1dd86744 2019-08-12 anthony .Cm got rebase ,
85 7fc00dff 2019-08-06 stsp .Cm got histedit
86 7fc00dff 2019-08-06 stsp are in progress.
87 7fc00dff 2019-08-06 stsp This flag is always cleared before the entry is written to disk.
89 495342e6 2019-08-06 stsp The entry's on-disk file content in the work tree is not based on
90 7fc00dff 2019-08-06 stsp a blob in the repository.
91 7fc00dff 2019-08-06 stsp The blob object ID of this entry must be considered invalid.
92 7fc00dff 2019-08-06 stsp This happens when unversioned files are added with
94 7fc00dff 2019-08-06 stsp and when files are added to the work tree by operations such as
95 1dd86744 2019-08-12 anthony .Cm got cherrypick ,
96 1dd86744 2019-08-12 anthony .Cm got backout ,
97 1dd86744 2019-08-12 anthony .Cm got rebase ,
99 7fc00dff 2019-08-06 stsp .Cm got histedit .
100 7fc00dff 2019-08-06 stsp .It NO_COMMIT
101 7fc00dff 2019-08-06 stsp The entry is not based on a commit in the repository.
102 7fc00dff 2019-08-06 stsp The commit object ID of this entry must be considered invalid.
103 7fc00dff 2019-08-06 stsp This happens when unversioned files are added with
104 7fc00dff 2019-08-06 stsp .Cm got add
105 7fc00dff 2019-08-06 stsp and when files are added to the work tree by operations such as
106 1dd86744 2019-08-12 anthony .Cm got cherrypick ,
107 1dd86744 2019-08-12 anthony .Cm got backout ,
108 1dd86744 2019-08-12 anthony .Cm got rebase ,
110 7fc00dff 2019-08-06 stsp .Cm got histedit .
111 7fc00dff 2019-08-06 stsp .It NO_FILE_ON_DISK
112 7fc00dff 2019-08-06 stsp The entry has no corresponding on-disk file in the work tree.
113 7fc00dff 2019-08-06 stsp This happens when files are removed with
114 7fc00dff 2019-08-06 stsp .Cm got remove .
116 84258ea0 2019-03-26 stsp .It Path data
117 84258ea0 2019-03-26 stsp The path of the entry, relative to the work tree root.
118 84258ea0 2019-03-26 stsp Path data is of variable length and NUL-padded to a multiple of 8 bytes.
119 28c99501 2019-08-06 stsp .It Staged blob object ID
120 28c99501 2019-08-06 stsp The SHA1 hash of a blob object containing file content which has been
121 28c99501 2019-08-06 stsp staged for commit.
122 28c99501 2019-08-06 stsp The hash is stored as binary data.
123 7fc00dff 2019-08-06 stsp Only present if a file addition or modification has been staged with
124 28c99501 2019-08-06 stsp .Cm got stage .
127 d93542d4 2020-08-08 stsp A corrupt or missing file index can be recreated on demand as follows:
129 d93542d4 2020-08-08 stsp .Dl $ mv .got/file-index .got/file-index.bad
130 d93542d4 2020-08-08 stsp .Dl $ got update # re-create .got/file-index
131 016859fc 2020-10-02 naddy .Dl $ find\ . -type f -exec touch {}\ + # update timestamp of all files
132 d93542d4 2020-08-08 stsp .Dl $ got update # sync timestamps
134 84258ea0 2019-03-26 stsp When the file index is modified, it is read into memory in its entirety,
135 84258ea0 2019-03-26 stsp modified in place, and written to a temporary file.
136 84258ea0 2019-03-26 stsp This temporary file is then moved on top of the old file index with
137 84258ea0 2019-03-26 stsp .Xr rename 2 .
138 84258ea0 2019-03-26 stsp This ensures that no other processes see an inconsistent file index
139 84258ea0 2019-03-26 stsp which is in the process of being written.
141 84258ea0 2019-03-26 stsp Work tree meta data must only be modified while the work tree's
143 84258ea0 2019-03-26 stsp file has been exclusively locked with
144 84258ea0 2019-03-26 stsp .Xr lockf 3 .
146 84258ea0 2019-03-26 stsp Each work tree has a universal unique identifier.
147 84258ea0 2019-03-26 stsp When a work tree is checked out or updated, this identifier is used to
148 84258ea0 2019-03-26 stsp create a reference to the current base commit in the Git repository.
149 e6786710 2021-07-03 stsp The presence of this reference prevents the Git garbage collector and
150 e6786710 2021-07-03 stsp .Cm gotadmin cleanup
151 e6786710 2021-07-03 stsp from discarding the base commit and any objects it refers to.
152 e38d4cde 2022-03-21 naddy When a work tree is no longer needed, its reference can be deleted from
153 84258ea0 2019-03-26 stsp the Git repository with
154 84258ea0 2019-03-26 stsp .Cm got ref -d .
156 84258ea0 2019-03-26 stsp .Bl -tag -width path-prefix -compact
157 84258ea0 2019-03-26 stsp .It Pa .got
158 84258ea0 2019-03-26 stsp Meta-data directory where all files listed below reside.
159 84258ea0 2019-03-26 stsp .It Pa base-commit
160 84258ea0 2019-03-26 stsp SHA1 hex-string representation of the current base commit.
161 84258ea0 2019-03-26 stsp .It Pa file-index
162 84258ea0 2019-03-26 stsp File status information.
163 84258ea0 2019-03-26 stsp .It Pa format
164 84258ea0 2019-03-26 stsp Work tree format number.
165 50b0790e 2020-09-11 stsp .It Pa got.conf
166 50b0790e 2020-09-11 stsp Configuration file for
167 50b0790e 2020-09-11 stsp .Xr got 1 .
169 50b0790e 2020-09-11 stsp .Xr got.conf 5 .
170 84258ea0 2019-03-26 stsp .It Pa head-ref
171 84258ea0 2019-03-26 stsp Name of the reference to the current branch.
172 84258ea0 2019-03-26 stsp .It Pa lock
173 84258ea0 2019-03-26 stsp Lock file to obtain exclusive write access to meta data.
174 84258ea0 2019-03-26 stsp .It Pa path-prefix
175 84258ea0 2019-03-26 stsp Path inside repository the work tree was checked out from.
176 84258ea0 2019-03-26 stsp .It Pa repository
177 84258ea0 2019-03-26 stsp Path to the repository the work tree was checked out from.
178 84258ea0 2019-03-26 stsp .It Pa uuid
179 fdcf78bb 2019-03-26 stsp A universal unique identifier for the work tree.
181 84258ea0 2019-03-26 stsp .Sh SEE ALSO
182 84258ea0 2019-03-26 stsp .Xr got 1 ,
183 84258ea0 2019-03-26 stsp .Xr rename 2 ,
184 84258ea0 2019-03-26 stsp .Xr stat 2 ,
185 84258ea0 2019-03-26 stsp .Xr umask 2 ,
186 84258ea0 2019-03-26 stsp .Xr lockf 3 ,
187 50b0790e 2020-09-11 stsp .Xr git-repository 5 ,
188 50b0790e 2020-09-11 stsp .Xr got.conf 5
