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.
19 <meta charset="utf-8"/>
21 table.head, table.foot { width: 100%; }
22 td.head-rtitle, td.foot-os { text-align: right; }
23 td.head-vol { text-align: center; }
24 div.Pp { margin: 1ex 0ex; }
25 div.Nd, div.Bf, div.Op { display: inline; }
26 span.Pa, span.Ad { font-style: italic; }
27 span.Ms { font-weight: bold; }
28 dl.Bl-diag > dt { font-weight: bold; }
29 code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn,
30 code.Cd { font-weight: bold; font-family: inherit; }
32 <title>GOT-WORKTREE(5)</title>
37 <td class="head-ltitle">GOT-WORKTREE(5)</td>
38 <td class="head-vol">File Formats Manual</td>
39 <td class="head-rtitle">GOT-WORKTREE(5)</td>
42 <div class="manual-text">
44 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
45 <code class="Nm">got-worktree</code> —
46 <div class="Nd">Got worktree format</div>
49 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
50 A Got <i class="Em">work tree</i> stores a file hierarchy which corresponds to a
51 versioned snapshot stored in a Git repository. The work tree's meta data is
52 stored in the <span class="Pa">.got</span> directory. A work tree is created
53 with <code class="Cm">got checkout</code> and is required to make changes to a
54 Git repository with <a class="Xr">got(1)</a>.
55 <p class="Pp">A work tree stores the path to its Git repository, the name of a
56 reference to the branch which files were checked out from, and the ID of a
57 commit on this branch known as the <i class="Em">base commit</i>.</p>
58 <p class="Pp">File meta-data is stored in a structured file called the
59 <i class="Em">file index</i> which tracks the status of file modifications,
60 additions, and deletions, relative to the base commit in the repository. The
61 file index contains a series of records, and each such record contains the
62 following status information for a particular file:</p>
64 <dt>Copy of filesystem meta-data</dt>
65 <dd>Timestamp, file size, and file ownership information from
66 <a class="Xr">stat(2)</a>. This is only used to detect file modifications
67 and is never applied back to the filesystem. File permissions are not
68 tracked, except for the executable bit. When versioned files are checked
69 out into the work tree, the current <a class="Xr">umask(2)</a> is
71 <dt>Blob object ID</dt>
72 <dd>The SHA1 hash of the blob object which corresponds to the contents of this
73 file in the repository. The hash is stored as binary data.</dd>
74 <dt>Commit object ID</dt>
75 <dd>The SHA1 hash of the commit object the file was checked out from. The hash
76 is stored as binary data. This data is used to detect past incomplete
77 update operations. Entries which do not match the work tree's base commit
78 may still need to be updated to match file content stored in the base
81 <dd>This field contains the length, according to <a class="Xr">strlen(3)</a>,
82 of path data which follows, and the following flags:
85 <dd>Reflects the added, modified, or deleted staged state of a path staged
86 with <code class="Cm">got stage</code>.</dd>
88 <dd>The entry was added to the file index in memory and does not exist in
89 file index data read from disk. This happens to files which are added
90 to the work tree while operations such as <code class="Cm">got
91 checkout</code>, <code class="Cm">got update</code>,
92 <code class="Cm">got cherrypick,</code> <code class="Cm">got
93 backout,</code> <code class="Cm">got rebase,</code> and
94 <code class="Cm">got histedit</code> are in progress. This flag is
95 always cleared before the entry is written to disk.</dd>
97 <dd>The entry's on-disk file content in the work tree is not based on a
98 blob in the repository. The blob object ID of this entry must be
99 considered invalid. This happens when unversioned files are added with
100 <code class="Cm">got add</code> and when files are added to the work
101 tree by operations such as <code class="Cm">got cherrypick,</code>
102 <code class="Cm">got backout,</code> <code class="Cm">got
103 rebase,</code> and <code class="Cm">got histedit</code>.</dd>
105 <dd>The entry is not based on a commit in the repository. The commit
106 object ID of this entry must be considered invalid. This happens when
107 unversioned files are added with <code class="Cm">got add</code> and
108 when files are added to the work tree by operations such as
109 <code class="Cm">got cherrypick,</code> <code class="Cm">got
110 backout,</code> <code class="Cm">got rebase,</code> and
111 <code class="Cm">got histedit</code>.</dd>
112 <dt>NO_FILE_ON_DISK</dt>
113 <dd>The entry has no corresponding on-disk file in the work tree. This
114 happens when files are removed with <code class="Cm">got
119 <dd>The path of the entry, relative to the work tree root. Path data is of
120 variable length and NUL-padded to a multiple of 8 bytes.</dd>
121 <dt>Staged blob object ID</dt>
122 <dd>The SHA1 hash of a blob object containing file content which has been
123 staged for commit. The hash is stored as binary data. Only present if a
124 file addition or modification has been staged with <code class="Cm">got
127 <p class="Pp">A corrupt or missing file index can be recreated on demand with
128 <code class="Cm">got update</code>. When the file index is modified, it is
129 read into memory in its entirety, modified in place, and written to a
130 temporary file. This temporary file is then moved on top of the old file
131 index with <a class="Xr">rename(2)</a>. This ensures that no other processes
132 see an inconsistent file index which is in the process of being written.</p>
133 <p class="Pp">Work tree meta data must only be modified while the work tree's
134 <span class="Pa">lock</span> file has been exclusively locked with
135 <a class="Xr">lockf(3)</a>.</p>
136 <p class="Pp">Each work tree has a universal unique identifier. When a work tree
137 is checked out or updated, this identifier is used to create a reference to
138 the current base commit in the Git repository. The presence of this
139 reference prevents Git garbage collectors from discarding the base commit
140 and any objects it refers to. When a work tree is no longer needed its
141 reference can be deleted from the Git repository with <code class="Cm">got
145 <h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
146 <dl class="Bl-tag Bl-compact">
147 <dt><span class="Pa">.got</span></dt>
148 <dd>Meta-data directory where all files listed below reside.</dd>
149 <dt><span class="Pa">base-commit</span></dt>
150 <dd>SHA1 hex-string representation of the current base commit.</dd>
151 <dt><span class="Pa">file-index</span></dt>
152 <dd>File status information.</dd>
153 <dt><span class="Pa">format</span></dt>
154 <dd>Work tree format number.</dd>
155 <dt><span class="Pa">head-ref</span></dt>
156 <dd>Name of the reference to the current branch.</dd>
157 <dt><span class="Pa">lock</span></dt>
158 <dd>Lock file to obtain exclusive write access to meta data.</dd>
159 <dt><span class="Pa">path-prefix</span></dt>
160 <dd>Path inside repository the work tree was checked out from.</dd>
161 <dt><span class="Pa">repository</span></dt>
162 <dd>Path to the repository the work tree was checked out from.</dd>
163 <dt><span class="Pa">uuid</span></dt>
164 <dd>A universal unique identifier for the work tree.</dd>
168 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
170 <a class="Xr">got(1)</a>, <a class="Xr">rename(2)</a>,
171 <a class="Xr">stat(2)</a>, <a class="Xr">umask(2)</a>,
172 <a class="Xr">lockf(3)</a>, <a class="Xr">git-repository(5)</a>
177 <td class="foot-date">August 6, 2019</td>
178 <td class="foot-os">OpenBSD 6.5</td>
