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