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