Blame


1 8797b228 2019-08-04 stsp <!DOCTYPE html>
2 8797b228 2019-08-04 stsp <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>
5 8797b228 2019-08-04 stsp
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.
9 8797b228 2019-08-04 stsp
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.
17 8797b228 2019-08-04 stsp -->
18 8797b228 2019-08-04 stsp <head>
19 8797b228 2019-08-04 stsp <meta charset="utf-8"/>
20 a954aa0a 2021-06-22 stsp <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
21 5ca479d6 2021-11-21 stsp <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
22 8797b228 2019-08-04 stsp <title>GOT-WORKTREE(5)</title>
23 8797b228 2019-08-04 stsp </head>
24 8797b228 2019-08-04 stsp <body>
25 8797b228 2019-08-04 stsp <table class="head">
26 8797b228 2019-08-04 stsp <tr>
27 8797b228 2019-08-04 stsp <td class="head-ltitle">GOT-WORKTREE(5)</td>
28 8797b228 2019-08-04 stsp <td class="head-vol">File Formats Manual</td>
29 8797b228 2019-08-04 stsp <td class="head-rtitle">GOT-WORKTREE(5)</td>
30 8797b228 2019-08-04 stsp </tr>
31 8797b228 2019-08-04 stsp </table>
32 8797b228 2019-08-04 stsp <div class="manual-text">
33 8797b228 2019-08-04 stsp <section class="Sh">
34 8797b228 2019-08-04 stsp <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
35 feee6923 2020-09-17 stsp <p class="Pp"><code class="Nm">got-worktree</code> &#x2014;
36 feee6923 2020-09-17 stsp <span class="Nd">Game of Trees work tree format</span></p>
37 8797b228 2019-08-04 stsp </section>
38 8797b228 2019-08-04 stsp <section class="Sh">
39 8797b228 2019-08-04 stsp <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
40 2dbbbc3a 2020-07-23 stsp <p class="Pp">A Got
41 2dbbbc3a 2020-07-23 stsp <a class="permalink" href="#work"><i class="Em" id="work">work tree</i></a>
42 2dbbbc3a 2020-07-23 stsp stores a file hierarchy which corresponds to a versioned snapshot stored in
43 2dbbbc3a 2020-07-23 stsp a Git repository. The work tree's meta data is stored in the
44 2dbbbc3a 2020-07-23 stsp <span class="Pa">.got</span> directory. A work tree is created with
45 2dbbbc3a 2020-07-23 stsp <code class="Cm">got checkout</code> and is required to make changes to a
46 2dbbbc3a 2020-07-23 stsp Git repository with <a class="Xr">got(1)</a>.</p>
47 2dbbbc3a 2020-07-23 stsp <p class="Pp" id="base">A work tree stores the path to its Git repository, the
48 2dbbbc3a 2020-07-23 stsp name of a reference to the branch which files were checked out from, and the
49 2dbbbc3a 2020-07-23 stsp ID of a commit on this branch known as the
50 2dbbbc3a 2020-07-23 stsp <a class="permalink" href="#base"><i class="Em">base commit</i></a>.</p>
51 2dbbbc3a 2020-07-23 stsp <p class="Pp" id="file">File meta-data is stored in a structured file called the
52 2dbbbc3a 2020-07-23 stsp <a class="permalink" href="#file"><i class="Em">file index</i></a> which
53 2dbbbc3a 2020-07-23 stsp tracks the status of file modifications, additions, and deletions, relative
54 2dbbbc3a 2020-07-23 stsp to the base commit in the repository. The file index contains a series of
55 2dbbbc3a 2020-07-23 stsp records, and each such record contains the following status information for
56 2dbbbc3a 2020-07-23 stsp a particular file:</p>
57 8797b228 2019-08-04 stsp <dl class="Bl-tag">
58 8797b228 2019-08-04 stsp <dt>Copy of filesystem meta-data</dt>
59 8797b228 2019-08-04 stsp <dd>Timestamp, file size, and file ownership information from
60 8797b228 2019-08-04 stsp <a class="Xr">stat(2)</a>. This is only used to detect file modifications
61 8797b228 2019-08-04 stsp and is never applied back to the filesystem. File permissions are not
62 8797b228 2019-08-04 stsp tracked, except for the executable bit. When versioned files are checked
63 8797b228 2019-08-04 stsp out into the work tree, the current <a class="Xr">umask(2)</a> is
64 8797b228 2019-08-04 stsp heeded.</dd>
65 8797b228 2019-08-04 stsp <dt>Blob object ID</dt>
66 8797b228 2019-08-04 stsp <dd>The SHA1 hash of the blob object which corresponds to the contents of this
67 8797b228 2019-08-04 stsp file in the repository. The hash is stored as binary data.</dd>
68 8797b228 2019-08-04 stsp <dt>Commit object ID</dt>
69 8797b228 2019-08-04 stsp <dd>The SHA1 hash of the commit object the file was checked out from. The hash
70 8797b228 2019-08-04 stsp is stored as binary data. This data is used to detect past incomplete
71 8797b228 2019-08-04 stsp update operations. Entries which do not match the work tree's base commit
72 8797b228 2019-08-04 stsp may still need to be updated to match file content stored in the base
73 8797b228 2019-08-04 stsp commit.</dd>
74 8797b228 2019-08-04 stsp <dt>Flags</dt>
75 61cf2aeb 2019-08-06 stsp <dd>This field contains the length, according to <a class="Xr">strlen(3)</a>,
76 61cf2aeb 2019-08-06 stsp of path data 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>
110 61cf2aeb 2019-08-06 stsp </dl>
111 61cf2aeb 2019-08-06 stsp </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>
120 8797b228 2019-08-04 stsp </dl>
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&#x00A0;. -type f -exec touch
129 f2e17eed 2020-11-14 stsp {}&#x00A0;+ # 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 feee6923 2020-09-17 stsp <a class="Xr">rename(2)</a>. This ensures that no other processes see an
136 feee6923 2020-09-17 stsp inconsistent file index which is in the process of being written.</p>
137 8797b228 2019-08-04 stsp <p class="Pp">Work tree meta data must only be modified while the work tree's
138 8797b228 2019-08-04 stsp <span class="Pa">lock</span> file has been exclusively locked with
139 8797b228 2019-08-04 stsp <a class="Xr">lockf(3)</a>.</p>
140 8797b228 2019-08-04 stsp <p class="Pp">Each work tree has a universal unique identifier. When a work tree
141 8797b228 2019-08-04 stsp is checked out or updated, this identifier is used to create a reference to
142 8797b228 2019-08-04 stsp the current base commit in the Git repository. The presence of this
143 16cd1323 2021-07-26 stsp reference prevents the Git garbage collector and <code class="Cm">gotadmin
144 16cd1323 2021-07-26 stsp cleanup</code> from discarding the base commit and any objects it refers to.
145 16cd1323 2021-07-26 stsp When a work tree is no longer needed its reference can be deleted from the
146 16cd1323 2021-07-26 stsp Git repository with <code class="Cm">got ref -d</code>.</p>
147 8797b228 2019-08-04 stsp </section>
148 8797b228 2019-08-04 stsp <section class="Sh">
149 8797b228 2019-08-04 stsp <h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
150 8797b228 2019-08-04 stsp <dl class="Bl-tag Bl-compact">
151 8797b228 2019-08-04 stsp <dt><span class="Pa">.got</span></dt>
152 8797b228 2019-08-04 stsp <dd>Meta-data directory where all files listed below reside.</dd>
153 8797b228 2019-08-04 stsp <dt><span class="Pa">base-commit</span></dt>
154 8797b228 2019-08-04 stsp <dd>SHA1 hex-string representation of the current base commit.</dd>
155 8797b228 2019-08-04 stsp <dt><span class="Pa">file-index</span></dt>
156 8797b228 2019-08-04 stsp <dd>File status information.</dd>
157 8797b228 2019-08-04 stsp <dt><span class="Pa">format</span></dt>
158 8797b228 2019-08-04 stsp <dd>Work tree format number.</dd>
159 feee6923 2020-09-17 stsp <dt><span class="Pa">got.conf</span></dt>
160 feee6923 2020-09-17 stsp <dd>Configuration file for <a class="Xr">got(1)</a>. See
161 feee6923 2020-09-17 stsp <a class="Xr">got.conf(5)</a>.</dd>
162 8797b228 2019-08-04 stsp <dt><span class="Pa">head-ref</span></dt>
163 8797b228 2019-08-04 stsp <dd>Name of the reference to the current branch.</dd>
164 8797b228 2019-08-04 stsp <dt><span class="Pa">lock</span></dt>
165 8797b228 2019-08-04 stsp <dd>Lock file to obtain exclusive write access to meta data.</dd>
166 8797b228 2019-08-04 stsp <dt><span class="Pa">path-prefix</span></dt>
167 8797b228 2019-08-04 stsp <dd>Path inside repository the work tree was checked out from.</dd>
168 8797b228 2019-08-04 stsp <dt><span class="Pa">repository</span></dt>
169 8797b228 2019-08-04 stsp <dd>Path to the repository the work tree was checked out from.</dd>
170 8797b228 2019-08-04 stsp <dt><span class="Pa">uuid</span></dt>
171 8797b228 2019-08-04 stsp <dd>A universal unique identifier for the work tree.</dd>
172 8797b228 2019-08-04 stsp </dl>
173 8797b228 2019-08-04 stsp </section>
174 8797b228 2019-08-04 stsp <section class="Sh">
175 8797b228 2019-08-04 stsp <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
176 8797b228 2019-08-04 stsp ALSO</a></h1>
177 d8e62599 2019-10-21 stsp <p class="Pp"><a class="Xr">got(1)</a>, <a class="Xr">rename(2)</a>,
178 d8e62599 2019-10-21 stsp <a class="Xr">stat(2)</a>, <a class="Xr">umask(2)</a>,
179 feee6923 2020-09-17 stsp <a class="Xr">lockf(3)</a>, <a class="Xr">git-repository(5)</a>,
180 feee6923 2020-09-17 stsp <a class="Xr">got.conf(5)</a></p>
181 8797b228 2019-08-04 stsp </section>
182 8797b228 2019-08-04 stsp </div>
183 8797b228 2019-08-04 stsp <table class="foot">
184 8797b228 2019-08-04 stsp <tr>
185 46043f6f 2021-11-23 stsp <td class="foot-date">November 23, 2021</td>
186 def5be4a 2021-08-31 stsp <td class="foot-os">OpenBSD 7.0</td>
187 8797b228 2019-08-04 stsp </tr>
188 8797b228 2019-08-04 stsp </table>
189 8797b228 2019-08-04 stsp </body>
190 8797b228 2019-08-04 stsp </html>