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 84258ea0 2019-03-26 stsp .Nd got worktree 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 84258ea0 2019-03-26 stsp and 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 84258ea0 2019-03-26 stsp A flags field (intentionally not documented).
68 84258ea0 2019-03-26 stsp .It Path data
69 84258ea0 2019-03-26 stsp The path of the entry, relative to the work tree root.
70 84258ea0 2019-03-26 stsp Path data is of variable length and NUL-padded to a multiple of 8 bytes.
73 84258ea0 2019-03-26 stsp A corrupt or missing file index can be recreated on demand with
74 84258ea0 2019-03-26 stsp .Cm got update .
75 84258ea0 2019-03-26 stsp When the file index is modified, it is read into memory in its entirety,
76 84258ea0 2019-03-26 stsp modified in place, and written to a temporary file.
77 84258ea0 2019-03-26 stsp This temporary file is then moved on top of the old file index with
78 84258ea0 2019-03-26 stsp .Xr rename 2 .
79 84258ea0 2019-03-26 stsp This ensures that no other processes see an inconsistent file index
80 84258ea0 2019-03-26 stsp which is in the process of being written.
82 84258ea0 2019-03-26 stsp Work tree meta data must only be modified while the work tree's
84 84258ea0 2019-03-26 stsp file has been exclusively locked with
85 84258ea0 2019-03-26 stsp .Xr lockf 3 .
87 84258ea0 2019-03-26 stsp Each work tree has a universal unique identifier.
88 84258ea0 2019-03-26 stsp When a work tree is checked out or updated, this identifier is used to
89 84258ea0 2019-03-26 stsp create a reference to the current base commit in the Git repository.
90 84258ea0 2019-03-26 stsp The presence of this reference prevents Git garbage collectors from
91 84258ea0 2019-03-26 stsp discarding the base commit and any objects it refers to.
92 84258ea0 2019-03-26 stsp When a work tree is no longer needed its reference can be deleted from
93 84258ea0 2019-03-26 stsp the Git repository with
94 84258ea0 2019-03-26 stsp .Cm got ref -d .
96 84258ea0 2019-03-26 stsp .Bl -tag -width path-prefix -compact
98 84258ea0 2019-03-26 stsp Meta-data directory where all files listed below reside.
99 84258ea0 2019-03-26 stsp .It Pa base-commit
100 84258ea0 2019-03-26 stsp SHA1 hex-string representation of the current base commit.
101 84258ea0 2019-03-26 stsp .It Pa file-index
102 84258ea0 2019-03-26 stsp File status information.
103 84258ea0 2019-03-26 stsp .It Pa format
104 84258ea0 2019-03-26 stsp Work tree format number.
105 84258ea0 2019-03-26 stsp .It Pa head-ref
106 84258ea0 2019-03-26 stsp Name of the reference to the current branch.
107 84258ea0 2019-03-26 stsp .It Pa lock
108 84258ea0 2019-03-26 stsp Lock file to obtain exclusive write access to meta data.
109 84258ea0 2019-03-26 stsp .It Pa path-prefix
110 84258ea0 2019-03-26 stsp Path inside repository the work tree was checked out from.
111 84258ea0 2019-03-26 stsp .It Pa repository
112 84258ea0 2019-03-26 stsp Path to the repository the work tree was checked out from.
113 84258ea0 2019-03-26 stsp .It Pa uuid
114 fdcf78bb 2019-03-26 stsp A universal unique identifier for the work tree.
116 84258ea0 2019-03-26 stsp .Sh SEE ALSO
117 84258ea0 2019-03-26 stsp .Xr got 1 ,
118 84258ea0 2019-03-26 stsp .Xr rename 2 ,
119 84258ea0 2019-03-26 stsp .Xr stat 2 ,
120 84258ea0 2019-03-26 stsp .Xr umask 2 ,
121 84258ea0 2019-03-26 stsp .Xr lockf 3 ,
122 84258ea0 2019-03-26 stsp .Xr git-repository 5
