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 8797b228 2019-08-04 stsp <dd>The SHA1 hash of the blob object which corresponds to the contents of this
66 8797b228 2019-08-04 stsp file in the repository. The hash is stored as binary data.</dd>
67 8797b228 2019-08-04 stsp <dt>Commit object ID</dt>
68 8797b228 2019-08-04 stsp <dd>The SHA1 hash of the commit object the file was checked out from. The hash
69 8797b228 2019-08-04 stsp is stored as binary data. This data is used to detect past incomplete
70 8797b228 2019-08-04 stsp update operations. Entries which do not match the work tree's base commit
71 8797b228 2019-08-04 stsp may still need to be updated to match file content stored in the base
72 8797b228 2019-08-04 stsp commit.</dd>
73 8797b228 2019-08-04 stsp <dt>Flags</dt>
74 376d4d52 2022-07-04 stsp <dd>This field contains the length, according to
75 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="strlen, section 3">strlen(3)</a>, of path data
76 376d4d52 2022-07-04 stsp which follows, and the following flags:
77 61cf2aeb 2019-08-06 stsp <dl class="Bl-tag">
78 61cf2aeb 2019-08-06 stsp <dt>STAGE</dt>
79 61cf2aeb 2019-08-06 stsp <dd>Reflects the added, modified, or deleted staged state of a path staged
80 61cf2aeb 2019-08-06 stsp with <code class="Cm">got stage</code>.</dd>
81 61cf2aeb 2019-08-06 stsp <dt>NOT_FLUSHED</dt>
82 61cf2aeb 2019-08-06 stsp <dd>The entry was added to the file index in memory and does not exist in
83 61cf2aeb 2019-08-06 stsp file index data read from disk. This happens to files which are added
84 61cf2aeb 2019-08-06 stsp to the work tree while operations such as <code class="Cm">got
85 61cf2aeb 2019-08-06 stsp checkout</code>, <code class="Cm">got update</code>,
86 4967d3c2 2019-08-12 stsp <code class="Cm">got cherrypick</code>, <code class="Cm">got
87 4967d3c2 2019-08-12 stsp backout</code>, <code class="Cm">got rebase</code>, and
88 61cf2aeb 2019-08-06 stsp <code class="Cm">got histedit</code> are in progress. This flag is
89 61cf2aeb 2019-08-06 stsp always cleared before the entry is written to disk.</dd>
90 61cf2aeb 2019-08-06 stsp <dt>NO_BLOB</dt>
91 1ae36976 2019-08-06 stsp <dd>The entry's on-disk file content in the work tree is not based on a
92 61cf2aeb 2019-08-06 stsp blob in the repository. The blob object ID of this entry must be
93 61cf2aeb 2019-08-06 stsp considered invalid. This happens when unversioned files are added with
94 61cf2aeb 2019-08-06 stsp <code class="Cm">got add</code> and when files are added to the work
95 4967d3c2 2019-08-12 stsp tree by operations such as <code class="Cm">got cherrypick</code>,
96 4967d3c2 2019-08-12 stsp <code class="Cm">got backout</code>, <code class="Cm">got
97 4967d3c2 2019-08-12 stsp rebase</code>, and <code class="Cm">got histedit</code>.</dd>
98 61cf2aeb 2019-08-06 stsp <dt>NO_COMMIT</dt>
99 61cf2aeb 2019-08-06 stsp <dd>The entry is not based on a commit in the repository. The commit
100 61cf2aeb 2019-08-06 stsp object ID of this entry must be considered invalid. This happens when
101 61cf2aeb 2019-08-06 stsp unversioned files are added with <code class="Cm">got add</code> and
102 61cf2aeb 2019-08-06 stsp when files are added to the work tree by operations such as
103 4967d3c2 2019-08-12 stsp <code class="Cm">got cherrypick</code>, <code class="Cm">got
104 4967d3c2 2019-08-12 stsp backout</code>, <code class="Cm">got rebase</code>, and
105 61cf2aeb 2019-08-06 stsp <code class="Cm">got histedit</code>.</dd>
106 61cf2aeb 2019-08-06 stsp <dt>NO_FILE_ON_DISK</dt>
107 61cf2aeb 2019-08-06 stsp <dd>The entry has no corresponding on-disk file in the work tree. This
108 61cf2aeb 2019-08-06 stsp happens when files are removed with <code class="Cm">got
109 61cf2aeb 2019-08-06 stsp remove</code>.</dd>
112 8797b228 2019-08-04 stsp <dt>Path data</dt>
113 8797b228 2019-08-04 stsp <dd>The path of the entry, relative to the work tree root. Path data is of
114 8797b228 2019-08-04 stsp variable length and NUL-padded to a multiple of 8 bytes.</dd>
115 61cf2aeb 2019-08-06 stsp <dt>Staged blob object ID</dt>
116 61cf2aeb 2019-08-06 stsp <dd>The SHA1 hash of a blob object containing file content which has been
117 61cf2aeb 2019-08-06 stsp staged for commit. The hash is stored as binary data. Only present if a
118 61cf2aeb 2019-08-06 stsp file addition or modification has been staged with <code class="Cm">got
119 61cf2aeb 2019-08-06 stsp stage</code>.</dd>
121 feee6923 2020-09-17 stsp <p class="Pp">A corrupt or missing file index can be recreated on demand as
122 feee6923 2020-09-17 stsp follows:</p>
123 feee6923 2020-09-17 stsp <p class="Pp"></p>
124 feee6923 2020-09-17 stsp <div class="Bd Bd-indent"><code class="Li">$ mv .got/file-index
125 feee6923 2020-09-17 stsp .got/file-index.bad</code></div>
126 feee6923 2020-09-17 stsp <div class="Bd Bd-indent"><code class="Li">$ got update # re-create
127 feee6923 2020-09-17 stsp .got/file-index</code></div>
128 feee6923 2020-09-17 stsp <div class="Bd Bd-indent"><code class="Li">$ find . -type f -exec touch
129 f2e17eed 2020-11-14 stsp {} + # update timestamp of all files</code></div>
130 feee6923 2020-09-17 stsp <div class="Bd Bd-indent"><code class="Li">$ got update # sync
131 feee6923 2020-09-17 stsp timestamps</code></div>
132 feee6923 2020-09-17 stsp <p class="Pp">When the file index is modified, it is read into memory in its
133 feee6923 2020-09-17 stsp entirety, modified in place, and written to a temporary file. This temporary
134 feee6923 2020-09-17 stsp file is then moved on top of the old file index with
135 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="rename, section 2">rename(2)</a>. This ensures
136 376d4d52 2022-07-04 stsp that no other processes see an inconsistent file index which is in the
137 376d4d52 2022-07-04 stsp process of being written.</p>
138 8797b228 2019-08-04 stsp <p class="Pp">Work tree meta data must only be modified while the work tree's
139 8797b228 2019-08-04 stsp <span class="Pa">lock</span> file has been exclusively locked with
140 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="lockf, section 3">lockf(3)</a>.</p>
141 8797b228 2019-08-04 stsp <p class="Pp">Each work tree has a universal unique identifier. When a work tree
142 8797b228 2019-08-04 stsp is checked out or updated, this identifier is used to create a reference to
143 8797b228 2019-08-04 stsp the current base commit in the Git repository. The presence of this
144 16cd1323 2021-07-26 stsp reference prevents the Git garbage collector and <code class="Cm">gotadmin
145 16cd1323 2021-07-26 stsp cleanup</code> from discarding the base commit and any objects it refers to.
146 b078d5c4 2022-03-23 stsp When a work tree is no longer needed, its reference can be deleted from the
147 16cd1323 2021-07-26 stsp Git repository with <code class="Cm">got ref -d</code>.</p>
149 8797b228 2019-08-04 stsp <section class="Sh">
150 63657f42 2022-09-07 stsp <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
151 8797b228 2019-08-04 stsp <dl class="Bl-tag Bl-compact">
152 8797b228 2019-08-04 stsp <dt><span class="Pa">.got</span></dt>
153 8797b228 2019-08-04 stsp <dd>Meta-data directory where all files listed below reside.</dd>
154 8797b228 2019-08-04 stsp <dt><span class="Pa">base-commit</span></dt>
155 8797b228 2019-08-04 stsp <dd>SHA1 hex-string representation of the current base commit.</dd>
156 8797b228 2019-08-04 stsp <dt><span class="Pa">file-index</span></dt>
157 8797b228 2019-08-04 stsp <dd>File status information.</dd>
158 8797b228 2019-08-04 stsp <dt><span class="Pa">format</span></dt>
159 8797b228 2019-08-04 stsp <dd>Work tree format number.</dd>
160 feee6923 2020-09-17 stsp <dt><span class="Pa">got.conf</span></dt>
161 376d4d52 2022-07-04 stsp <dd>Configuration file for <a class="Xr" aria-label="got, section
162 376d4d52 2022-07-04 stsp 1">got(1)</a>. See <a class="Xr" aria-label="got.conf, section
163 376d4d52 2022-07-04 stsp 5">got.conf(5)</a>.</dd>
164 8797b228 2019-08-04 stsp <dt><span class="Pa">head-ref</span></dt>
165 8797b228 2019-08-04 stsp <dd>Name of the reference to the current branch.</dd>
166 8797b228 2019-08-04 stsp <dt><span class="Pa">lock</span></dt>
167 8797b228 2019-08-04 stsp <dd>Lock file to obtain exclusive write access to meta data.</dd>
168 8797b228 2019-08-04 stsp <dt><span class="Pa">path-prefix</span></dt>
169 8797b228 2019-08-04 stsp <dd>Path inside repository the work tree was checked out from.</dd>
170 8797b228 2019-08-04 stsp <dt><span class="Pa">repository</span></dt>
171 8797b228 2019-08-04 stsp <dd>Path to the repository the work tree was checked out from.</dd>
172 8797b228 2019-08-04 stsp <dt><span class="Pa">uuid</span></dt>
173 8797b228 2019-08-04 stsp <dd>A universal unique identifier for the work tree.</dd>
176 8797b228 2019-08-04 stsp <section class="Sh">
177 63657f42 2022-09-07 stsp <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
178 63657f42 2022-09-07 stsp ALSO</a></h2>
179 376d4d52 2022-07-04 stsp <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
180 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="rename, section 2">rename(2)</a>,
181 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="stat, section 2">stat(2)</a>,
182 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="umask, section 2">umask(2)</a>,
183 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="lockf, section 3">lockf(3)</a>,
184 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
185 376d4d52 2022-07-04 stsp <a class="Xr" aria-label="got.conf, section 5">got.conf(5)</a></p>
188 63657f42 2022-09-07 stsp <div class="foot" role="doc-pagefooter" aria-label="Manual footer
189 2b1d45b9 2024-03-11 stsp line"><span class="foot-left"></span><span class="foot-date">March 11,
190 2b1d45b9 2024-03-11 stsp 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
