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