1 8797b228 2019-08-04 stsp <!DOCTYPE html>
4 63657f42 2022-09-07 stsp <meta charset="utf-8"/>
5 63657f42 2022-09-07 stsp <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
6 63657f42 2022-09-07 stsp <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
7 63657f42 2022-09-07 stsp <title>GOT-WORKTREE(5)</title>
9 8797b228 2019-08-04 stsp <!-- This is an automatically generated file. Do not edit.
10 8797b228 2019-08-04 stsp Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
12 8797b228 2019-08-04 stsp Permission to use, copy, modify, and distribute this software for any
13 8797b228 2019-08-04 stsp purpose with or without fee is hereby granted, provided that the above
14 8797b228 2019-08-04 stsp copyright notice and this permission notice appear in all copies.
16 8797b228 2019-08-04 stsp THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 8797b228 2019-08-04 stsp WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 8797b228 2019-08-04 stsp MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 8797b228 2019-08-04 stsp ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 8797b228 2019-08-04 stsp WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 8797b228 2019-08-04 stsp ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 8797b228 2019-08-04 stsp OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 63657f42 2022-09-07 stsp <div class="head" role="doc-pageheader" aria-label="Manual header
26 63657f42 2022-09-07 stsp line"><span class="head-ltitle">GOT-WORKTREE(5)</span>
27 63657f42 2022-09-07 stsp <span class="head-vol">File Formats Manual</span>
28 63657f42 2022-09-07 stsp <span class="head-rtitle">GOT-WORKTREE(5)</span></div>
29 63657f42 2022-09-07 stsp <main class="manual-text">
30 8797b228 2019-08-04 stsp <section class="Sh">
31 63657f42 2022-09-07 stsp <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 feee6923 2020-09-17 stsp <p class="Pp"><code class="Nm">got-worktree</code> —
33 63657f42 2022-09-07 stsp <span class="Nd" role="doc-subtitle">Game of Trees work tree
34 63657f42 2022-09-07 stsp format</span></p>
36 8797b228 2019-08-04 stsp <section class="Sh">
37 63657f42 2022-09-07 stsp <h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
38 2dbbbc3a 2020-07-23 stsp <p class="Pp">A Got
39 2dbbbc3a 2020-07-23 stsp <a class="permalink" href="#work"><i class="Em" id="work">work tree</i></a>
40 2dbbbc3a 2020-07-23 stsp stores a file hierarchy which corresponds to a versioned snapshot stored in
41 2dbbbc3a 2020-07-23 stsp a Git repository. The work tree's meta data is stored in the
42 2dbbbc3a 2020-07-23 stsp <span class="Pa">.got</span> directory. A work tree is created with
43 2dbbbc3a 2020-07-23 stsp <code class="Cm">got checkout</code> and is required to make changes to a
44 376d4d52 2022-07-04 stsp Git repository with <a class="Xr" aria-label="got, section
45 376d4d52 2022-07-04 stsp 1">got(1)</a>.</p>
46 2dbbbc3a 2020-07-23 stsp <p class="Pp" id="base">A work tree stores the path to its Git repository, the
47 2dbbbc3a 2020-07-23 stsp name of a reference to the branch which files were checked out from, and the
48 2dbbbc3a 2020-07-23 stsp ID of a commit on this branch known as the
49 2dbbbc3a 2020-07-23 stsp <a class="permalink" href="#base"><i class="Em">base commit</i></a>.</p>
50 2dbbbc3a 2020-07-23 stsp <p class="Pp" id="file">File meta-data is stored in a structured file called the
51 2dbbbc3a 2020-07-23 stsp <a class="permalink" href="#file"><i class="Em">file index</i></a> which
52 2dbbbc3a 2020-07-23 stsp tracks the status of file modifications, additions, and deletions, relative
53 2dbbbc3a 2020-07-23 stsp to the base commit in the repository. The file index contains a series of
54 2dbbbc3a 2020-07-23 stsp records, and each such record contains the following status information for
55 2dbbbc3a 2020-07-23 stsp a particular file:</p>
56 8797b228 2019-08-04 stsp <dl class="Bl-tag">
57 8797b228 2019-08-04 stsp <dt>Copy of filesystem meta-data</dt>
58 8797b228 2019-08-04 stsp <dd>Timestamp, file size, and file ownership information from
59 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="stat, section 2">stat(2)</a>. This is only used
60 376d4d52 2022-07-04 stsp to detect file modifications and is never applied back to the filesystem.
61 376d4d52 2022-07-04 stsp File permissions are not tracked, except for the executable bit. When
62 376d4d52 2022-07-04 stsp versioned files are checked out into the work tree, the current
63 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="umask, section 2">umask(2)</a> is heeded.</dd>
64 8797b228 2019-08-04 stsp <dt>Blob object ID</dt>
65 b183145b 2024-08-14 op <dd>The hash of the blob object which corresponds to the contents of this file
66 b183145b 2024-08-14 op in the repository. The hash is stored as binary data. The size of the hash
67 b183145b 2024-08-14 op depends on the hashing algorithm used in the repository.</dd>
68 8797b228 2019-08-04 stsp <dt>Commit object ID</dt>
69 b183145b 2024-08-14 op <dd>The hash of the commit object the file was checked out from. The hash is
70 b183145b 2024-08-14 op stored as binary data. This data is used to detect past incomplete update
71 b183145b 2024-08-14 op operations. Entries which do not match the work tree's base commit may
72 b183145b 2024-08-14 op still need to be updated to match file content stored in the base
74 8797b228 2019-08-04 stsp <dt>Flags</dt>
75 376d4d52 2022-07-04 stsp <dd>This field contains the length, according to
76 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="strlen, section 3">strlen(3)</a>, of path data
77 376d4d52 2022-07-04 stsp which follows, and the following flags:
78 61cf2aeb 2019-08-06 stsp <dl class="Bl-tag">
79 61cf2aeb 2019-08-06 stsp <dt>STAGE</dt>
80 61cf2aeb 2019-08-06 stsp <dd>Reflects the added, modified, or deleted staged state of a path staged
81 61cf2aeb 2019-08-06 stsp with <code class="Cm">got stage</code>.</dd>
82 61cf2aeb 2019-08-06 stsp <dt>NOT_FLUSHED</dt>
83 61cf2aeb 2019-08-06 stsp <dd>The entry was added to the file index in memory and does not exist in
84 61cf2aeb 2019-08-06 stsp file index data read from disk. This happens to files which are added
85 61cf2aeb 2019-08-06 stsp to the work tree while operations such as <code class="Cm">got
86 61cf2aeb 2019-08-06 stsp checkout</code>, <code class="Cm">got update</code>,
87 4967d3c2 2019-08-12 stsp <code class="Cm">got cherrypick</code>, <code class="Cm">got
88 4967d3c2 2019-08-12 stsp backout</code>, <code class="Cm">got rebase</code>, and
89 61cf2aeb 2019-08-06 stsp <code class="Cm">got histedit</code> are in progress. This flag is
90 61cf2aeb 2019-08-06 stsp always cleared before the entry is written to disk.</dd>
91 61cf2aeb 2019-08-06 stsp <dt>NO_BLOB</dt>
92 1ae36976 2019-08-06 stsp <dd>The entry's on-disk file content in the work tree is not based on a
93 61cf2aeb 2019-08-06 stsp blob in the repository. The blob object ID of this entry must be
94 61cf2aeb 2019-08-06 stsp considered invalid. This happens when unversioned files are added with
95 61cf2aeb 2019-08-06 stsp <code class="Cm">got add</code> and when files are added to the work
96 4967d3c2 2019-08-12 stsp tree by operations such as <code class="Cm">got cherrypick</code>,
97 4967d3c2 2019-08-12 stsp <code class="Cm">got backout</code>, <code class="Cm">got
98 4967d3c2 2019-08-12 stsp rebase</code>, and <code class="Cm">got histedit</code>.</dd>
99 61cf2aeb 2019-08-06 stsp <dt>NO_COMMIT</dt>
100 61cf2aeb 2019-08-06 stsp <dd>The entry is not based on a commit in the repository. The commit
101 61cf2aeb 2019-08-06 stsp object ID of this entry must be considered invalid. This happens when
102 61cf2aeb 2019-08-06 stsp unversioned files are added with <code class="Cm">got add</code> and
103 61cf2aeb 2019-08-06 stsp when files are added to the work tree by operations such as
104 4967d3c2 2019-08-12 stsp <code class="Cm">got cherrypick</code>, <code class="Cm">got
105 4967d3c2 2019-08-12 stsp backout</code>, <code class="Cm">got rebase</code>, and
106 61cf2aeb 2019-08-06 stsp <code class="Cm">got histedit</code>.</dd>
107 61cf2aeb 2019-08-06 stsp <dt>NO_FILE_ON_DISK</dt>
108 61cf2aeb 2019-08-06 stsp <dd>The entry has no corresponding on-disk file in the work tree. This
109 61cf2aeb 2019-08-06 stsp happens when files are removed with <code class="Cm">got
110 61cf2aeb 2019-08-06 stsp remove</code>.</dd>
113 8797b228 2019-08-04 stsp <dt>Path data</dt>
114 8797b228 2019-08-04 stsp <dd>The path of the entry, relative to the work tree root. Path data is of
115 8797b228 2019-08-04 stsp variable length and NUL-padded to a multiple of 8 bytes.</dd>
116 61cf2aeb 2019-08-06 stsp <dt>Staged blob object ID</dt>
117 b183145b 2024-08-14 op <dd>The hash of a blob object containing file content which has been staged
118 b183145b 2024-08-14 op for commit. The hash is stored as binary data. Only present if a file
119 b183145b 2024-08-14 op addition or modification has been staged with <code class="Cm">got
120 61cf2aeb 2019-08-06 stsp stage</code>.</dd>
122 feee6923 2020-09-17 stsp <p class="Pp">A corrupt or missing file index can be recreated on demand as
123 feee6923 2020-09-17 stsp follows:</p>
124 feee6923 2020-09-17 stsp <p class="Pp"></p>
125 feee6923 2020-09-17 stsp <div class="Bd Bd-indent"><code class="Li">$ mv .got/file-index
126 feee6923 2020-09-17 stsp .got/file-index.bad</code></div>
127 feee6923 2020-09-17 stsp <div class="Bd Bd-indent"><code class="Li">$ got update # re-create
128 feee6923 2020-09-17 stsp .got/file-index</code></div>
129 feee6923 2020-09-17 stsp <div class="Bd Bd-indent"><code class="Li">$ find . -type f -exec touch
130 f2e17eed 2020-11-14 stsp {} + # update timestamp of all files</code></div>
131 feee6923 2020-09-17 stsp <div class="Bd Bd-indent"><code class="Li">$ got update # sync
132 feee6923 2020-09-17 stsp timestamps</code></div>
133 feee6923 2020-09-17 stsp <p class="Pp">When the file index is modified, it is read into memory in its
134 feee6923 2020-09-17 stsp entirety, modified in place, and written to a temporary file. This temporary
135 feee6923 2020-09-17 stsp file is then moved on top of the old file index with
136 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="rename, section 2">rename(2)</a>. This ensures
137 376d4d52 2022-07-04 stsp that no other processes see an inconsistent file index which is in the
138 376d4d52 2022-07-04 stsp process of being written.</p>
139 8797b228 2019-08-04 stsp <p class="Pp">Work tree meta data must only be modified while the work tree's
140 8797b228 2019-08-04 stsp <span class="Pa">lock</span> file has been exclusively locked with
141 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="lockf, section 3">lockf(3)</a>.</p>
142 8797b228 2019-08-04 stsp <p class="Pp">Each work tree has a universal unique identifier. When a work tree
143 8797b228 2019-08-04 stsp is checked out or updated, this identifier is used to create a reference to
144 8797b228 2019-08-04 stsp the current base commit in the Git repository. The presence of this
145 16cd1323 2021-07-26 stsp reference prevents the Git garbage collector and <code class="Cm">gotadmin
146 16cd1323 2021-07-26 stsp cleanup</code> from discarding the base commit and any objects it refers to.
147 b078d5c4 2022-03-23 stsp When a work tree is no longer needed, its reference can be deleted from the
148 16cd1323 2021-07-26 stsp Git repository with <code class="Cm">got ref -d</code>.</p>
150 8797b228 2019-08-04 stsp <section class="Sh">
151 63657f42 2022-09-07 stsp <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
152 8797b228 2019-08-04 stsp <dl class="Bl-tag Bl-compact">
153 8797b228 2019-08-04 stsp <dt><span class="Pa">.got</span></dt>
154 8797b228 2019-08-04 stsp <dd>Meta-data directory where all files listed below reside.</dd>
155 8797b228 2019-08-04 stsp <dt><span class="Pa">base-commit</span></dt>
156 b183145b 2024-08-14 op <dd>hash digest hex-string representation of the current base commit.</dd>
157 8797b228 2019-08-04 stsp <dt><span class="Pa">file-index</span></dt>
158 8797b228 2019-08-04 stsp <dd>File status information.</dd>
159 8797b228 2019-08-04 stsp <dt><span class="Pa">format</span></dt>
160 8797b228 2019-08-04 stsp <dd>Work tree format number.</dd>
161 feee6923 2020-09-17 stsp <dt><span class="Pa">got.conf</span></dt>
162 376d4d52 2022-07-04 stsp <dd>Configuration file for <a class="Xr" aria-label="got, section
163 376d4d52 2022-07-04 stsp 1">got(1)</a>. See <a class="Xr" aria-label="got.conf, section
164 376d4d52 2022-07-04 stsp 5">got.conf(5)</a>.</dd>
165 8797b228 2019-08-04 stsp <dt><span class="Pa">head-ref</span></dt>
166 8797b228 2019-08-04 stsp <dd>Name of the reference to the current branch.</dd>
167 8797b228 2019-08-04 stsp <dt><span class="Pa">lock</span></dt>
168 8797b228 2019-08-04 stsp <dd>Lock file to obtain exclusive write access to meta data.</dd>
169 8797b228 2019-08-04 stsp <dt><span class="Pa">path-prefix</span></dt>
170 8797b228 2019-08-04 stsp <dd>Path inside repository the work tree was checked out from.</dd>
171 8797b228 2019-08-04 stsp <dt><span class="Pa">repository</span></dt>
172 8797b228 2019-08-04 stsp <dd>Path to the repository the work tree was checked out from.</dd>
173 8797b228 2019-08-04 stsp <dt><span class="Pa">uuid</span></dt>
174 8797b228 2019-08-04 stsp <dd>A universal unique identifier for the work tree.</dd>
177 8797b228 2019-08-04 stsp <section class="Sh">
178 63657f42 2022-09-07 stsp <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
179 63657f42 2022-09-07 stsp ALSO</a></h2>
180 376d4d52 2022-07-04 stsp <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
181 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="rename, section 2">rename(2)</a>,
182 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="stat, section 2">stat(2)</a>,
183 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="umask, section 2">umask(2)</a>,
184 b183145b 2024-08-14 op <a class="Xr" aria-label="flock, section 3">flock(3)</a>,
185 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
186 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="got.conf, section 5">got.conf(5)</a></p>
189 63657f42 2022-09-07 stsp <div class="foot" role="doc-pagefooter" aria-label="Manual footer
190 b6df88e2 2024-12-28 stsp line"><span class="foot-left"></span><span class="foot-date">December 28,
191 a3016eec 2024-10-22 op 2024</span> <span class="foot-os">OpenBSD 7.6</span></div>
