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