Blob


1 <!DOCTYPE html>
2 <html>
3 <!-- This is an automatically generated file. Do not edit.
4 Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
6 Permission to use, copy, modify, and distribute this software for any
7 purpose with or without fee is hereby granted, provided that the above
8 copyright notice and this permission notice appear in all copies.
10 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 -->
18 <head>
19 <meta charset="utf-8"/>
20 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
21 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
22 <title>GOT-WORKTREE(5)</title>
23 </head>
24 <body>
25 <table class="head">
26 <tr>
27 <td class="head-ltitle">GOT-WORKTREE(5)</td>
28 <td class="head-vol">File Formats Manual</td>
29 <td class="head-rtitle">GOT-WORKTREE(5)</td>
30 </tr>
31 </table>
32 <div class="manual-text">
33 <section class="Sh">
34 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
35 <p class="Pp"><code class="Nm">got-worktree</code> &#x2014;
36 <span class="Nd">Game of Trees work tree format</span></p>
37 </section>
38 <section class="Sh">
39 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
40 <p class="Pp">A Got
41 <a class="permalink" href="#work"><i class="Em" id="work">work tree</i></a>
42 stores a file hierarchy which corresponds to a versioned snapshot stored in
43 a Git repository. The work tree's meta data is stored in the
44 <span class="Pa">.got</span> directory. A work tree is created with
45 <code class="Cm">got checkout</code> and is required to make changes to a
46 Git repository with <a class="Xr">got(1)</a>.</p>
47 <p class="Pp" id="base">A work tree stores the path to its Git repository, the
48 name of a reference to the branch which files were checked out from, and the
49 ID of a commit on this branch known as the
50 <a class="permalink" href="#base"><i class="Em">base commit</i></a>.</p>
51 <p class="Pp" id="file">File meta-data is stored in a structured file called the
52 <a class="permalink" href="#file"><i class="Em">file index</i></a> which
53 tracks the status of file modifications, additions, and deletions, relative
54 to the base commit in the repository. The file index contains a series of
55 records, and each such record contains the following status information for
56 a particular file:</p>
57 <dl class="Bl-tag">
58 <dt>Copy of filesystem meta-data</dt>
59 <dd>Timestamp, file size, and file ownership information from
60 <a class="Xr">stat(2)</a>. This is only used to detect file modifications
61 and is never applied back to the filesystem. File permissions are not
62 tracked, except for the executable bit. When versioned files are checked
63 out into the work tree, the current <a class="Xr">umask(2)</a> is
64 heeded.</dd>
65 <dt>Blob object ID</dt>
66 <dd>The SHA1 hash of the blob object which corresponds to the contents of this
67 file in the repository. The hash is stored as binary data.</dd>
68 <dt>Commit object ID</dt>
69 <dd>The SHA1 hash of the commit object the file was checked out from. The hash
70 is stored as binary data. This data is used to detect past incomplete
71 update operations. Entries which do not match the work tree's base commit
72 may still need to be updated to match file content stored in the base
73 commit.</dd>
74 <dt>Flags</dt>
75 <dd>This field contains the length, according to <a class="Xr">strlen(3)</a>,
76 of path data which follows, and the following flags:
77 <dl class="Bl-tag">
78 <dt>STAGE</dt>
79 <dd>Reflects the added, modified, or deleted staged state of a path staged
80 with <code class="Cm">got stage</code>.</dd>
81 <dt>NOT_FLUSHED</dt>
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>
90 <dt>NO_BLOB</dt>
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>
98 <dt>NO_COMMIT</dt>
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
109 remove</code>.</dd>
110 </dl>
111 </dd>
112 <dt>Path data</dt>
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
119 stage</code>.</dd>
120 </dl>
121 <p class="Pp">A corrupt or missing file index can be recreated on demand as
122 follows:</p>
123 <p class="Pp"></p>
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&#x00A0;. -type f -exec touch
129 {}&#x00A0;+ # 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">rename(2)</a>. This ensures that no other processes see an
136 inconsistent file index which is in the process of being written.</p>
137 <p class="Pp">Work tree meta data must only be modified while the work tree's
138 <span class="Pa">lock</span> file has been exclusively locked with
139 <a class="Xr">lockf(3)</a>.</p>
140 <p class="Pp">Each work tree has a universal unique identifier. When a work tree
141 is checked out or updated, this identifier is used to create a reference to
142 the current base commit in the Git repository. The presence of this
143 reference prevents the Git garbage collector and <code class="Cm">gotadmin
144 cleanup</code> from discarding the base commit and any objects it refers to.
145 When a work tree is no longer needed its reference can be deleted from the
146 Git repository with <code class="Cm">got ref -d</code>.</p>
147 </section>
148 <section class="Sh">
149 <h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
150 <dl class="Bl-tag Bl-compact">
151 <dt><span class="Pa">.got</span></dt>
152 <dd>Meta-data directory where all files listed below reside.</dd>
153 <dt><span class="Pa">base-commit</span></dt>
154 <dd>SHA1 hex-string representation of the current base commit.</dd>
155 <dt><span class="Pa">file-index</span></dt>
156 <dd>File status information.</dd>
157 <dt><span class="Pa">format</span></dt>
158 <dd>Work tree format number.</dd>
159 <dt><span class="Pa">got.conf</span></dt>
160 <dd>Configuration file for <a class="Xr">got(1)</a>. See
161 <a class="Xr">got.conf(5)</a>.</dd>
162 <dt><span class="Pa">head-ref</span></dt>
163 <dd>Name of the reference to the current branch.</dd>
164 <dt><span class="Pa">lock</span></dt>
165 <dd>Lock file to obtain exclusive write access to meta data.</dd>
166 <dt><span class="Pa">path-prefix</span></dt>
167 <dd>Path inside repository the work tree was checked out from.</dd>
168 <dt><span class="Pa">repository</span></dt>
169 <dd>Path to the repository the work tree was checked out from.</dd>
170 <dt><span class="Pa">uuid</span></dt>
171 <dd>A universal unique identifier for the work tree.</dd>
172 </dl>
173 </section>
174 <section class="Sh">
175 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
176 ALSO</a></h1>
177 <p class="Pp"><a class="Xr">got(1)</a>, <a class="Xr">rename(2)</a>,
178 <a class="Xr">stat(2)</a>, <a class="Xr">umask(2)</a>,
179 <a class="Xr">lockf(3)</a>, <a class="Xr">git-repository(5)</a>,
180 <a class="Xr">got.conf(5)</a></p>
181 </section>
182 </div>
183 <table class="foot">
184 <tr>
185 <td class="foot-date">November 23, 2021</td>
186 <td class="foot-os">OpenBSD 7.0</td>
187 </tr>
188 </table>
189 </body>
190 </html>