Blob


1 <!DOCTYPE html>
2 <html>
3 <!-- This is an automatically generated file. Do not edit.
4 Copyright (c) 2017 Martin Pieuchot
5 Copyright (c) 2018, 2019, 2020 Stefan Sperling
7 Permission to use, copy, modify, and distribute this software for any
8 purpose with or without fee is hereby granted, provided that the above
9 copyright notice and this permission notice appear in all copies.
11 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 -->
19 <head>
20 <meta charset="utf-8"/>
21 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
22 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
23 <title>GOT(1)</title>
24 </head>
25 <body>
26 <table class="head">
27 <tr>
28 <td class="head-ltitle">GOT(1)</td>
29 <td class="head-vol">General Commands Manual</td>
30 <td class="head-rtitle">GOT(1)</td>
31 </tr>
32 </table>
33 <div class="manual-text">
34 <section class="Sh">
35 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
36 <p class="Pp"><code class="Nm">got</code> &#x2014; <span class="Nd">Game of
37 Trees</span></p>
38 </section>
39 <section class="Sh">
40 <h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
41 <table class="Nm">
42 <tr>
43 <td><code class="Nm">got</code></td>
44 <td><var class="Ar">command</var> [<code class="Fl">-h</code>]
45 [<var class="Ar">arg ...</var>]</td>
46 </tr>
47 </table>
48 </section>
49 <section class="Sh">
50 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
51 <p class="Pp"><code class="Nm">got</code> is a version control system which
52 stores the history of tracked files in a Git repository, as used by the Git
53 version control system. This repository format is described in
54 <a class="Xr">git-repository(5)</a>.</p>
55 <p class="Pp"><code class="Nm">got</code> is a &#x201C;distributed&#x201D;
56 version control system because every copy of a repository is writeable.
57 Modifications made to files can be synchronized between repositories at any
58 time.</p>
59 <p class="Pp" id="work">Files managed by <code class="Nm">got</code> must be
60 checked out from the repository for modification. Checked out files are
61 stored in a <a class="permalink" href="#work"><i class="Em">work
62 tree</i></a> which can be placed at an arbitrary directory in the filesystem
63 hierarchy. The on-disk format of this work tree is described in
64 <a class="Xr">got-worktree(5)</a>.</p>
65 <p class="Pp"><code class="Nm">got</code> provides global and command-specific
66 options. Global options must precede the command name, and are as
67 follows:</p>
68 <dl class="Bl-tag">
69 <dt id="h"><a class="permalink" href="#h"><code class="Fl">-h</code></a></dt>
70 <dd>Display usage information and exit immediately.</dd>
71 <dt id="V"><a class="permalink" href="#V"><code class="Fl">-V</code></a>,
72 <code class="Fl">--version</code></dt>
73 <dd>Display program version and exit immediately.</dd>
74 </dl>
75 <p class="Pp">The commands for <code class="Nm">got</code> are as follows:</p>
76 <dl class="Bl-tag">
77 <dt id="init"><a class="permalink" href="#init"><code class="Cm">init</code></a>
78 <var class="Ar">repository-path</var></dt>
79 <dd>Create a new empty repository at the specified
80 <var class="Ar">repository-path</var>.
81 <p class="Pp">After <code class="Cm">got init</code>, the
82 <code class="Cm">got import</code> command must be used to populate the
83 empty repository before <code class="Cm">got checkout</code> can be
84 used.</p>
85 </dd>
86 <dt id="im"><a class="permalink" href="#import"><code class="Cm" id="import">import</code></a>
87 [<code class="Fl">-b</code> <var class="Ar">branch</var>]
88 [<code class="Fl">-m</code> <var class="Ar">message</var>]
89 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]
90 [<code class="Fl">-I</code> <var class="Ar">pattern</var>]
91 <var class="Ar">directory</var></dt>
92 <dd>
93 <div class="Bd Bd-indent"><code class="Li">(alias:
94 <code class="Cm">im</code>)</code></div>
95 Create an initial commit in a repository from the file hierarchy within the
96 specified <var class="Ar">directory</var>. The created commit will not
97 have any parent commits, i.e. it will be a root commit. Also create a new
98 reference which provides a branch name for the newly created commit. Show
99 the path of each imported file to indicate progress.
100 <p class="Pp">The <code class="Cm">got import</code> command requires the
101 <code class="Ev">GOT_AUTHOR</code> environment variable to be set,
102 unless an author has been configured in <a class="Xr">got.conf(5)</a> or
103 Git's <code class="Dv">user.name</code> and
104 <code class="Dv">user.email</code> configuration settings can be
105 obtained from the repository's <span class="Pa">.git/config</span> file
106 or from Git's global <span class="Pa">~/.gitconfig</span> configuration
107 file.</p>
108 <p class="Pp">The options for <code class="Cm">got import</code> are as
109 follows:</p>
110 <dl class="Bl-tag">
111 <dt id="b"><a class="permalink" href="#b"><code class="Fl">-b</code></a>
112 <var class="Ar">branch</var></dt>
113 <dd>Create the specified <var class="Ar">branch</var> instead of creating
114 the default branch &#x201C;main&#x201D;. Use of this option is
115 required if the &#x201C;main&#x201D; branch already exists.</dd>
116 <dt id="m"><a class="permalink" href="#m"><code class="Fl">-m</code></a>
117 <var class="Ar">message</var></dt>
118 <dd>Use the specified log message when creating the new commit. Without
119 the <code class="Fl">-m</code> option, <code class="Cm">got
120 import</code> opens a temporary file in an editor where a log message
121 can be written.</dd>
122 <dt id="r"><a class="permalink" href="#r"><code class="Fl">-r</code></a>
123 <var class="Ar">repository-path</var></dt>
124 <dd>Use the repository at the specified path. If not specified, assume the
125 repository is located at or above the current working directory.</dd>
126 <dt id="I"><a class="permalink" href="#I"><code class="Fl">-I</code></a>
127 <var class="Ar">pattern</var></dt>
128 <dd>Ignore files or directories with a name which matches the specified
129 <var class="Ar">pattern</var>. This option may be specified multiple
130 times to build a list of ignore patterns. The
131 <var class="Ar">pattern</var> follows the globbing rules documented in
132 <a class="Xr">glob(7)</a>.</dd>
133 </dl>
134 </dd>
135 <dt id="cl"><a class="permalink" href="#clone"><code class="Cm" id="clone">clone</code></a>
136 [<code class="Fl">-a</code>] [<code class="Fl">-b</code>
137 <var class="Ar">branch</var>] [<code class="Fl">-l</code>]
138 [<code class="Fl">-m</code>] [<code class="Fl">-q</code>]
139 [<code class="Fl">-v</code>] [<code class="Fl">-R</code>
140 <var class="Ar">reference</var>] <var class="Ar">repository-URL</var>
141 [<var class="Ar">directory</var>]</dt>
142 <dd>
143 <div class="Bd Bd-indent"><code class="Li">(alias:
144 <code class="Cm">cl</code>)</code></div>
145 Clone a Git repository at the specified <var class="Ar">repository-URL</var>
146 into the specified <var class="Ar">directory</var>. If no
147 <var class="Ar">directory</var> is specified the directory name will be
148 derived from the name of the cloned repository. <code class="Cm">got
149 clone</code> will refuse to run if the <var class="Ar">directory</var>
150 already exists.
151 <p class="Pp">The <var class="Ar">repository-URL</var> specifies a protocol
152 scheme, a server hostname, an optional port number separated from the
153 hostname by a colon, and a path to the repository on the server:
154 <a class="Lk" href="scheme://hostname:port/path/to/repository">scheme://hostname:port/path/to/repository</a></p>
155 <p class="Pp">The following protocol schemes are supported:</p>
156 <dl class="Bl-tag">
157 <dt>git</dt>
158 <dd>The Git protocol as implemented by the <a class="Xr">git-daemon(1)</a>
159 server. Use of this protocol is discouraged since it supports neither
160 authentication nor encryption.</dd>
161 <dt>git+ssh</dt>
162 <dd>The Git protocol wrapped in an authenticated and encrypted
163 <a class="Xr">ssh(1)</a> tunnel. With this protocol the hostname may
164 contain an embedded username for <a class="Xr">ssh(1)</a> to use:
165 <a class="Mt" href="mailto:user@hostname">user@hostname</a></dd>
166 <dt>ssh</dt>
167 <dd>Short alias for git+ssh.</dd>
168 </dl>
169 <p class="Pp">Objects in the cloned repository are stored in a pack file
170 which is downloaded from the server. This pack file will then be indexed
171 to facilitate access to the objects stored within. If any objects in the
172 pack file are stored in deltified form, all deltas will be fully
173 resolved in order to compute the ID of such objects. This can take some
174 time. More details about the pack file format are documented in
175 <a class="Xr">git-repository(5)</a>.</p>
176 <p class="Pp"><code class="Cm">got clone</code> creates a remote repository
177 entry in the <a class="Xr">got.conf(5)</a> and
178 <span class="Pa">config</span> files of the cloned repository to store
179 the <var class="Ar">repository-url</var> and any
180 <var class="Ar">branch</var> or <var class="Ar">reference</var>
181 arguments for future use by <code class="Cm">got fetch</code> or
182 <a class="Xr">git-fetch(1)</a>.</p>
183 <p class="Pp">The options for <code class="Cm">got clone</code> are as
184 follows:</p>
185 <dl class="Bl-tag">
186 <dt id="a"><a class="permalink" href="#a"><code class="Fl">-a</code></a></dt>
187 <dd>Fetch all branches from the remote repository's
188 &#x201C;refs/heads/&#x201D; reference namespace and set
189 <code class="Cm">fetch-all-branches</code> in the cloned repository's
190 <a class="Xr">got.conf(5)</a> file for future use by
191 <code class="Cm">got fetch</code>. If this option is not specified, a
192 branch resolved via the remote repository's HEAD reference will be
193 fetched. Cannot be used together with the <code class="Fl">-b</code>
194 option.</dd>
195 <dt id="b~2"><a class="permalink" href="#b~2"><code class="Fl">-b</code></a>
196 <var class="Ar">branch</var></dt>
197 <dd>Fetch the specified <var class="Ar">branch</var> from the remote
198 repository's &#x201C;refs/heads/&#x201D; reference namespace. This
199 option may be specified multiple times to build a list of branches to
200 fetch. If the branch corresponding to the remote repository's HEAD
201 reference is not in this list, the cloned repository's HEAD reference
202 will be set to the first branch which was fetched. If this option is
203 not specified, a branch resolved via the remote repository's HEAD
204 reference will be fetched. Cannot be used together with the
205 <code class="Fl">-a</code> option.</dd>
206 <dt id="l"><a class="permalink" href="#l"><code class="Fl">-l</code></a></dt>
207 <dd>List branches and tags available for fetching from the remote
208 repository and exit immediately. Cannot be used together with any of
209 the other options except <code class="Fl">-q</code> and
210 <code class="Fl">-v</code>.</dd>
211 <dt id="m~2"><a class="permalink" href="#m~2"><code class="Fl">-m</code></a></dt>
212 <dd>Create the cloned repository as a mirror of the original repository.
213 This is useful if the cloned repository will not be used to store
214 locally created commits.
215 <p class="Pp">The repository's <a class="Xr">got.conf(5)</a> and
216 <span class="Pa">config</span> files will be set up with the
217 &#x201C;mirror&#x201D; option enabled, such that
218 <code class="Cm">got fetch</code> or <a class="Xr">git-fetch(1)</a>
219 will write incoming changes directly to branches in the
220 &#x201C;refs/heads/&#x201D; reference namespace, rather than to
221 branches in the &#x201C;refs/remotes/&#x201D; namespace. This avoids
222 the usual requirement of having to run <code class="Cm">got
223 rebase</code> after <code class="Cm">got fetch</code> in order to
224 make incoming changes appear on branches in the
225 &#x201C;refs/heads/&#x201D; namespace. But maintaining custom
226 changes in the cloned repository becomes difficult since such
227 changes will be at risk of being discarded whenever incoming changes
228 are fetched.</p>
229 </dd>
230 <dt id="q"><a class="permalink" href="#q"><code class="Fl">-q</code></a></dt>
231 <dd>Suppress progress reporting output. The same option will be passed to
232 <a class="Xr">ssh(1)</a> if applicable.</dd>
233 <dt id="v"><a class="permalink" href="#v"><code class="Fl">-v</code></a></dt>
234 <dd>Verbose mode. Causes <code class="Cm">got clone</code> to print
235 debugging messages to standard error output. This option will be
236 passed to <a class="Xr">ssh(1)</a> if applicable. Multiple -v options
237 increase the verbosity. The maximum is 3.</dd>
238 <dt id="R"><a class="permalink" href="#R"><code class="Fl">-R</code></a>
239 <var class="Ar">reference</var></dt>
240 <dd>In addition to the branches and tags that will be fetched, fetch an
241 arbitrary <var class="Ar">reference</var> from the remote repository's
242 &#x201C;refs/&#x201D; namespace. This option may be specified multiple
243 times to build a list of additional references to fetch. The specified
244 <var class="Ar">reference</var> may either be a path to a specific
245 reference, or a reference namespace which will cause all references in
246 this namespace to be fetched.
247 <p class="Pp">Each reference will be mapped into the cloned repository's
248 &#x201C;refs/remotes/&#x201D; namespace, unless the
249 <code class="Fl">-m</code> option is used to mirror references
250 directly into the cloned repository's &#x201C;refs/&#x201D;
251 namespace.</p>
252 <p class="Pp"><code class="Cm">got clone</code> will refuse to fetch
253 references from the remote repository's
254 &#x201C;refs/remotes/&#x201D; or &#x201C;refs/got/&#x201D;
255 namespace.</p>
256 </dd>
257 </dl>
258 </dd>
259 <dt id="fe"><a class="permalink" href="#fetch"><code class="Cm" id="fetch">fetch</code></a>
260 [<code class="Fl">-a</code>] [<code class="Fl">-b</code>
261 <var class="Ar">branch</var>] [<code class="Fl">-d</code>]
262 [<code class="Fl">-l</code>] [<code class="Fl">-r</code>
263 <var class="Ar">repository-path</var>] [<code class="Fl">-t</code>]
264 [<code class="Fl">-q</code>] [<code class="Fl">-v</code>]
265 [<code class="Fl">-R</code> <var class="Ar">reference</var>]
266 [<code class="Fl">-X</code>] [<var class="Ar">remote-repository</var>]</dt>
267 <dd>
268 <div class="Bd Bd-indent"><code class="Li">(alias:
269 <code class="Cm">fe</code>)</code></div>
270 Fetch new changes from a remote repository. If no
271 <var class="Ar">remote-repository</var> is specified,
272 &#x201C;origin&#x201D; will be used. The remote repository's URL is
273 obtained from the corresponding entry in <a class="Xr">got.conf(5)</a> or
274 Git's <span class="Pa">config</span> file of the local repository, as
275 created by <code class="Cm">got clone</code>.
276 <p class="Pp">New changes will be stored in a separate pack file downloaded
277 from the server. Optionally, separate pack files stored in the
278 repository can be combined with <a class="Xr">git-repack(1)</a>.</p>
279 <p class="Pp">By default, branch references in the
280 &#x201C;refs/remotes/&#x201D; reference namespace will be updated to
281 point at the newly fetched commits. The <code class="Cm">got
282 rebase</code> command can then be used to make new changes visible on
283 branches in the &#x201C;refs/heads/&#x201D; namespace, merging incoming
284 changes with the changes on those branches as necessary.</p>
285 <p class="Pp">If the repository was created as a mirror with
286 <code class="Cm">got clone -m</code> then all branches in the
287 &#x201C;refs/heads/&#x201D; namespace will be updated directly to match
288 the corresponding branches in the remote repository. If those branches
289 contained local commits, these commits will no longer be reachable via a
290 reference and will therefore be at risk of being discarded by Git's
291 garbage collector or <code class="Cm">gotadmin cleanup</code>.
292 Maintaining custom changes in a mirror repository is therefore
293 discouraged.</p>
294 <p class="Pp">In any case, references in the &#x201C;refs/tags/&#x201D;
295 namespace will always be fetched and mapped directly to local references
296 in the same namespace.</p>
297 <p class="Pp">The options for <code class="Cm">got fetch</code> are as
298 follows:</p>
299 <dl class="Bl-tag">
300 <dt id="a~2"><a class="permalink" href="#a~2"><code class="Fl">-a</code></a></dt>
301 <dd>Fetch all branches from the remote repository's
302 &#x201C;refs/heads/&#x201D; reference namespace. This option can be
303 enabled by default for specific repositories in
304 <a class="Xr">got.conf(5)</a>. If this option is not specified, a
305 branch resolved via the remote repository's HEAD reference will be
306 fetched. Cannot be used together with the <code class="Fl">-b</code>
307 option.</dd>
308 <dt id="b~3"><a class="permalink" href="#b~3"><code class="Fl">-b</code></a>
309 <var class="Ar">branch</var></dt>
310 <dd>Fetch the specified <var class="Ar">branch</var> from the remote
311 repository's &#x201C;refs/heads/&#x201D; reference namespace. This
312 option may be specified multiple times to build a list of branches to
313 fetch. If this option is not specified, a branch resolved via the
314 remote repository's HEAD reference will be fetched. Cannot be used
315 together with the <code class="Fl">-a</code> option.</dd>
316 <dt id="d"><a class="permalink" href="#d"><code class="Fl">-d</code></a></dt>
317 <dd>Delete branches and tags from the local repository which are no longer
318 present in the remote repository. Only references are deleted. Any
319 commit, tree, tag, and blob objects belonging to deleted branches or
320 tags remain in the repository and may be removed separately with Git's
321 garbage collector or <code class="Cm">gotadmin cleanup</code>.</dd>
322 <dt id="l~2"><a class="permalink" href="#l~2"><code class="Fl">-l</code></a></dt>
323 <dd>List branches and tags available for fetching from the remote
324 repository and exit immediately. Cannot be used together with any of
325 the other options except <code class="Fl">-v</code>,
326 <code class="Fl">-q</code>, and <code class="Fl">-r</code>.</dd>
327 <dt id="t"><a class="permalink" href="#t"><code class="Fl">-t</code></a></dt>
328 <dd>Allow existing references in the &#x201C;refs/tags&#x201D; namespace
329 to be updated if they have changed on the server. If not specified,
330 only new tag references will be created.</dd>
331 <dt id="r~2"><a class="permalink" href="#r~2"><code class="Fl">-r</code></a>
332 <var class="Ar">repository-path</var></dt>
333 <dd>Use the repository at the specified path. If not specified, assume the
334 repository is located at or above the current working directory. If
335 this directory is a <code class="Nm">got</code> work tree, use the
336 repository path associated with this work tree.</dd>
337 <dt id="q~2"><a class="permalink" href="#q~2"><code class="Fl">-q</code></a></dt>
338 <dd>Suppress progress reporting output. The same option will be passed to
339 <a class="Xr">ssh(1)</a> if applicable.</dd>
340 <dt id="v~2"><a class="permalink" href="#v~2"><code class="Fl">-v</code></a></dt>
341 <dd>Verbose mode. Causes <code class="Cm">got fetch</code> to print
342 debugging messages to standard error output. The same option will be
343 passed to <a class="Xr">ssh(1)</a> if applicable. Multiple -v options
344 increase the verbosity. The maximum is 3.</dd>
345 <dt id="R~2"><a class="permalink" href="#R~2"><code class="Fl">-R</code></a>
346 <var class="Ar">reference</var></dt>
347 <dd>In addition to the branches and tags that will be fetched, fetch an
348 arbitrary <var class="Ar">reference</var> from the remote repository's
349 &#x201C;refs/&#x201D; namespace. This option may be specified multiple
350 times to build a list of additional references to fetch. The specified
351 <var class="Ar">reference</var> may either be a path to a specific
352 reference, or a reference namespace which will cause all references in
353 this namespace to be fetched.
354 <p class="Pp">Each reference will be mapped into the local repository's
355 &#x201C;refs/remotes/&#x201D; namespace, unless the local repository
356 was created as a mirror with <code class="Cm">got clone -m</code> in
357 which case references will be mapped directly into the local
358 repository's &#x201C;refs/&#x201D; namespace.</p>
359 <p class="Pp">Once a reference has been fetched, a branch based on it
360 can be created with <code class="Cm">got branch</code> if
361 needed.</p>
362 <p class="Pp"><code class="Cm">got fetch</code> will refuse to fetch
363 references from the remote repository's
364 &#x201C;refs/remotes/&#x201D; or &#x201C;refs/got/&#x201D;
365 namespace.</p>
366 </dd>
367 <dt id="X"><a class="permalink" href="#X"><code class="Fl">-X</code></a></dt>
368 <dd>Delete all references which correspond to a particular
369 <var class="Ar">remote-repository</var> instead of fetching new
370 changes. This can be useful when a remote repository is being removed
371 from <a class="Xr">got.conf(5)</a>.
372 <p class="Pp">With <code class="Fl">-X</code>, the
373 <var class="Ar">remote-repository</var> argument is mandatory and no
374 other options except <code class="Fl">-r</code>,
375 <code class="Fl">-v</code>, and <code class="Fl">-q</code> are
376 allowed.</p>
377 <p class="Pp">Only references are deleted. Any commit, tree, tag, and
378 blob objects fetched from a remote repository will generally be
379 stored in pack files and may be removed separately with
380 <a class="Xr">git-repack(1)</a> and Git's garbage collector.</p>
381 </dd>
382 </dl>
383 </dd>
384 <dt id="co"><a class="permalink" href="#checkout"><code class="Cm" id="checkout">checkout</code></a>
385 [<code class="Fl">-E</code>] [<code class="Fl">-b</code>
386 <var class="Ar">branch</var>] [<code class="Fl">-c</code>
387 <var class="Ar">commit</var>] [<code class="Fl">-p</code>
388 <var class="Ar">path-prefix</var>] [<code class="Fl">-q</code>]
389 <var class="Ar">repository-path</var>
390 [<var class="Ar">work-tree-path</var>]</dt>
391 <dd>
392 <div class="Bd Bd-indent"><code class="Li">(alias:
393 <code class="Cm">co</code>)</code></div>
394 Copy files from a repository into a new work tree. Show the status of each
395 affected file, using the following status codes:
396 <table class="Bl-column">
397 <tr>
398 <td>A</td>
399 <td>new file was added</td>
400 </tr>
401 <tr>
402 <td>E</td>
403 <td>file already exists in work tree's meta-data</td>
404 </tr>
405 </table>
406 <p class="Pp">If the <var class="Ar">work tree path</var> is not specified,
407 either use the last component of <var class="Ar">repository path</var>,
408 or if a <var class="Ar">path prefix</var> was specified use the last
409 component of <var class="Ar">path prefix</var>.</p>
410 <p class="Pp">The options for <code class="Cm">got checkout</code> are as
411 follows:</p>
412 <dl class="Bl-tag">
413 <dt id="E"><a class="permalink" href="#E"><code class="Fl">-E</code></a></dt>
414 <dd>Proceed with the checkout operation even if the directory at
415 <var class="Ar">work-tree-path</var> is not empty. Existing files will
416 be left intact.</dd>
417 <dt id="b~4"><a class="permalink" href="#b~4"><code class="Fl">-b</code></a>
418 <var class="Ar">branch</var></dt>
419 <dd>Check out files from a commit on the specified
420 <var class="Ar">branch</var>. If this option is not specified, a
421 branch resolved via the repository's HEAD reference will be used.</dd>
422 <dt id="c"><a class="permalink" href="#c"><code class="Fl">-c</code></a>
423 <var class="Ar">commit</var></dt>
424 <dd>Check out files from the specified <var class="Ar">commit</var> on the
425 selected branch. The expected argument is a commit ID SHA1 hash or an
426 existing reference or tag name which will be resolved to a commit ID.
427 An abbreviated hash argument will be expanded to a full SHA1 hash
428 automatically, provided the abbreviation is unique. If this option is
429 not specified, the most recent commit on the selected branch will be
430 used.
431 <p class="Pp">If the specified <var class="Ar">commit</var> is not
432 contained in the selected branch, a different branch which contains
433 this commit must be specified with the <code class="Fl">-b</code>
434 option. If no such branch is known a new branch must be created for
435 this commit with <code class="Cm">got branch</code> before
436 <code class="Cm">got checkout</code> can be used. Checking out work
437 trees with an unknown branch is intentionally not supported.</p>
438 </dd>
439 <dt id="p"><a class="permalink" href="#p"><code class="Fl">-p</code></a>
440 <var class="Ar">path-prefix</var></dt>
441 <dd>Restrict the work tree to a subset of the repository's tree hierarchy.
442 Only files beneath the specified <var class="Ar">path-prefix</var>
443 will be checked out.</dd>
444 <dt id="q~3"><a class="permalink" href="#q~3"><code class="Fl">-q</code></a></dt>
445 <dd>Silence progress output.</dd>
446 </dl>
447 </dd>
448 <dt id="up"><a class="permalink" href="#update"><code class="Cm" id="update">update</code></a>
449 [<code class="Fl">-b</code> <var class="Ar">branch</var>]
450 [<code class="Fl">-c</code> <var class="Ar">commit</var>]
451 [<code class="Fl">-q</code>] [<var class="Ar">path ...</var>]</dt>
452 <dd>
453 <div class="Bd Bd-indent"><code class="Li">(alias:
454 <code class="Cm">up</code>)</code></div>
455 Update an existing work tree to a different <var class="Ar">commit</var>.
456 Change existing files in the work tree as necessary to match file contents
457 of this commit. Preserve any local changes in the work tree and merge them
458 with the incoming changes.
459 <p class="Pp">Files which already contain merge conflicts will not be
460 updated to avoid further complications. Such files will be updated when
461 <code class="Cm">got update</code> is run again after merge conflicts
462 have been resolved. If the conflicting changes are no longer needed
463 affected files can be reverted with <code class="Cm">got revert</code>
464 before running <code class="Cm">got update</code> again.</p>
465 <p class="Pp">Show the status of each affected file, using the following
466 status codes:</p>
467 <table class="Bl-column">
468 <tr>
469 <td>U</td>
470 <td>file was updated and contained no local changes</td>
471 </tr>
472 <tr>
473 <td>G</td>
474 <td>file was updated and local changes were merged cleanly</td>
475 </tr>
476 <tr>
477 <td>C</td>
478 <td>file was updated and conflicts occurred during merge</td>
479 </tr>
480 <tr>
481 <td>D</td>
482 <td>file was deleted</td>
483 </tr>
484 <tr>
485 <td>A</td>
486 <td>new file was added</td>
487 </tr>
488 <tr>
489 <td>~</td>
490 <td>versioned file is obstructed by a non-regular file</td>
491 </tr>
492 <tr>
493 <td>!</td>
494 <td>a missing versioned file was restored</td>
495 </tr>
496 <tr>
497 <td>#</td>
498 <td>file was not updated because it contains merge conflicts</td>
499 </tr>
500 <tr>
501 <td>?</td>
502 <td>changes destined for an unversioned file were not merged</td>
503 </tr>
504 </table>
505 <p class="Pp">If no <var class="Ar">path</var> is specified, update the
506 entire work tree. Otherwise, restrict the update operation to files at
507 or within the specified paths. Each path is required to exist in the
508 update operation's target commit. Files in the work tree outside
509 specified paths will remain unchanged and will retain their previously
510 recorded base commit. Some <code class="Nm">got</code> commands may
511 refuse to run while the work tree contains files from multiple base
512 commits. The base commit of such a work tree can be made consistent by
513 running <code class="Cm">got update</code> across the entire work tree.
514 Specifying a <var class="Ar">path</var> is incompatible with the
515 <code class="Fl">-b</code> option.</p>
516 <p class="Pp"><code class="Cm">got update</code> cannot update paths with
517 staged changes. If changes have been staged with <code class="Cm">got
518 stage</code>, these changes must first be committed with
519 <code class="Cm">got commit</code> or unstaged with <code class="Cm">got
520 unstage</code>.</p>
521 <p class="Pp">The options for <code class="Cm">got update</code> are as
522 follows:</p>
523 <dl class="Bl-tag">
524 <dt id="b~5"><a class="permalink" href="#b~5"><code class="Fl">-b</code></a>
525 <var class="Ar">branch</var></dt>
526 <dd>Switch the work tree's branch reference to the specified
527 <var class="Ar">branch</var> before updating the work tree. This
528 option requires that all paths in the work tree are updated.
529 <p class="Pp">As usual, any local changes in the work tree will be
530 preserved. This can be useful when switching to a newly created
531 branch in order to commit existing local changes to this branch.</p>
532 <p class="Pp">Any local changes must be dealt with separately in order
533 to obtain a work tree with pristine file contents corresponding
534 exactly to the specified <var class="Ar">branch</var>. Such changes
535 could first be committed to a different branch with
536 <code class="Cm">got commit</code>, or could be discarded with
537 <code class="Cm">got revert</code>.</p>
538 </dd>
539 <dt id="c~2"><a class="permalink" href="#c~2"><code class="Fl">-c</code></a>
540 <var class="Ar">commit</var></dt>
541 <dd>Update the work tree to the specified <var class="Ar">commit</var>.
542 The expected argument is a commit ID SHA1 hash or an existing
543 reference or tag name which will be resolved to a commit ID. An
544 abbreviated hash argument will be expanded to a full SHA1 hash
545 automatically, provided the abbreviation is unique. If this option is
546 not specified, the most recent commit on the work tree's branch will
547 be used.</dd>
548 <dt id="q~4"><a class="permalink" href="#q~4"><code class="Fl">-q</code></a></dt>
549 <dd>Silence progress output.</dd>
550 </dl>
551 </dd>
552 <dt id="st"><a class="permalink" href="#status"><code class="Cm" id="status">status</code></a>
553 [<code class="Fl">-I</code>] [<code class="Fl">-s</code>
554 <var class="Ar">status-codes</var>] [<code class="Fl">-S</code>
555 <var class="Ar">status-codes</var>] [<var class="Ar">path ...</var>]</dt>
556 <dd>
557 <div class="Bd Bd-indent"><code class="Li">(alias:
558 <code class="Cm">st</code>)</code></div>
559 Show the current modification status of files in a work tree, using the
560 following status codes:
561 <table class="Bl-column">
562 <tr>
563 <td>M</td>
564 <td>modified file</td>
565 </tr>
566 <tr>
567 <td>A</td>
568 <td>file scheduled for addition in next commit</td>
569 </tr>
570 <tr>
571 <td>D</td>
572 <td>file scheduled for deletion in next commit</td>
573 </tr>
574 <tr>
575 <td>C</td>
576 <td>modified or added file which contains merge conflicts</td>
577 </tr>
578 <tr>
579 <td>!</td>
580 <td>versioned file was expected on disk but is missing</td>
581 </tr>
582 <tr>
583 <td>~</td>
584 <td>versioned file is obstructed by a non-regular file</td>
585 </tr>
586 <tr>
587 <td>?</td>
588 <td>unversioned item not tracked by <code class="Nm">got</code></td>
589 </tr>
590 <tr>
591 <td>m</td>
592 <td>modified file modes (executable bit only)</td>
593 </tr>
594 <tr>
595 <td>N</td>
596 <td>non-existent <var class="Ar">path</var> specified on the command
597 line</td>
598 </tr>
599 </table>
600 <p class="Pp">If no <var class="Ar">path</var> is specified, show
601 modifications in the entire work tree. Otherwise, show modifications at
602 or within the specified paths.</p>
603 <p class="Pp">If changes have been staged with <code class="Cm">got
604 stage</code>, staged changes are shown in the second output column,
605 using the following status codes:</p>
606 <table class="Bl-column">
607 <tr>
608 <td>M</td>
609 <td>file modification is staged</td>
610 </tr>
611 <tr>
612 <td>A</td>
613 <td>file addition is staged</td>
614 </tr>
615 <tr>
616 <td>D</td>
617 <td>file deletion is staged</td>
618 </tr>
619 </table>
620 <p class="Pp">Changes created on top of staged changes are indicated in the
621 first column:</p>
622 <table class="Bl-column">
623 <tr>
624 <td>MM</td>
625 <td>file was modified after earlier changes have been staged</td>
626 </tr>
627 <tr>
628 <td>MA</td>
629 <td>file was modified after having been staged for addition</td>
630 </tr>
631 </table>
632 <p class="Pp">The options for <code class="Cm">got status</code> are as
633 follows:</p>
634 <dl class="Bl-tag">
635 <dt id="I~2"><a class="permalink" href="#I~2"><code class="Fl">-I</code></a></dt>
636 <dd>Show unversioned files even if they match an ignore pattern.</dd>
637 <dt id="s"><a class="permalink" href="#s"><code class="Fl">-s</code></a>
638 <var class="Ar">status-codes</var></dt>
639 <dd>Only show files with a modification status matching any of the
640 single-character status codes contained in the
641 <var class="Ar">status-codes</var> argument. Any combination of codes
642 from the above list of possible status codes may be specified. For
643 staged files, status codes displayed in either column will be matched.
644 Cannot be used together with the <code class="Fl">-S</code>
645 option.</dd>
646 <dt id="S"><a class="permalink" href="#S"><code class="Fl">-S</code></a>
647 <var class="Ar">status-codes</var></dt>
648 <dd>Suppress the output of files with a modification status matching any
649 of the single-character status codes contained in the
650 <var class="Ar">status-codes</var> argument. Any combination of codes
651 from the above list of possible status codes may be specified. For
652 staged files, status codes displayed in either column will be matched.
653 Cannot be used together with the <code class="Fl">-s</code>
654 option.</dd>
655 </dl>
656 <p class="Pp">For compatibility with <a class="Xr">cvs(1)</a> and
657 <a class="Xr">git(1)</a>, <code class="Cm">got status</code> reads
658 <a class="Xr">glob(7)</a> patterns from
659 <span class="Pa">.cvsignore</span> and
660 <span class="Pa">.gitignore</span> files in each traversed directory and
661 will not display unversioned files which match these patterns. As an
662 extension to <a class="Xr">glob(7)</a> matching rules,
663 <code class="Cm">got status</code> supports consecutive asterisks,
664 &#x201C;**&#x201D;, which will match an arbitrary amount of directories.
665 Unlike <a class="Xr">cvs(1)</a>, <code class="Cm">got status</code> only
666 supports a single ignore pattern per line. Unlike
667 <a class="Xr">git(1)</a>, <code class="Cm">got status</code> does not
668 support negated ignore patterns prefixed with &#x201C;!&#x201D;, and
669 gives no special significance to the location of path component
670 separators, &#x201C;/&#x201D;, in a pattern.</p>
671 </dd>
672 <dt id="log"><a class="permalink" href="#log"><code class="Cm">log</code></a>
673 [<code class="Fl">-b</code>] [<code class="Fl">-c</code>
674 <var class="Ar">commit</var>] [<code class="Fl">-C</code>
675 <var class="Ar">number</var>] [<code class="Fl">-l</code>
676 <var class="Ar">N</var>] [<code class="Fl">-p</code>]
677 [<code class="Fl">-P</code>] [<code class="Fl">-s</code>
678 <var class="Ar">search-pattern</var>] [<code class="Fl">-r</code>
679 <var class="Ar">repository-path</var>] [<code class="Fl">-R</code>]
680 [<code class="Fl">-x</code> <var class="Ar">commit</var>]
681 [<var class="Ar">path</var>]</dt>
682 <dd>Display history of a repository. If a <var class="Ar">path</var> is
683 specified, show only commits which modified this path. If invoked in a
684 work tree, the <var class="Ar">path</var> is interpreted relative to the
685 current working directory, and the work tree's path prefix is implicitly
686 prepended. Otherwise, the path is interpreted relative to the repository
687 root.
688 <p class="Pp">The options for <code class="Cm">got log</code> are as
689 follows:</p>
690 <dl class="Bl-tag">
691 <dt id="b~6"><a class="permalink" href="#b~6"><code class="Fl">-b</code></a></dt>
692 <dd>Display individual commits which were merged into the current branch
693 from other branches. By default, <code class="Cm">got log</code> shows
694 the linear history of the current branch only.</dd>
695 <dt id="c~3"><a class="permalink" href="#c~3"><code class="Fl">-c</code></a>
696 <var class="Ar">commit</var></dt>
697 <dd>Start traversing history at the specified
698 <var class="Ar">commit</var>. The expected argument is a commit ID
699 SHA1 hash or an existing reference or tag name which will be resolved
700 to a commit ID. An abbreviated hash argument will be expanded to a
701 full SHA1 hash automatically, provided the abbreviation is unique. If
702 this option is not specified, default to the work tree's current
703 branch if invoked in a work tree, or to the repository's HEAD
704 reference.</dd>
705 <dt id="C"><a class="permalink" href="#C"><code class="Fl">-C</code></a>
706 <var class="Ar">number</var></dt>
707 <dd>Set the number of context lines shown in diffs with
708 <code class="Fl">-p</code>. By default, 3 lines of context are
709 shown.</dd>
710 <dt id="l~3"><a class="permalink" href="#l~3"><code class="Fl">-l</code></a>
711 <var class="Ar">N</var></dt>
712 <dd>Limit history traversal to a given number of commits. If this option
713 is not specified, a default limit value of zero is used, which is
714 treated as an unbounded limit. The
715 <code class="Ev">GOT_LOG_DEFAULT_LIMIT</code> environment variable may
716 be set to change this default value.</dd>
717 <dt id="p~2"><a class="permalink" href="#p~2"><code class="Fl">-p</code></a></dt>
718 <dd>Display the patch of modifications made in each commit. If a
719 <var class="Ar">path</var> is specified, only show the patch of
720 modifications at or within this path.</dd>
721 <dt id="P"><a class="permalink" href="#P"><code class="Fl">-P</code></a></dt>
722 <dd>Display the list of file paths changed in each commit, using the
723 following status codes:
724 <table class="Bl-column">
725 <tr>
726 <td>M</td>
727 <td>modified file</td>
728 </tr>
729 <tr>
730 <td>D</td>
731 <td>file was deleted</td>
732 </tr>
733 <tr>
734 <td>A</td>
735 <td>new file was added</td>
736 </tr>
737 <tr>
738 <td>m</td>
739 <td>modified file modes (executable bit only)</td>
740 </tr>
741 </table>
742 </dd>
743 <dt id="s~2"><a class="permalink" href="#s~2"><code class="Fl">-s</code></a>
744 <var class="Ar">search-pattern</var></dt>
745 <dd>If specified, show only commits with a log message matched by the
746 extended regular expression <var class="Ar">search-pattern</var>. When
747 used together with <code class="Fl">-P</code> then the file paths
748 changed by a commit can be matched as well. Regular expression syntax
749 is documented in <a class="Xr">re_format(7)</a>.</dd>
750 <dt id="r~3"><a class="permalink" href="#r~3"><code class="Fl">-r</code></a>
751 <var class="Ar">repository-path</var></dt>
752 <dd>Use the repository at the specified path. If not specified, assume the
753 repository is located at or above the current working directory. If
754 this directory is a <code class="Nm">got</code> work tree, use the
755 repository path associated with this work tree.</dd>
756 <dt id="R~3"><a class="permalink" href="#R~3"><code class="Fl">-R</code></a></dt>
757 <dd>Determine a set of commits to display as usual, but display these
758 commits in reverse order.</dd>
759 <dt id="x"><a class="permalink" href="#x"><code class="Fl">-x</code></a>
760 <var class="Ar">commit</var></dt>
761 <dd>Stop traversing commit history immediately after the specified
762 <var class="Ar">commit</var> has been traversed. This option has no
763 effect if the specified <var class="Ar">commit</var> is never
764 traversed.</dd>
765 </dl>
766 </dd>
767 <dt id="di"><a class="permalink" href="#diff"><code class="Cm" id="diff">diff</code></a>
768 [<code class="Fl">-a</code>] [<code class="Fl">-c</code>
769 <var class="Ar">commit</var>] [<code class="Fl">-C</code>
770 <var class="Ar">number</var>] [<code class="Fl">-r</code>
771 <var class="Ar">repository-path</var>] [<code class="Fl">-s</code>]
772 [<code class="Fl">-P</code>] [<code class="Fl">-w</code>]
773 [<var class="Ar">object1</var> <var class="Ar">object2</var> |
774 <var class="Ar">path ...</var>]</dt>
775 <dd>
776 <div class="Bd Bd-indent"><code class="Li">(alias:
777 <code class="Cm">di</code>)</code></div>
778 When invoked within a work tree without any arguments, display all local
779 changes in the work tree. If one or more <var class="Ar">path</var>
780 arguments are specified, only show changes within the specified paths.
781 <p class="Pp">If two arguments are provided, treat each argument as a
782 reference, a tag name, or an object ID SHA1 hash, and display
783 differences between the corresponding objects. Both objects must be of
784 the same type (blobs, trees, or commits). An abbreviated hash argument
785 will be expanded to a full SHA1 hash automatically, provided the
786 abbreviation is unique. If none of these interpretations produce a valid
787 result or if the <code class="Fl">-P</code> option is used, and if
788 <code class="Cm">got diff</code> is running in a work tree, attempt to
789 interpret the two arguments as paths.</p>
790 <p class="Pp">The options for <code class="Cm">got diff</code> are as
791 follows:</p>
792 <dl class="Bl-tag">
793 <dt id="a~3"><a class="permalink" href="#a~3"><code class="Fl">-a</code></a></dt>
794 <dd>Treat file contents as ASCII text even if binary data is
795 detected.</dd>
796 <dt id="c~4"><a class="permalink" href="#c~4"><code class="Fl">-c</code></a>
797 <var class="Ar">commit</var></dt>
798 <dd>Show differences between commits in the repository. This options may
799 be used up to two times. When used only once, show differences between
800 the specified <var class="Ar">commit</var> and its first parent
801 commit. When used twice, show differences between the two specified
802 commits.
803 <p class="Pp">The expected argument is a commit ID SHA1 hash or an
804 existing reference or tag name which will be resolved to a commit
805 ID. An abbreviated hash argument will be expanded to a full SHA1
806 hash automatically, provided the abbreviation is unique.</p>
807 <p class="Pp">If the <code class="Fl">-c</code> option is used, all
808 non-option arguments will be interpreted as paths. If one or more
809 such <var class="Ar">path</var> arguments are provided, only show
810 differences for the specified paths.</p>
811 <p class="Pp">Cannot be used together with the
812 <code class="Fl">-P</code> option.</p>
813 </dd>
814 <dt id="C~2"><a class="permalink" href="#C~2"><code class="Fl">-C</code></a>
815 <var class="Ar">number</var></dt>
816 <dd>Set the number of context lines shown in the diff. By default, 3 lines
817 of context are shown.</dd>
818 <dt id="r~4"><a class="permalink" href="#r~4"><code class="Fl">-r</code></a>
819 <var class="Ar">repository-path</var></dt>
820 <dd>Use the repository at the specified path. If not specified, assume the
821 repository is located at or above the current working directory. If
822 this directory is a <code class="Nm">got</code> work tree, use the
823 repository path associated with this work tree.</dd>
824 <dt id="s~3"><a class="permalink" href="#s~3"><code class="Fl">-s</code></a></dt>
825 <dd>Show changes staged with <code class="Cm">got stage</code> instead of
826 showing local changes in the work tree. This option is only valid when
827 <code class="Cm">got diff</code> is invoked in a work tree.</dd>
828 <dt id="P~2"><a class="permalink" href="#P~2"><code class="Fl">-P</code></a></dt>
829 <dd>Interpret all arguments as paths only. This option can be used to
830 resolve ambiguity in cases where paths look like tag names, reference
831 names, or object IDs. This option is only valid when
832 <code class="Cm">got diff</code> is invoked in a work tree.</dd>
833 <dt id="w"><a class="permalink" href="#w"><code class="Fl">-w</code></a></dt>
834 <dd>Ignore whitespace-only changes.</dd>
835 </dl>
836 </dd>
837 <dt id="bl"><a class="permalink" href="#blame"><code class="Cm" id="blame">blame</code></a>
838 [<code class="Fl">-c</code> <var class="Ar">commit</var>]
839 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]
840 <var class="Ar">path</var></dt>
841 <dd>
842 <div class="Bd Bd-indent"><code class="Li">(alias:
843 <code class="Cm">bl</code>)</code></div>
844 Display line-by-line history of a file at the specified path.
845 <p class="Pp">The options for <code class="Cm">got blame</code> are as
846 follows:</p>
847 <dl class="Bl-tag">
848 <dt id="c~5"><a class="permalink" href="#c~5"><code class="Fl">-c</code></a>
849 <var class="Ar">commit</var></dt>
850 <dd>Start traversing history at the specified
851 <var class="Ar">commit</var>. The expected argument is a commit ID
852 SHA1 hash or an existing reference or tag name which will be resolved
853 to a commit ID. An abbreviated hash argument will be expanded to a
854 full SHA1 hash automatically, provided the abbreviation is
855 unique.</dd>
856 <dt id="r~5"><a class="permalink" href="#r~5"><code class="Fl">-r</code></a>
857 <var class="Ar">repository-path</var></dt>
858 <dd>Use the repository at the specified path. If not specified, assume the
859 repository is located at or above the current working directory. If
860 this directory is a <code class="Nm">got</code> work tree, use the
861 repository path associated with this work tree.</dd>
862 </dl>
863 </dd>
864 <dt id="tr"><a class="permalink" href="#tree"><code class="Cm" id="tree">tree</code></a>
865 [<code class="Fl">-c</code> <var class="Ar">commit</var>]
866 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]
867 [<code class="Fl">-i</code>] [<code class="Fl">-R</code>]
868 [<var class="Ar">path</var>]</dt>
869 <dd>
870 <div class="Bd Bd-indent"><code class="Li">(alias:
871 <code class="Cm">tr</code>)</code></div>
872 Display a listing of files and directories at the specified directory path
873 in the repository. Entries shown in this listing may carry one of the
874 following trailing annotations:
875 <table class="Bl-column">
876 <tr>
877 <td>@</td>
878 <td>entry is a symbolic link</td>
879 </tr>
880 <tr>
881 <td>/</td>
882 <td>entry is a directory</td>
883 </tr>
884 <tr>
885 <td>*</td>
886 <td>entry is an executable file</td>
887 </tr>
888 <tr>
889 <td>$</td>
890 <td>entry is a Git submodule</td>
891 </tr>
892 </table>
893 <p class="Pp">Symbolic link entries are also annotated with the target path
894 of the link.</p>
895 <p class="Pp">If no <var class="Ar">path</var> is specified, list the
896 repository path corresponding to the current directory of the work tree,
897 or the root directory of the repository if there is no work tree.</p>
898 <p class="Pp">The options for <code class="Cm">got tree</code> are as
899 follows:</p>
900 <dl class="Bl-tag">
901 <dt id="c~6"><a class="permalink" href="#c~6"><code class="Fl">-c</code></a>
902 <var class="Ar">commit</var></dt>
903 <dd>List files and directories as they appear in the specified
904 <var class="Ar">commit</var>. The expected argument is a commit ID
905 SHA1 hash or an existing reference or tag name which will be resolved
906 to a commit ID. An abbreviated hash argument will be expanded to a
907 full SHA1 hash automatically, provided the abbreviation is
908 unique.</dd>
909 <dt id="r~6"><a class="permalink" href="#r~6"><code class="Fl">-r</code></a>
910 <var class="Ar">repository-path</var></dt>
911 <dd>Use the repository at the specified path. If not specified, assume the
912 repository is located at or above the current working directory. If
913 this directory is a <code class="Nm">got</code> work tree, use the
914 repository path associated with this work tree.</dd>
915 <dt id="i"><a class="permalink" href="#i"><code class="Fl">-i</code></a></dt>
916 <dd>Show object IDs of files (blob objects) and directories (tree
917 objects).</dd>
918 <dt id="R~4"><a class="permalink" href="#R~4"><code class="Fl">-R</code></a></dt>
919 <dd>Recurse into sub-directories in the repository.</dd>
920 </dl>
921 </dd>
922 <dt id="ref"><a class="permalink" href="#ref"><code class="Cm">ref</code></a>
923 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]
924 [<code class="Fl">-l</code>] [<code class="Fl">-t</code>]
925 [<code class="Fl">-c</code> <var class="Ar">object</var>]
926 [<code class="Fl">-s</code> <var class="Ar">reference</var>]
927 [<code class="Fl">-d</code>] [<var class="Ar">name</var>]</dt>
928 <dd>Manage references in a repository.
929 <p class="Pp">References may be listed, created, deleted, and changed. When
930 creating, deleting, or changing a reference the specified
931 <var class="Ar">name</var> must be an absolute reference name, i.e. it
932 must begin with &#x201C;refs/&#x201D;.</p>
933 <p class="Pp">The options for <code class="Cm">got ref</code> are as
934 follows:</p>
935 <dl class="Bl-tag">
936 <dt id="r~7"><a class="permalink" href="#r~7"><code class="Fl">-r</code></a>
937 <var class="Ar">repository-path</var></dt>
938 <dd>Use the repository at the specified path. If not specified, assume the
939 repository is located at or above the current working directory. If
940 this directory is a <code class="Nm">got</code> work tree, use the
941 repository path associated with this work tree.</dd>
942 <dt id="l~4"><a class="permalink" href="#l~4"><code class="Fl">-l</code></a></dt>
943 <dd>List references in the repository. If no <var class="Ar">name</var> is
944 specified, list all existing references in the repository. If
945 <var class="Ar">name</var> is a reference namespace, list all
946 references in this namespace. Otherwise, show only the reference with
947 the given <var class="Ar">name</var>. Cannot be used together with any
948 other options except <code class="Fl">-r</code> and
949 <code class="Fl">-t</code>.</dd>
950 <dt id="t~2"><a class="permalink" href="#t~2"><code class="Fl">-t</code></a></dt>
951 <dd>Sort listed references by modification time (most recently modified
952 first) instead of sorting by lexicographical order. Use of this option
953 requires the <code class="Fl">-l</code> option to be used as
954 well.</dd>
955 <dt id="c~7"><a class="permalink" href="#c~7"><code class="Fl">-c</code></a>
956 <var class="Ar">object</var></dt>
957 <dd>Create a reference or change an existing reference. The reference with
958 the specified <var class="Ar">name</var> will point at the specified
959 <var class="Ar">object</var>. The expected
960 <var class="Ar">object</var> argument is a ID SHA1 hash or an existing
961 reference or tag name which will be resolved to the ID of a
962 corresponding commit, tree, tag, or blob object. Cannot be used
963 together with any other options except
964 <code class="Fl">-r</code>.</dd>
965 <dt id="s~4"><a class="permalink" href="#s~4"><code class="Fl">-s</code></a>
966 <var class="Ar">reference</var></dt>
967 <dd>Create a symbolic reference, or change an existing symbolic reference.
968 The symbolic reference with the specified <var class="Ar">name</var>
969 will point at the specified <var class="Ar">reference</var> which must
970 already exist in the repository. Care should be taken not to create
971 loops between references when this option is used. Cannot be used
972 together with any other options except
973 <code class="Fl">-r</code>.</dd>
974 <dt id="d~2"><a class="permalink" href="#d~2"><code class="Fl">-d</code></a></dt>
975 <dd>Delete the reference with the specified <var class="Ar">name</var>
976 from the repository. Any commit, tree, tag, and blob objects belonging
977 to deleted references remain in the repository and may be removed
978 separately with Git's garbage collector or <code class="Cm">gotadmin
979 cleanup</code>. Cannot be used together with any other options except
980 <code class="Fl">-r</code>.</dd>
981 </dl>
982 </dd>
983 <dt id="br"><a class="permalink" href="#branch"><code class="Cm" id="branch">branch</code></a>
984 [<code class="Fl">-c</code> <var class="Ar">commit</var>]
985 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]
986 [<code class="Fl">-l</code>] [<code class="Fl">-d</code>
987 <var class="Ar">name</var>] [<code class="Fl">-n</code>]
988 [<var class="Ar">name</var>]</dt>
989 <dd>
990 <div class="Bd Bd-indent"><code class="Li">(alias:
991 <code class="Cm">br</code>)</code></div>
992 Create, list, or delete branches.
993 <p class="Pp">Local branches are managed via references which live in the
994 &#x201C;refs/heads/&#x201D; reference namespace. The
995 <code class="Cm">got branch</code> command creates references in this
996 namespace only.</p>
997 <p class="Pp">When deleting branches the specified
998 <var class="Ar">name</var> is searched in the &#x201C;refs/heads&#x201D;
999 reference namespace first. If no corresponding branch is found the
1000 &#x201C;refs/remotes&#x201D; namespace will be searched next.</p>
1001 <p class="Pp">If invoked in a work tree without any arguments, print the
1002 name of the work tree's current branch.</p>
1003 <p class="Pp">If a <var class="Ar">name</var> argument is passed, attempt to
1004 create a branch reference with the given name. By default the new branch
1005 reference will point at the latest commit on the work tree's current
1006 branch if invoked in a work tree, and otherwise to a commit resolved via
1007 the repository's HEAD reference.</p>
1008 <p class="Pp">If invoked in a work tree, once the branch was created
1009 successfully switch the work tree's head reference to the newly created
1010 branch and update files across the entire work tree, just like
1011 <code class="Cm">got update -b</code> <var class="Ar">name</var> would
1012 do. Show the status of each affected file, using the following status
1013 codes:</p>
1014 <table class="Bl-column">
1015 <tr>
1016 <td>U</td>
1017 <td>file was updated and contained no local changes</td>
1018 </tr>
1019 <tr>
1020 <td>G</td>
1021 <td>file was updated and local changes were merged cleanly</td>
1022 </tr>
1023 <tr>
1024 <td>C</td>
1025 <td>file was updated and conflicts occurred during merge</td>
1026 </tr>
1027 <tr>
1028 <td>D</td>
1029 <td>file was deleted</td>
1030 </tr>
1031 <tr>
1032 <td>A</td>
1033 <td>new file was added</td>
1034 </tr>
1035 <tr>
1036 <td>~</td>
1037 <td>versioned file is obstructed by a non-regular file</td>
1038 </tr>
1039 <tr>
1040 <td>!</td>
1041 <td>a missing versioned file was restored</td>
1042 </tr>
1043 </table>
1044 <p class="Pp">The options for <code class="Cm">got branch</code> are as
1045 follows:</p>
1046 <dl class="Bl-tag">
1047 <dt id="c~8"><a class="permalink" href="#c~8"><code class="Fl">-c</code></a>
1048 <var class="Ar">commit</var></dt>
1049 <dd>Make a newly created branch reference point at the specified
1050 <var class="Ar">commit</var>. The expected
1051 <var class="Ar">commit</var> argument is a commit ID SHA1 hash or an
1052 existing reference or tag name which will be resolved to a commit
1053 ID.</dd>
1054 <dt id="r~8"><a class="permalink" href="#r~8"><code class="Fl">-r</code></a>
1055 <var class="Ar">repository-path</var></dt>
1056 <dd>Use the repository at the specified path. If not specified, assume the
1057 repository is located at or above the current working directory. If
1058 this directory is a <code class="Nm">got</code> work tree, use the
1059 repository path associated with this work tree.</dd>
1060 <dt id="l~5"><a class="permalink" href="#l~5"><code class="Fl">-l</code></a></dt>
1061 <dd>List all existing branches in the repository, including copies of
1062 remote repositories' branches in the &#x201C;refs/remotes/&#x201D;
1063 reference namespace.
1064 <p class="Pp">If invoked in a work tree, the work tree's current branch
1065 is shown with one the following annotations:</p>
1066 <table class="Bl-column">
1067 <tr>
1068 <td>*</td>
1069 <td>work tree's base commit matches the branch tip</td>
1070 </tr>
1071 <tr>
1072 <td>~</td>
1073 <td>work tree's base commit is out-of-date</td>
1074 </tr>
1075 </table>
1076 </dd>
1077 <dt id="t~3"><a class="permalink" href="#t~3"><code class="Fl">-t</code></a></dt>
1078 <dd>Sort listed branches by modification time (most recently modified
1079 first) instead of sorting by lexicographical order. Branches in the
1080 &#x201C;refs/heads/&#x201D; reference namespace are listed before
1081 branches in &#x201C;refs/remotes/&#x201D; regardless. Use of this
1082 option requires the <code class="Fl">-l</code> option to be used as
1083 well.</dd>
1084 <dt id="d~3"><a class="permalink" href="#d~3"><code class="Fl">-d</code></a>
1085 <var class="Ar">name</var></dt>
1086 <dd>Delete the branch with the specified <var class="Ar">name</var> from
1087 the &#x201C;refs/heads&#x201D; or &#x201C;refs/remotes&#x201D;
1088 reference namespace.
1089 <p class="Pp">Only the branch reference is deleted. Any commit, tree,
1090 and blob objects belonging to the branch remain in the repository
1091 and may be removed separately with Git's garbage collector or
1092 <code class="Cm">gotadmin cleanup</code>.</p>
1093 </dd>
1094 <dt id="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
1095 <dd>Do not switch and update the work tree after creating a new
1096 branch.</dd>
1097 </dl>
1098 </dd>
1099 <dt id="tag"><a class="permalink" href="#tag"><code class="Cm">tag</code></a>
1100 [<code class="Fl">-c</code> <var class="Ar">commit</var>]
1101 [<code class="Fl">-m</code> <var class="Ar">message</var>]
1102 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]
1103 [<code class="Fl">-l</code>] <var class="Ar">name</var></dt>
1104 <dd>Manage tags in a repository.
1105 <p class="Pp">Tags are managed via references which live in the
1106 &#x201C;refs/tags/&#x201D; reference namespace. The <code class="Cm">got
1107 tag</code> command operates on references in this namespace only.
1108 References in this namespace point at tag objects which contain a
1109 pointer to another object, a tag message, as well as author and
1110 timestamp information.</p>
1111 <p class="Pp">Attempt to create a tag with the given
1112 <var class="Ar">name</var>, and make this tag point at the given
1113 <var class="Ar">commit</var>. If no commit is specified, default to the
1114 latest commit on the work tree's current branch if invoked in a work
1115 tree, and to a commit resolved via the repository's HEAD reference
1116 otherwise.</p>
1117 <p class="Pp">The options for <code class="Cm">got tag</code> are as
1118 follows:</p>
1119 <dl class="Bl-tag">
1120 <dt id="c~9"><a class="permalink" href="#c~9"><code class="Fl">-c</code></a>
1121 <var class="Ar">commit</var></dt>
1122 <dd>Make the newly created tag reference point at the specified
1123 <var class="Ar">commit</var>. The expected
1124 <var class="Ar">commit</var> argument is a commit ID SHA1 hash or an
1125 existing reference or tag name which will be resolved to a commit ID.
1126 An abbreviated hash argument will be expanded to a full SHA1 hash
1127 automatically, provided the abbreviation is unique.</dd>
1128 <dt id="m~3"><a class="permalink" href="#m~3"><code class="Fl">-m</code></a>
1129 <var class="Ar">message</var></dt>
1130 <dd>Use the specified tag message when creating the new tag. Without the
1131 <code class="Fl">-m</code> option, <code class="Cm">got tag</code>
1132 opens a temporary file in an editor where a tag message can be
1133 written.</dd>
1134 <dt id="r~9"><a class="permalink" href="#r~9"><code class="Fl">-r</code></a>
1135 <var class="Ar">repository-path</var></dt>
1136 <dd>Use the repository at the specified path. If not specified, assume the
1137 repository is located at or above the current working directory. If
1138 this directory is a <code class="Nm">got</code> work tree, use the
1139 repository path associated with this work tree.</dd>
1140 <dt id="l~6"><a class="permalink" href="#l~6"><code class="Fl">-l</code></a></dt>
1141 <dd>List all existing tags in the repository instead of creating a new
1142 tag. If this option is used, no other command-line arguments are
1143 allowed.</dd>
1144 </dl>
1145 <p class="Pp">By design, the <code class="Cm">got tag</code> command will
1146 not delete tags or change existing tags. If a tag must be deleted, the
1147 <code class="Cm">got ref</code> command may be used to delete a tag's
1148 reference. This should only be done if the tag has not already been
1149 copied to another repository.</p>
1150 </dd>
1151 <dt id="add"><a class="permalink" href="#add"><code class="Cm">add</code></a>
1152 [<code class="Fl">-R</code>] [<code class="Fl">-I</code>]
1153 <var class="Ar">path ...</var></dt>
1154 <dd>Schedule unversioned files in a work tree for addition to the repository
1155 in the next commit. By default, files which match a <code class="Cm">got
1156 status</code> ignore pattern will not be added.
1157 <p class="Pp">The options for <code class="Cm">got add</code> are as
1158 follows:</p>
1159 <dl class="Bl-tag">
1160 <dt id="R~5"><a class="permalink" href="#R~5"><code class="Fl">-R</code></a></dt>
1161 <dd>Permit recursion into directories. If this option is not specified,
1162 <code class="Cm">got add</code> will refuse to run if a specified
1163 <var class="Ar">path</var> is a directory.</dd>
1164 <dt id="I~3"><a class="permalink" href="#I~3"><code class="Fl">-I</code></a></dt>
1165 <dd>Add files even if they match a <code class="Cm">got status</code>
1166 ignore pattern.</dd>
1167 </dl>
1168 </dd>
1169 <dt id="rm"><a class="permalink" href="#remove"><code class="Cm" id="remove">remove</code></a>
1170 [<code class="Fl">-f</code>] [<code class="Fl">-k</code>]
1171 [<code class="Fl">-R</code>] [<code class="Fl">-s</code>
1172 <var class="Ar">status-codes</var>] <var class="Ar">path ...</var></dt>
1173 <dd>
1174 <div class="Bd Bd-indent"><code class="Li">(alias:
1175 <code class="Cm">rm</code>)</code></div>
1176 Remove versioned files from a work tree and schedule them for deletion from
1177 the repository in the next commit.
1178 <p class="Pp">The options for <code class="Cm">got remove</code> are as
1179 follows:</p>
1180 <dl class="Bl-tag">
1181 <dt id="f"><a class="permalink" href="#f"><code class="Fl">-f</code></a></dt>
1182 <dd>Perform the operation even if a file contains local
1183 modifications.</dd>
1184 <dt id="k"><a class="permalink" href="#k"><code class="Fl">-k</code></a></dt>
1185 <dd>Keep affected files on disk.</dd>
1186 <dt id="R~6"><a class="permalink" href="#R~6"><code class="Fl">-R</code></a></dt>
1187 <dd>Permit recursion into directories. If this option is not specified,
1188 <code class="Cm">got remove</code> will refuse to run if a specified
1189 <var class="Ar">path</var> is a directory.</dd>
1190 <dt id="s~5"><a class="permalink" href="#s~5"><code class="Fl">-s</code></a>
1191 <var class="Ar">status-codes</var></dt>
1192 <dd>Only delete files with a modification status matching one of the
1193 single-character status codes contained in the
1194 <var class="Ar">status-codes</var> argument. The following status
1195 codes may be specified:
1196 <table class="Bl-column">
1197 <tr>
1198 <td>M</td>
1199 <td>modified file (this implies the <code class="Fl">-f</code>
1200 option)</td>
1201 </tr>
1202 <tr>
1203 <td>!</td>
1204 <td>versioned file expected on disk but missing</td>
1205 </tr>
1206 </table>
1207 </dd>
1208 </dl>
1209 </dd>
1210 <dt id="rv"><a class="permalink" href="#revert"><code class="Cm" id="revert">revert</code></a>
1211 [<code class="Fl">-p</code>] [<code class="Fl">-F</code>
1212 <var class="Ar">response-script</var>] [<code class="Fl">-R</code>]
1213 <var class="Ar">path ...</var></dt>
1214 <dd>
1215 <div class="Bd Bd-indent"><code class="Li">(alias:
1216 <code class="Cm">rv</code>)</code></div>
1217 Revert any local changes in files at the specified paths in a work tree.
1218 File contents will be overwritten with those contained in the work tree's
1219 base commit. There is no way to bring discarded changes back after
1220 <code class="Cm">got revert</code>!
1221 <p class="Pp">If a file was added with <code class="Cm">got add</code> it
1222 will become an unversioned file again. If a file was deleted with
1223 <code class="Cm">got remove</code> it will be restored.</p>
1224 <p class="Pp">The options for <code class="Cm">got revert</code> are as
1225 follows:</p>
1226 <dl class="Bl-tag">
1227 <dt id="p~3"><a class="permalink" href="#p~3"><code class="Fl">-p</code></a></dt>
1228 <dd>Instead of reverting all changes in files, interactively select or
1229 reject changes to revert based on &#x201C;y&#x201D; (revert change),
1230 &#x201C;n&#x201D; (keep change), and &#x201C;q&#x201D; (quit reverting
1231 this file) responses. If a file is in modified status, individual
1232 patches derived from the modified file content can be reverted. Files
1233 in added or deleted status may only be reverted in their
1234 entirety.</dd>
1235 <dt id="F"><a class="permalink" href="#F"><code class="Fl">-F</code></a>
1236 <var class="Ar">response-script</var></dt>
1237 <dd>With the <code class="Fl">-p</code> option, read &#x201C;y&#x201D;,
1238 &#x201C;n&#x201D;, and &#x201C;q&#x201D; responses line-by-line from
1239 the specified <var class="Ar">response-script</var> file instead of
1240 prompting interactively.</dd>
1241 <dt id="R~7"><a class="permalink" href="#R~7"><code class="Fl">-R</code></a></dt>
1242 <dd>Permit recursion into directories. If this option is not specified,
1243 <code class="Cm">got revert</code> will refuse to run if a specified
1244 <var class="Ar">path</var> is a directory.</dd>
1245 </dl>
1246 </dd>
1247 <dt id="ci"><a class="permalink" href="#commit"><code class="Cm" id="commit">commit</code></a>
1248 [<code class="Fl">-F</code> <var class="Ar">path</var>]
1249 [<code class="Fl">-m</code> <var class="Ar">message</var>]
1250 [<code class="Fl">-N</code>] [<code class="Fl">-S</code>]
1251 [<var class="Ar">path ...</var>]</dt>
1252 <dd>
1253 <div class="Bd Bd-indent"><code class="Li">(alias:
1254 <code class="Cm">ci</code>)</code></div>
1255 Create a new commit in the repository from changes in a work tree and use
1256 this commit as the new base commit for the work tree. If no
1257 <var class="Ar">path</var> is specified, commit all changes in the work
1258 tree. Otherwise, commit changes at or within the specified paths.
1259 <p class="Pp">If changes have been explicitly staged for commit with
1260 <code class="Cm">got stage</code>, only commit staged changes and reject
1261 any specified paths which have not been staged.</p>
1262 <p class="Pp"><code class="Cm">got commit</code> opens a temporary file in
1263 an editor where a log message can be written unless the
1264 <code class="Fl">-m</code> option is used or the
1265 <code class="Fl">-F</code> and <code class="Fl">-N</code> options are
1266 used together.</p>
1267 <p class="Pp">Show the status of each affected file, using the following
1268 status codes:</p>
1269 <table class="Bl-column">
1270 <tr>
1271 <td>M</td>
1272 <td>modified file</td>
1273 </tr>
1274 <tr>
1275 <td>D</td>
1276 <td>file was deleted</td>
1277 </tr>
1278 <tr>
1279 <td>A</td>
1280 <td>new file was added</td>
1281 </tr>
1282 <tr>
1283 <td>m</td>
1284 <td>modified file modes (executable bit only)</td>
1285 </tr>
1286 </table>
1287 <p class="Pp">Files which are not part of the new commit will retain their
1288 previously recorded base commit. Some <code class="Nm">got</code>
1289 commands may refuse to run while the work tree contains files from
1290 multiple base commits. The base commit of such a work tree can be made
1291 consistent by running <code class="Cm">got update</code> across the
1292 entire work tree.</p>
1293 <p class="Pp">The <code class="Cm">got commit</code> command requires the
1294 <code class="Ev">GOT_AUTHOR</code> environment variable to be set,
1295 unless an author has been configured in <a class="Xr">got.conf(5)</a> or
1296 Git's <code class="Dv">user.name</code> and
1297 <code class="Dv">user.email</code> configuration settings can be
1298 obtained from the repository's <span class="Pa">.git/config</span> file
1299 or from Git's global <span class="Pa">~/.gitconfig</span> configuration
1300 file.</p>
1301 <p class="Pp">The options for <code class="Cm">got commit</code> are as
1302 follows:</p>
1303 <dl class="Bl-tag">
1304 <dt id="F~2"><a class="permalink" href="#F~2"><code class="Fl">-F</code></a>
1305 <var class="Ar">path</var></dt>
1306 <dd>Use the prepared log message stored in the file found at
1307 <var class="Ar">path</var> when creating the new commit.
1308 <code class="Cm">got commit</code> opens a temporary file in an editor
1309 where the prepared log message can be reviewed and edited further if
1310 needed. Cannot be used together with the <code class="Fl">-m</code>
1311 option.</dd>
1312 <dt id="m~4"><a class="permalink" href="#m~4"><code class="Fl">-m</code></a>
1313 <var class="Ar">message</var></dt>
1314 <dd>Use the specified log message when creating the new commit. Cannot be
1315 used together with the <code class="Fl">-F</code> option.</dd>
1316 <dt id="N"><a class="permalink" href="#N"><code class="Fl">-N</code></a></dt>
1317 <dd>This option prevents <code class="Cm">got commit</code> from opening
1318 the commit message in an editor. It has no effect unless it is used
1319 together with the <code class="Fl">-F</code> option and is intended
1320 for non-interactive use such as scripting.</dd>
1321 <dt id="S~2"><a class="permalink" href="#S~2"><code class="Fl">-S</code></a></dt>
1322 <dd>Allow the addition of symbolic links which point outside of the path
1323 space that is under version control. By default, <code class="Cm">got
1324 commit</code> will reject such symbolic links due to safety concerns.
1325 As a precaution, <code class="Nm">got</code> may decide to represent
1326 such a symbolic link as a regular file which contains the link's
1327 target path, rather than creating an actual symbolic link which points
1328 outside of the work tree. Use of this option is discouraged because
1329 external mechanisms such as &#x201C;make obj&#x201D; are better suited
1330 for managing symbolic links to paths not under version control.</dd>
1331 </dl>
1332 <p class="Pp"><code class="Cm">got commit</code> will refuse to run if
1333 certain preconditions are not met. If the work tree's current branch is
1334 not in the &#x201C;refs/heads/&#x201D; reference namespace, new commits
1335 may not be created on this branch. Local changes may only be committed
1336 if they are based on file content found in the most recent commit on the
1337 work tree's branch. If a path is found to be out of date,
1338 <code class="Cm">got update</code> must be used first in order to merge
1339 local changes with changes made in the repository.</p>
1340 </dd>
1341 <dt id="se"><a class="permalink" href="#send"><code class="Cm" id="send">send</code></a>
1342 [<code class="Fl">-a</code>] [<code class="Fl">-b</code>
1343 <var class="Ar">branch</var>] [<code class="Fl">-d</code>
1344 <var class="Ar">branch</var>] [<code class="Fl">-f</code>]
1345 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]
1346 [<code class="Fl">-t</code> <var class="Ar">tag</var>]
1347 [<code class="Fl">-T</code>] [<code class="Fl">-q</code>]
1348 [<code class="Fl">-v</code>] [<var class="Ar">remote-repository</var>]</dt>
1349 <dd>
1350 <div class="Bd Bd-indent"><code class="Li">(alias:
1351 <code class="Cm">se</code>)</code></div>
1352 Send new changes to a remote repository. If no
1353 <var class="Ar">remote-repository</var> is specified,
1354 &#x201C;origin&#x201D; will be used. The remote repository's URL is
1355 obtained from the corresponding entry in <a class="Xr">got.conf(5)</a> or
1356 Git's <span class="Pa">config</span> file of the local repository, as
1357 created by <code class="Cm">got clone</code>.
1358 <p class="Pp">All objects corresponding to new changes will be written to a
1359 temporary pack file which is then uploaded to the server. Upon success,
1360 references in the &#x201C;refs/remotes/&#x201D; reference namespace of
1361 the local repository will be updated to point at the commits which have
1362 been sent.</p>
1363 <p class="Pp">By default, changes will only be sent if they are based on
1364 up-to-date copies of relevant branches in the remote repository. If any
1365 changes to be sent are based on out-of-date copies or would otherwise
1366 break linear history of existing branches, new changes must be fetched
1367 from the server with <code class="Cm">got fetch</code> and local
1368 branches must be rebased with <code class="Cm">got rebase</code> before
1369 <code class="Cm">got send</code> can succeed. The
1370 <code class="Fl">-f</code> option can be used to make exceptions to
1371 these requirements.</p>
1372 <p class="Pp">The options for <code class="Cm">got send</code> are as
1373 follows:</p>
1374 <dl class="Bl-tag">
1375 <dt id="a~4"><a class="permalink" href="#a~4"><code class="Fl">-a</code></a></dt>
1376 <dd>Send all branches from the local repository's
1377 &#x201C;refs/heads/&#x201D; reference namespace. The
1378 <code class="Fl">-a</code> option is equivalent to listing all
1379 branches with multiple <code class="Fl">-b</code> options. Cannot be
1380 used together with the <code class="Fl">-b</code> option.</dd>
1381 <dt id="b~7"><a class="permalink" href="#b~7"><code class="Fl">-b</code></a>
1382 <var class="Ar">branch</var></dt>
1383 <dd>Send the specified <var class="Ar">branch</var> from the local
1384 repository's &#x201C;refs/heads/&#x201D; reference namespace. This
1385 option may be specified multiple times to build a list of branches to
1386 send. If this option is not specified, default to the work tree's
1387 current branch if invoked in a work tree, or to the repository's HEAD
1388 reference. Cannot be used together with the <code class="Fl">-a</code>
1389 option.</dd>
1390 <dt id="d~4"><a class="permalink" href="#d~4"><code class="Fl">-d</code></a>
1391 <var class="Ar">branch</var></dt>
1392 <dd>Delete the specified <var class="Ar">branch</var> from the remote
1393 repository's &#x201C;refs/heads/&#x201D; reference namespace. This
1394 option may be specified multiple times to build a list of branches to
1395 delete.
1396 <p class="Pp">Only references are deleted. Any commit, tree, tag, and
1397 blob objects belonging to deleted branches may become subject to
1398 deletion by Git's garbage collector running on the server.</p>
1399 <p class="Pp">Requesting deletion of branches results in an error if the
1400 server does not support this feature or disallows the deletion of
1401 branches based on its configuration.</p>
1402 </dd>
1403 <dt id="f~2"><a class="permalink" href="#f~2"><code class="Fl">-f</code></a></dt>
1404 <dd>Attempt to force the server to overwrite existing branches or tags in
1405 the remote repository, even when <code class="Cm">got fetch</code> and
1406 <code class="Cm">got rebase</code> would usually be required before
1407 changes can be sent. The server may reject forced requests regardless,
1408 depending on its configuration.
1409 <p class="Pp">Any commit, tree, tag, and blob objects belonging to
1410 overwritten branches or tags may become subject to deletion by Git's
1411 garbage collector running on the server.</p>
1412 <p class="Pp">The &#x201C;refs/tags&#x201D; reference namespace is
1413 globally shared between all repositories. Use of the
1414 <code class="Fl">-f</code> option to overwrite tags is discouraged
1415 because it can lead to inconsistencies between the tags present in
1416 different repositories. In general, creating a new tag with a
1417 different name is recommended instead of overwriting an existing
1418 tag.</p>
1419 <p class="Pp">Use of the <code class="Fl">-f</code> option is
1420 particularly discouraged if changes being sent are based on an
1421 out-of-date copy of a branch in the remote repository. Instead of
1422 using the <code class="Fl">-f</code> option, new changes should be
1423 fetched with <code class="Cm">got fetch</code> and local branches
1424 should be rebased with <code class="Cm">got rebase</code>, followed
1425 by another attempt to send the changes.</p>
1426 <p class="Pp">The <code class="Fl">-f</code> option should only be
1427 needed in situations where the remote repository's copy of a branch
1428 or tag is known to be out-of-date and is considered disposable. The
1429 risks of creating inconsistencies between different repositories
1430 should also be taken into account.</p>
1431 </dd>
1432 <dt id="r~10"><a class="permalink" href="#r~10"><code class="Fl">-r</code></a>
1433 <var class="Ar">repository-path</var></dt>
1434 <dd>Use the repository at the specified path. If not specified, assume the
1435 repository is located at or above the current working directory. If
1436 this directory is a <code class="Nm">got</code> work tree, use the
1437 repository path associated with this work tree.</dd>
1438 <dt id="t~4"><a class="permalink" href="#t~4"><code class="Fl">-t</code></a>
1439 <var class="Ar">tag</var></dt>
1440 <dd>Send the specified <var class="Ar">tag</var> from the local
1441 repository's &#x201C;refs/tags/&#x201D; reference namespace, in
1442 addition to any branches that are being sent. The
1443 <code class="Fl">-t</code> option may be specified multiple times to
1444 build a list of tags to send. No tags will be sent if the
1445 <code class="Fl">-t</code> option is not used.
1446 <p class="Pp">Raise an error if the specified <var class="Ar">tag</var>
1447 already exists in the remote repository, unless the
1448 <code class="Fl">-f</code> option is used to overwrite the server's
1449 copy of the tag. In general, creating a new tag with a different
1450 name is recommended instead of overwriting an existing tag.</p>
1451 <p class="Pp">Cannot be used together with the
1452 <code class="Fl">-T</code> option.</p>
1453 </dd>
1454 <dt id="T"><a class="permalink" href="#T"><code class="Fl">-T</code></a></dt>
1455 <dd>Attempt to send all tags from the local repository's
1456 &#x201C;refs/tags/&#x201D; reference namespace. The
1457 <code class="Fl">-T</code> option is equivalent to listing all tags
1458 with multiple <code class="Fl">-t</code> options. Cannot be used
1459 together with the <code class="Fl">-t</code> option.</dd>
1460 <dt id="q~5"><a class="permalink" href="#q~5"><code class="Fl">-q</code></a></dt>
1461 <dd>Suppress progress reporting output. The same option will be passed to
1462 <a class="Xr">ssh(1)</a> if applicable.</dd>
1463 <dt id="v~3"><a class="permalink" href="#v~3"><code class="Fl">-v</code></a></dt>
1464 <dd>Verbose mode. Causes <code class="Cm">got send</code> to print
1465 debugging messages to standard error output. The same option will be
1466 passed to <a class="Xr">ssh(1)</a> if applicable. Multiple -v options
1467 increase the verbosity. The maximum is 3.</dd>
1468 </dl>
1469 </dd>
1470 <dt id="cy"><a class="permalink" href="#cherrypick"><code class="Cm" id="cherrypick">cherrypick</code></a>
1471 <var class="Ar">commit</var></dt>
1472 <dd>
1473 <div class="Bd Bd-indent"><code class="Li">(alias:
1474 <code class="Cm">cy</code>)</code></div>
1475 Merge changes from a single <var class="Ar">commit</var> into the work tree.
1476 The specified <var class="Ar">commit</var> should be on a different branch
1477 than the work tree's base commit. The expected argument is a reference or
1478 a commit ID SHA1 hash. An abbreviated hash argument will be expanded to a
1479 full SHA1 hash automatically, provided the abbreviation is unique.
1480 <p class="Pp">Show the status of each affected file, using the following
1481 status codes:</p>
1482 <table class="Bl-column">
1483 <tr>
1484 <td>G</td>
1485 <td>file was merged</td>
1486 </tr>
1487 <tr>
1488 <td>C</td>
1489 <td>file was merged and conflicts occurred during merge</td>
1490 </tr>
1491 <tr>
1492 <td>!</td>
1493 <td>changes destined for a missing file were not merged</td>
1494 </tr>
1495 <tr>
1496 <td>D</td>
1497 <td>file was deleted</td>
1498 </tr>
1499 <tr>
1500 <td>d</td>
1501 <td>file's deletion was prevented by local modifications</td>
1502 </tr>
1503 <tr>
1504 <td>A</td>
1505 <td>new file was added</td>
1506 </tr>
1507 <tr>
1508 <td>~</td>
1509 <td>changes destined for a non-regular file were not merged</td>
1510 </tr>
1511 <tr>
1512 <td>?</td>
1513 <td>changes destined for an unversioned file were not merged</td>
1514 </tr>
1515 </table>
1516 <p class="Pp">The merged changes will appear as local changes in the work
1517 tree, which may be viewed with <code class="Cm">got diff</code>, amended
1518 manually or with further <code class="Cm">got cherrypick</code>
1519 commands, committed with <code class="Cm">got commit</code>, or
1520 discarded again with <code class="Cm">got revert</code>.</p>
1521 <p class="Pp"><code class="Cm">got cherrypick</code> will refuse to run if
1522 certain preconditions are not met. If the work tree contains multiple
1523 base commits it must first be updated to a single base commit with
1524 <code class="Cm">got update</code>. If any relevant files already
1525 contain merge conflicts, these conflicts must be resolved first.</p>
1526 </dd>
1527 <dt id="bo"><a class="permalink" href="#backout"><code class="Cm" id="backout">backout</code></a>
1528 <var class="Ar">commit</var></dt>
1529 <dd>
1530 <div class="Bd Bd-indent"><code class="Li">(alias:
1531 <code class="Cm">bo</code>)</code></div>
1532 Reverse-merge changes from a single <var class="Ar">commit</var> into the
1533 work tree. The specified <var class="Ar">commit</var> should be on the
1534 same branch as the work tree's base commit. The expected argument is a
1535 reference or a commit ID SHA1 hash. An abbreviated hash argument will be
1536 expanded to a full SHA1 hash automatically, provided the abbreviation is
1537 unique.
1538 <p class="Pp">Show the status of each affected file, using the following
1539 status codes:</p>
1540 <table class="Bl-column">
1541 <tr>
1542 <td>G</td>
1543 <td>file was merged</td>
1544 </tr>
1545 <tr>
1546 <td>C</td>
1547 <td>file was merged and conflicts occurred during merge</td>
1548 </tr>
1549 <tr>
1550 <td>!</td>
1551 <td>changes destined for a missing file were not merged</td>
1552 </tr>
1553 <tr>
1554 <td>D</td>
1555 <td>file was deleted</td>
1556 </tr>
1557 <tr>
1558 <td>d</td>
1559 <td>file's deletion was prevented by local modifications</td>
1560 </tr>
1561 <tr>
1562 <td>A</td>
1563 <td>new file was added</td>
1564 </tr>
1565 <tr>
1566 <td>~</td>
1567 <td>changes destined for a non-regular file were not merged</td>
1568 </tr>
1569 <tr>
1570 <td>?</td>
1571 <td>changes destined for an unversioned file were not merged</td>
1572 </tr>
1573 </table>
1574 <p class="Pp">The reverse-merged changes will appear as local changes in the
1575 work tree, which may be viewed with <code class="Cm">got diff</code>,
1576 amended manually or with further <code class="Cm">got backout</code>
1577 commands, committed with <code class="Cm">got commit</code>, or
1578 discarded again with <code class="Cm">got revert</code>.</p>
1579 <p class="Pp"><code class="Cm">got backout</code> will refuse to run if
1580 certain preconditions are not met. If the work tree contains multiple
1581 base commits it must first be updated to a single base commit with
1582 <code class="Cm">got update</code>. If any relevant files already
1583 contain merge conflicts, these conflicts must be resolved first.</p>
1584 </dd>
1585 <dt id="rb"><a class="permalink" href="#rebase"><code class="Cm" id="rebase">rebase</code></a>
1586 [<code class="Fl">-a</code>] [<code class="Fl">-c</code>]
1587 [<code class="Fl">-l</code>] [<code class="Fl">-X</code>]
1588 [<var class="Ar">branch</var>]</dt>
1589 <dd>
1590 <div class="Bd Bd-indent"><code class="Li">(alias:
1591 <code class="Cm">rb</code>)</code></div>
1592 Rebase commits on the specified <var class="Ar">branch</var> onto the tip of
1593 the current branch of the work tree. The <var class="Ar">branch</var> must
1594 share common ancestry with the work tree's current branch. Rebasing begins
1595 with the first descendant commit of the youngest common ancestor commit
1596 shared by the specified <var class="Ar">branch</var> and the work tree's
1597 current branch, and stops once the tip commit of the specified
1598 <var class="Ar">branch</var> has been rebased.
1599 <p class="Pp">When <code class="Cm">got rebase</code> is used as intended,
1600 the specified <var class="Ar">branch</var> represents a local commit
1601 history and may already contain changes that are not yet visible in any
1602 other repositories. The work tree's current branch, which must be set
1603 with <code class="Cm">got update -b</code> before starting the
1604 <code class="Cm">rebase</code> operation, represents a branch from a
1605 remote repository which shares a common history with the specified
1606 <var class="Ar">branch</var> but has progressed, and perhaps diverged,
1607 due to commits added to the remote repository.</p>
1608 <p class="Pp">Rebased commits are accumulated on a temporary branch which
1609 the work tree will remain switched to throughout the entire rebase
1610 operation. Commits on this branch represent the same changes with the
1611 same log messages as their counterparts on the original
1612 <var class="Ar">branch</var>, but with different commit IDs. Once
1613 rebasing has completed successfully, the temporary branch becomes the
1614 new version of the specified <var class="Ar">branch</var> and the work
1615 tree is automatically switched to it.</p>
1616 <p class="Pp">Old commits in their pre-rebase state are automatically backed
1617 up in the &#x201C;refs/got/backup/rebase&#x201D; reference namespace. As
1618 long as these references are not removed older versions of rebased
1619 commits will remain in the repository and can be viewed with the
1620 <code class="Cm">got rebase -l</code> command. Removal of these
1621 references makes objects which become unreachable via any reference
1622 subject to removal by Git's garbage collector or
1623 <code class="Cm">gotadmin cleanup</code>.</p>
1624 <p class="Pp">While rebasing commits, show the status of each affected file,
1625 using the following status codes:</p>
1626 <table class="Bl-column">
1627 <tr>
1628 <td>G</td>
1629 <td>file was merged</td>
1630 </tr>
1631 <tr>
1632 <td>C</td>
1633 <td>file was merged and conflicts occurred during merge</td>
1634 </tr>
1635 <tr>
1636 <td>!</td>
1637 <td>changes destined for a missing file were not merged</td>
1638 </tr>
1639 <tr>
1640 <td>D</td>
1641 <td>file was deleted</td>
1642 </tr>
1643 <tr>
1644 <td>d</td>
1645 <td>file's deletion was prevented by local modifications</td>
1646 </tr>
1647 <tr>
1648 <td>A</td>
1649 <td>new file was added</td>
1650 </tr>
1651 <tr>
1652 <td>~</td>
1653 <td>changes destined for a non-regular file were not merged</td>
1654 </tr>
1655 <tr>
1656 <td>?</td>
1657 <td>changes destined for an unversioned file were not merged</td>
1658 </tr>
1659 </table>
1660 <p class="Pp">If merge conflicts occur the rebase operation is interrupted
1661 and may be continued once conflicts have been resolved. If any files
1662 with destined changes are found to be missing or unversioned, or if
1663 files could not be deleted due to differences in deleted content, the
1664 rebase operation will be interrupted to prevent potentially incomplete
1665 changes from being committed to the repository without user
1666 intervention. The work tree may be modified as desired and the rebase
1667 operation can be continued once the changes present in the work tree are
1668 considered complete. Alternatively, the rebase operation may be aborted
1669 which will leave <var class="Ar">branch</var> unmodified and the work
1670 tree switched back to its original branch.</p>
1671 <p class="Pp">If a merge conflict is resolved in a way which renders the
1672 merged change into a no-op change, the corresponding commit will be
1673 elided when the rebase operation continues.</p>
1674 <p class="Pp"><code class="Cm">got rebase</code> will refuse to run if
1675 certain preconditions are not met. If the work tree is not yet fully
1676 updated to the tip commit of its branch then the work tree must first be
1677 updated with <code class="Cm">got update</code>. If changes have been
1678 staged with <code class="Cm">got stage</code>, these changes must first
1679 be committed with <code class="Cm">got commit</code> or unstaged with
1680 <code class="Cm">got unstage</code>. If the work tree contains local
1681 changes, these changes must first be committed with <code class="Cm">got
1682 commit</code> or reverted with <code class="Cm">got revert</code>. If
1683 the <var class="Ar">branch</var> contains changes to files outside of
1684 the work tree's path prefix, the work tree cannot be used to rebase this
1685 branch.</p>
1686 <p class="Pp">The <code class="Cm">got update</code> and
1687 <code class="Cm">got commit</code> commands will refuse to run while a
1688 rebase operation is in progress. Other commands which manipulate the
1689 work tree may be used for conflict resolution purposes.</p>
1690 <p class="Pp">If the specified <var class="Ar">branch</var> is already based
1691 on the work tree's current branch then no commits need to be rebased and
1692 <code class="Cm">got rebase</code> will simply switch the work tree to
1693 the specified <var class="Ar">branch</var> and update files in the work
1694 tree accordingly.</p>
1695 <p class="Pp">The options for <code class="Cm">got rebase</code> are as
1696 follows:</p>
1697 <dl class="Bl-tag">
1698 <dt id="a~5"><a class="permalink" href="#a~5"><code class="Fl">-a</code></a></dt>
1699 <dd>Abort an interrupted rebase operation. If this option is used, no
1700 other command-line arguments are allowed.</dd>
1701 <dt id="c~10"><a class="permalink" href="#c~10"><code class="Fl">-c</code></a></dt>
1702 <dd>Continue an interrupted rebase operation. If this option is used, no
1703 other command-line arguments are allowed.</dd>
1704 <dt id="l~7"><a class="permalink" href="#l~7"><code class="Fl">-l</code></a></dt>
1705 <dd>Show a list of past rebase operations, represented by references in
1706 the &#x201C;refs/got/backup/rebase&#x201D; reference namespace.
1707 <p class="Pp">Display the author, date, and log message of each backed
1708 up commit, the object ID of the corresponding post-rebase commit,
1709 and the object ID of their common ancestor commit. Given these
1710 object IDs, the <code class="Cm">got log</code> command with the
1711 <code class="Fl">-c</code> and <code class="Fl">-x</code> options
1712 can be used to examine the history of either version of the branch,
1713 and the <code class="Cm">got branch</code> command with the
1714 <code class="Fl">-c</code> option can be used to create a new branch
1715 from a pre-rebase state if desired.</p>
1716 <p class="Pp">If a <var class="Ar">branch</var> is specified, only show
1717 commits which at some point in time represented this branch.
1718 Otherwise, list all backed up commits for any branches.</p>
1719 <p class="Pp">If this option is used, <code class="Cm">got rebase</code>
1720 does not require a work tree. None of the other options can be used
1721 together with <code class="Fl">-l</code>.</p>
1722 </dd>
1723 <dt id="X~2"><a class="permalink" href="#X~2"><code class="Fl">-X</code></a></dt>
1724 <dd>Delete backups created by past rebase operations, represented by
1725 references in the &#x201C;refs/got/backup/rebase&#x201D; reference
1726 namespace.
1727 <p class="Pp">If a <var class="Ar">branch</var> is specified, only
1728 delete backups which at some point in time represented this branch.
1729 Otherwise, delete all references found within
1730 &#x201C;refs/got/backup/rebase&#x201D;.</p>
1731 <p class="Pp">Any commit, tree, tag, and blob objects belonging to
1732 deleted backups remain in the repository and may be removed
1733 separately with Git's garbage collector or <code class="Cm">gotadmin
1734 cleanup</code>.</p>
1735 <p class="Pp">If this option is used, <code class="Cm">got rebase</code>
1736 does not require a work tree. None of the other options can be used
1737 together with <code class="Fl">-X</code>.</p>
1738 </dd>
1739 </dl>
1740 </dd>
1741 <dt id="he"><a class="permalink" href="#histedit"><code class="Cm" id="histedit">histedit</code></a>
1742 [<code class="Fl">-a</code>] [<code class="Fl">-c</code>]
1743 [<code class="Fl">-e</code>] [<code class="Fl">-f</code>]
1744 [<code class="Fl">-F</code> <var class="Ar">histedit-script</var>]
1745 [<code class="Fl">-m</code>] [<code class="Fl">-l</code>]
1746 [<code class="Fl">-X</code>] [<var class="Ar">branch</var>]</dt>
1747 <dd>
1748 <div class="Bd Bd-indent"><code class="Li">(alias:
1749 <code class="Cm">he</code>)</code></div>
1750 Edit commit history between the work tree's current base commit and the tip
1751 commit of the work tree's current branch.
1752 <p class="Pp">Before starting a <code class="Cm">histedit</code> operation
1753 the work tree's current branch must be set with <code class="Cm">got
1754 update -b</code> to the branch which should be edited, unless this
1755 branch is already the current branch of the work tree. The tip of this
1756 branch represents the upper bound (inclusive) of commits touched by the
1757 <code class="Cm">histedit</code> operation.</p>
1758 <p class="Pp">Furthermore, the work tree's base commit must be set with
1759 <code class="Cm">got update -c</code> to a point in this branch's commit
1760 history where editing should begin. This commit represents the lower
1761 bound (non-inclusive) of commits touched by the
1762 <code class="Cm">histedit</code> operation.</p>
1763 <p class="Pp">Editing of commit history is controlled via a
1764 <var class="Ar">histedit script</var> which can be written in an editor
1765 based on a template, passed on the command line, or generated with the
1766 <code class="Fl">-f</code> or <code class="Fl">-m</code> options.</p>
1767 <p class="Pp">The format of the histedit script is line-based. Each line in
1768 the script begins with a command name, followed by whitespace and an
1769 argument. For most commands, the expected argument is a commit ID SHA1
1770 hash. Any remaining text on the line is ignored. Lines which begin with
1771 the &#x2018;#&#x2019; character are ignored entirely.</p>
1772 <p class="Pp">The available commands are as follows:</p>
1773 <table class="Bl-column">
1774 <tr>
1775 <td>pick <var class="Ar">commit</var></td>
1776 <td>Use the specified commit as it is.</td>
1777 </tr>
1778 <tr>
1779 <td>edit <var class="Ar">commit</var></td>
1780 <td>Use the specified commit but once changes have been merged into the
1781 work tree interrupt the histedit operation for amending.</td>
1782 </tr>
1783 <tr>
1784 <td>fold <var class="Ar">commit</var></td>
1785 <td>Combine the specified commit with the next commit listed further
1786 below that will be used.</td>
1787 </tr>
1788 <tr>
1789 <td>drop <var class="Ar">commit</var></td>
1790 <td>Remove this commit from the edited history.</td>
1791 </tr>
1792 <tr>
1793 <td>mesg <var class="Ar">log-message</var></td>
1794 <td>Use the specified single-line log message for the commit on the
1795 previous line. If the log message argument is left empty, open an
1796 editor where a new log message can be written.</td>
1797 </tr>
1798 </table>
1799 <p class="Pp">Every commit in the history being edited must be mentioned in
1800 the script. Lines may be re-ordered to change the order of commits in
1801 the edited history. No commit may be listed more than once.</p>
1802 <p class="Pp">Edited commits are accumulated on a temporary branch which the
1803 work tree will remain switched to throughout the entire histedit
1804 operation. Once history editing has completed successfully, the
1805 temporary branch becomes the new version of the work tree's branch and
1806 the work tree is automatically switched to it.</p>
1807 <p class="Pp">Old commits in their pre-histedit state are automatically
1808 backed up in the &#x201C;refs/got/backup/histedit&#x201D; reference
1809 namespace. As long as these references are not removed older versions of
1810 edited commits will remain in the repository and can be viewed with the
1811 <code class="Cm">got histedit -l</code> command. Removal of these
1812 references makes objects which become unreachable via any reference
1813 subject to removal by Git's garbage collector or
1814 <code class="Cm">gotadmin cleanup</code>.</p>
1815 <p class="Pp">While merging commits, show the status of each affected file,
1816 using the following status codes:</p>
1817 <table class="Bl-column">
1818 <tr>
1819 <td>G</td>
1820 <td>file was merged</td>
1821 </tr>
1822 <tr>
1823 <td>C</td>
1824 <td>file was merged and conflicts occurred during merge</td>
1825 </tr>
1826 <tr>
1827 <td>!</td>
1828 <td>changes destined for a missing file were not merged</td>
1829 </tr>
1830 <tr>
1831 <td>D</td>
1832 <td>file was deleted</td>
1833 </tr>
1834 <tr>
1835 <td>d</td>
1836 <td>file's deletion was prevented by local modifications</td>
1837 </tr>
1838 <tr>
1839 <td>A</td>
1840 <td>new file was added</td>
1841 </tr>
1842 <tr>
1843 <td>~</td>
1844 <td>changes destined for a non-regular file were not merged</td>
1845 </tr>
1846 <tr>
1847 <td>?</td>
1848 <td>changes destined for an unversioned file were not merged</td>
1849 </tr>
1850 </table>
1851 <p class="Pp">If merge conflicts occur the histedit operation is interrupted
1852 and may be continued once conflicts have been resolved. If any files
1853 with destined changes are found to be missing or unversioned, or if
1854 files could not be deleted due to differences in deleted content, the
1855 histedit operation will be interrupted to prevent potentially incomplete
1856 changes from being committed to the repository without user
1857 intervention. The work tree may be modified as desired and the histedit
1858 operation can be continued once the changes present in the work tree are
1859 considered complete. Alternatively, the histedit operation may be
1860 aborted which will leave the work tree switched back to its original
1861 branch.</p>
1862 <p class="Pp">If a merge conflict is resolved in a way which renders the
1863 merged change into a no-op change, the corresponding commit will be
1864 elided when the histedit operation continues.</p>
1865 <p class="Pp"><code class="Cm">got histedit</code> will refuse to run if
1866 certain preconditions are not met. If the work tree's current branch is
1867 not in the &#x201C;refs/heads/&#x201D; reference namespace, the history
1868 of the branch may not be edited. If the work tree contains multiple base
1869 commits it must first be updated to a single base commit with
1870 <code class="Cm">got update</code>. If changes have been staged with
1871 <code class="Cm">got stage</code>, these changes must first be committed
1872 with <code class="Cm">got commit</code> or unstaged with
1873 <code class="Cm">got unstage</code>. If the work tree contains local
1874 changes, these changes must first be committed with <code class="Cm">got
1875 commit</code> or reverted with <code class="Cm">got revert</code>. If
1876 the edited history contains changes to files outside of the work tree's
1877 path prefix, the work tree cannot be used to edit the history of this
1878 branch.</p>
1879 <p class="Pp">The <code class="Cm">got update</code>, <code class="Cm">got
1880 rebase</code>, and <code class="Cm">got integrate</code> commands will
1881 refuse to run while a histedit operation is in progress. Other commands
1882 which manipulate the work tree may be used, and the <code class="Cm">got
1883 commit</code> command may be used to commit arbitrary changes to the
1884 temporary branch while the histedit operation is interrupted.</p>
1885 <p class="Pp">The options for <code class="Cm">got histedit</code> are as
1886 follows:</p>
1887 <dl class="Bl-tag">
1888 <dt id="a~6"><a class="permalink" href="#a~6"><code class="Fl">-a</code></a></dt>
1889 <dd>Abort an interrupted histedit operation. If this option is used, no
1890 other command-line arguments are allowed.</dd>
1891 <dt id="c~11"><a class="permalink" href="#c~11"><code class="Fl">-c</code></a></dt>
1892 <dd>Continue an interrupted histedit operation. If this option is used, no
1893 other command-line arguments are allowed.</dd>
1894 <dt id="e"><a class="permalink" href="#e"><code class="Fl">-e</code></a></dt>
1895 <dd>Interrupt the histedit operation for editing after merging each
1896 commit. This option is a quick equivalent to a histedit script which
1897 uses the <code class="Cm">edit</code> command for all commits. The
1898 <code class="Fl">-e</code> option can only be used when starting a new
1899 histedit operation. If this option is used, no other command-line
1900 arguments are allowed.</dd>
1901 <dt id="f~3"><a class="permalink" href="#f~3"><code class="Fl">-f</code></a></dt>
1902 <dd>Fold all commits into a single commit. This option is a quick
1903 equivalent to a histedit script which folds all commits, combining
1904 them all into one commit. The <code class="Fl">-f</code> option can
1905 only be used when starting a new histedit operation. If this option is
1906 used, no other command-line arguments are allowed.</dd>
1907 <dt id="F~3"><a class="permalink" href="#F~3"><code class="Fl">-F</code></a>
1908 <var class="Ar">histedit-script</var></dt>
1909 <dd>Use the specified <var class="Ar">histedit-script</var> instead of
1910 opening a temporary file in an editor where a histedit script can be
1911 written.</dd>
1912 <dt id="m~5"><a class="permalink" href="#m~5"><code class="Fl">-m</code></a></dt>
1913 <dd>Edit log messages only. This option is a quick equivalent to a
1914 histedit script which edits only log messages but otherwise leaves
1915 every picked commit as-is. The <code class="Fl">-m</code> option can
1916 only be used when starting a new histedit operation. If this option is
1917 used, no other command-line arguments are allowed.</dd>
1918 <dt id="l~8"><a class="permalink" href="#l~8"><code class="Fl">-l</code></a></dt>
1919 <dd>Show a list of past histedit operations, represented by references in
1920 the &#x201C;refs/got/backup/histedit&#x201D; reference namespace.
1921 <p class="Pp">Display the author, date, and log message of each backed
1922 up commit, the object ID of the corresponding post-histedit commit,
1923 and the object ID of their common ancestor commit. Given these
1924 object IDs, the <code class="Cm">got log</code> command with the
1925 <code class="Fl">-c</code> and <code class="Fl">-x</code> options
1926 can be used to examine the history of either version of the branch,
1927 and the <code class="Cm">got branch</code> command with the
1928 <code class="Fl">-c</code> option can be used to create a new branch
1929 from a pre-histedit state if desired.</p>
1930 <p class="Pp">If a <var class="Ar">branch</var> is specified, only show
1931 commits which at some point in time represented this branch.
1932 Otherwise, list all backed up commits for any branches.</p>
1933 <p class="Pp">If this option is used, <code class="Cm">got
1934 histedit</code> does not require a work tree. None of the other
1935 options can be used together with <code class="Fl">-l</code>.</p>
1936 </dd>
1937 <dt id="X~3"><a class="permalink" href="#X~3"><code class="Fl">-X</code></a></dt>
1938 <dd>Delete backups created by past histedit operations, represented by
1939 references in the &#x201C;refs/got/backup/histedit&#x201D; reference
1940 namespace.
1941 <p class="Pp">If a <var class="Ar">branch</var> is specified, only
1942 delete backups which at some point in time represented this branch.
1943 Otherwise, delete all references found within
1944 &#x201C;refs/got/backup/histedit&#x201D;.</p>
1945 <p class="Pp">Any commit, tree, tag, and blob objects belonging to
1946 deleted backups remain in the repository and may be removed
1947 separately with Git's garbage collector or <code class="Cm">gotadmin
1948 cleanup</code>.</p>
1949 <p class="Pp">If this option is used, <code class="Cm">got
1950 histedit</code> does not require a work tree. None of the other
1951 options can be used together with <code class="Fl">-X</code>.</p>
1952 </dd>
1953 </dl>
1954 </dd>
1955 <dt id="ig"><a class="permalink" href="#integrate"><code class="Cm" id="integrate">integrate</code></a>
1956 <var class="Ar">branch</var></dt>
1957 <dd>
1958 <div class="Bd Bd-indent"><code class="Li">(alias:
1959 <code class="Cm">ig</code>)</code></div>
1960 Integrate the specified <var class="Ar">branch</var> into the work tree's
1961 current branch. Files in the work tree are updated to match the contents
1962 on the integrated <var class="Ar">branch</var>, and the reference of the
1963 work tree's branch is changed to point at the head commit of the
1964 integrated <var class="Ar">branch</var>.
1965 <p class="Pp">Both branches can be considered equivalent after integration
1966 since they will be pointing at the same commit. Both branches remain
1967 available for future work, if desired. In case the integrated
1968 <var class="Ar">branch</var> is no longer needed it may be deleted with
1969 <code class="Cm">got branch -d</code>.</p>
1970 <p class="Pp">Show the status of each affected file, using the following
1971 status codes:</p>
1972 <table class="Bl-column">
1973 <tr>
1974 <td>U</td>
1975 <td>file was updated</td>
1976 </tr>
1977 <tr>
1978 <td>D</td>
1979 <td>file was deleted</td>
1980 </tr>
1981 <tr>
1982 <td>A</td>
1983 <td>new file was added</td>
1984 </tr>
1985 <tr>
1986 <td>~</td>
1987 <td>versioned file is obstructed by a non-regular file</td>
1988 </tr>
1989 <tr>
1990 <td>!</td>
1991 <td>a missing versioned file was restored</td>
1992 </tr>
1993 </table>
1994 <p class="Pp"><code class="Cm">got integrate</code> will refuse to run if
1995 certain preconditions are not met. Most importantly, the
1996 <var class="Ar">branch</var> must have been rebased onto the work tree's
1997 current branch with <code class="Cm">got rebase</code> before it can be
1998 integrated, in order to linearize commit history and resolve merge
1999 conflicts. If the work tree contains multiple base commits it must first
2000 be updated to a single base commit with <code class="Cm">got
2001 update</code>. If changes have been staged with <code class="Cm">got
2002 stage</code>, these changes must first be committed with
2003 <code class="Cm">got commit</code> or unstaged with <code class="Cm">got
2004 unstage</code>. If the work tree contains local changes, these changes
2005 must first be committed with <code class="Cm">got commit</code> or
2006 reverted with <code class="Cm">got revert</code>.</p>
2007 </dd>
2008 <dt id="mg"><a class="permalink" href="#merge"><code class="Cm" id="merge">merge</code></a>
2009 [<code class="Fl">-a</code>] [<code class="Fl">-c</code>]
2010 [<code class="Fl">-n</code>] [<var class="Ar">branch</var>]</dt>
2011 <dd>
2012 <div class="Bd Bd-indent"><code class="Li">(alias:
2013 <code class="Cm">mg</code>)</code></div>
2014 Create a merge commit based on the current branch of the work tree and the
2015 specified <var class="Ar">branch</var>. If a linear project history is
2016 desired, then use of <code class="Cm">got rebase</code> should be
2017 preferred over <code class="Cm">got merge</code>. However, even strictly
2018 linear projects may require merge commits in order to merge in new
2019 versions of third-party code stored on vendor branches created with
2020 <code class="Cm">got import</code>.
2021 <p class="Pp">Merge commits are commits based on multiple parent commits.
2022 The tip commit of the work tree's current branch, which must be set with
2023 <code class="Cm">got update -b</code> before starting the
2024 <code class="Cm">merge</code> operation, will be used as the first
2025 parent. The tip commit of the specified <var class="Ar">branch</var>
2026 will be used as the second parent.</p>
2027 <p class="Pp">No ancestral relationship between the two branches is
2028 required. If the two branches have already been merged previously, only
2029 new changes will be merged.</p>
2030 <p class="Pp">It is not possible to create merge commits with more than two
2031 parents. If more than one branch needs to be merged, then multiple merge
2032 commits with two parents each can be created in sequence.</p>
2033 <p class="Pp">While merging changes found on the
2034 <var class="Ar">branch</var> into the work tree, show the status of each
2035 affected file, using the following status codes:</p>
2036 <table class="Bl-column">
2037 <tr>
2038 <td>G</td>
2039 <td>file was merged</td>
2040 </tr>
2041 <tr>
2042 <td>C</td>
2043 <td>file was merged and conflicts occurred during merge</td>
2044 </tr>
2045 <tr>
2046 <td>!</td>
2047 <td>changes destined for a missing file were not merged</td>
2048 </tr>
2049 <tr>
2050 <td>D</td>
2051 <td>file was deleted</td>
2052 </tr>
2053 <tr>
2054 <td>d</td>
2055 <td>file's deletion was prevented by local modifications</td>
2056 </tr>
2057 <tr>
2058 <td>A</td>
2059 <td>new file was added</td>
2060 </tr>
2061 <tr>
2062 <td>~</td>
2063 <td>changes destined for a non-regular file were not merged</td>
2064 </tr>
2065 <tr>
2066 <td>?</td>
2067 <td>changes destined for an unversioned file were not merged</td>
2068 </tr>
2069 </table>
2070 <p class="Pp">If merge conflicts occur, the merge operation is interrupted
2071 and conflicts must be resolved before the merge operation can continue.
2072 If any files with destined changes are found to be missing or
2073 unversioned, or if files could not be deleted due to differences in
2074 deleted content, the merge operation will be interrupted to prevent
2075 potentially incomplete changes from being committed to the repository
2076 without user intervention. The work tree may be modified as desired and
2077 the merge can be continued once the changes present in the work tree are
2078 considered complete. Alternatively, the merge operation may be aborted
2079 which will leave the work tree's current branch unmodified.</p>
2080 <p class="Pp">If a merge conflict is resolved in a way which renders all
2081 merged changes into no-op changes, the merge operation cannot continue
2082 and must be aborted.</p>
2083 <p class="Pp"><code class="Cm">got merge</code> will refuse to run if
2084 certain preconditions are not met. If history of the
2085 <var class="Ar">branch</var> is based on the work tree's current branch,
2086 then no merge commit can be created and <code class="Cm">got
2087 integrate</code> may be used to integrate the
2088 <var class="Ar">branch</var> instead. If the work tree is not yet fully
2089 updated to the tip commit of its branch, then the work tree must first
2090 be updated with <code class="Cm">got update</code>. If the work tree
2091 contains multiple base commits it must first be updated to a single base
2092 commit with <code class="Cm">got update</code>. If changes have been
2093 staged with <code class="Cm">got stage</code>, these changes must first
2094 be committed with <code class="Cm">got commit</code> or unstaged with
2095 <code class="Cm">got unstage</code>. If the work tree contains local
2096 changes, these changes must first be committed with <code class="Cm">got
2097 commit</code> or reverted with <code class="Cm">got revert</code>. If
2098 the <var class="Ar">branch</var> contains changes to files outside of
2099 the work tree's path prefix, the work tree cannot be used to merge this
2100 branch.</p>
2101 <p class="Pp">The <code class="Cm">got update</code>, <code class="Cm">got
2102 commit</code>, <code class="Cm">got rebase</code>, <code class="Cm">got
2103 histedit</code>, <code class="Cm">got integrate</code>, and
2104 <code class="Cm">got stage</code> commands will refuse to run while a
2105 merge operation is in progress. Other commands which manipulate the work
2106 tree may be used for conflict resolution purposes.</p>
2107 <p class="Pp">The options for <code class="Cm">got merge</code> are as
2108 follows:</p>
2109 <dl class="Bl-tag">
2110 <dt id="a~7"><a class="permalink" href="#a~7"><code class="Fl">-a</code></a></dt>
2111 <dd>Abort an interrupted merge operation. If this option is used, no other
2112 command-line arguments are allowed.</dd>
2113 <dt id="c~12"><a class="permalink" href="#c~12"><code class="Fl">-c</code></a></dt>
2114 <dd>Continue an interrupted merge operation. If this option is used, no
2115 other command-line arguments are allowed.</dd>
2116 <dt id="n~2"><a class="permalink" href="#n~2"><code class="Fl">-n</code></a></dt>
2117 <dd>Merge changes into the work tree as usual but do not create a merge
2118 commit immediately. The merge result can be adjusted as desired before
2119 a merge commit is created with <code class="Cm">got merge -c</code>.
2120 Alternatively, the merge may be aborted with <code class="Cm">got
2121 merge -a</code>.</dd>
2122 </dl>
2123 </dd>
2124 <dt id="sg"><a class="permalink" href="#stage"><code class="Cm" id="stage">stage</code></a>
2125 [<code class="Fl">-l</code>] [<code class="Fl">-p</code>]
2126 [<code class="Fl">-F</code> <var class="Ar">response-script</var>]
2127 [<code class="Fl">-S</code>] [<var class="Ar">path ...</var>]</dt>
2128 <dd>
2129 <div class="Bd Bd-indent"><code class="Li">(alias:
2130 <code class="Cm">sg</code>)</code></div>
2131 Stage local changes for inclusion in the next commit. If no
2132 <var class="Ar">path</var> is specified, stage all changes in the work
2133 tree. Otherwise, stage changes at or within the specified paths. Paths may
2134 be staged if they are added, modified, or deleted according to
2135 <code class="Cm">got status</code>.
2136 <p class="Pp">Show the status of each affected file, using the following
2137 status codes:</p>
2138 <table class="Bl-column">
2139 <tr>
2140 <td>A</td>
2141 <td>file addition has been staged</td>
2142 </tr>
2143 <tr>
2144 <td>M</td>
2145 <td>file modification has been staged</td>
2146 </tr>
2147 <tr>
2148 <td>D</td>
2149 <td>file deletion has been staged</td>
2150 </tr>
2151 </table>
2152 <p class="Pp">Staged file contents are saved in newly created blob objects
2153 in the repository. These blobs will be referred to by tree objects once
2154 staged changes have been committed.</p>
2155 <p class="Pp">Staged changes affect the behaviour of <code class="Cm">got
2156 commit</code>, <code class="Cm">got status</code>, and
2157 <code class="Cm">got diff</code>. While paths with staged changes exist,
2158 the <code class="Cm">got commit</code> command will refuse to commit any
2159 paths which do not have staged changes. Local changes created on top of
2160 staged changes can only be committed if the path is staged again, or if
2161 the staged changes are committed first. The <code class="Cm">got
2162 status</code> command will show both local changes and staged changes.
2163 The <code class="Cm">got diff</code> command is able to display local
2164 changes relative to staged changes, and to display staged changes
2165 relative to the repository. The <code class="Cm">got revert</code>
2166 command cannot revert staged changes but may be used to revert local
2167 changes created on top of staged changes.</p>
2168 <p class="Pp">The options for <code class="Cm">got stage</code> are as
2169 follows:</p>
2170 <dl class="Bl-tag">
2171 <dt id="l~9"><a class="permalink" href="#l~9"><code class="Fl">-l</code></a></dt>
2172 <dd>Instead of staging new changes, list paths which are already staged,
2173 along with the IDs of staged blob objects and stage status codes. If
2174 paths were provided in the command line show the staged paths among
2175 the specified paths. Otherwise, show all staged paths.</dd>
2176 <dt id="p~4"><a class="permalink" href="#p~4"><code class="Fl">-p</code></a></dt>
2177 <dd>Instead of staging the entire content of a changed file, interactively
2178 select or reject changes for staging based on &#x201C;y&#x201D; (stage
2179 change), &#x201C;n&#x201D; (reject change), and &#x201C;q&#x201D;
2180 (quit staging this file) responses. If a file is in modified status,
2181 individual patches derived from the modified file content can be
2182 staged. Files in added or deleted status may only be staged or
2183 rejected in their entirety.</dd>
2184 <dt id="F~4"><a class="permalink" href="#F~4"><code class="Fl">-F</code></a>
2185 <var class="Ar">response-script</var></dt>
2186 <dd>With the <code class="Fl">-p</code> option, read &#x201C;y&#x201D;,
2187 &#x201C;n&#x201D;, and &#x201C;q&#x201D; responses line-by-line from
2188 the specified <var class="Ar">response-script</var> file instead of
2189 prompting interactively.</dd>
2190 <dt id="S~3"><a class="permalink" href="#S~3"><code class="Fl">-S</code></a></dt>
2191 <dd>Allow staging of symbolic links which point outside of the path space
2192 that is under version control. By default, <code class="Cm">got
2193 stage</code> will reject such symbolic links due to safety concerns.
2194 As a precaution, <code class="Nm">got</code> may decide to represent
2195 such a symbolic link as a regular file which contains the link's
2196 target path, rather than creating an actual symbolic link which points
2197 outside of the work tree. Use of this option is discouraged because
2198 external mechanisms such as &#x201C;make obj&#x201D; are better suited
2199 for managing symbolic links to paths not under version control.</dd>
2200 </dl>
2201 <p class="Pp"><code class="Cm">got stage</code> will refuse to run if
2202 certain preconditions are not met. If a file contains merge conflicts,
2203 these conflicts must be resolved first. If a file is found to be out of
2204 date relative to the head commit on the work tree's current branch, the
2205 file must be updated with <code class="Cm">got update</code> before it
2206 can be staged (however, this does not prevent the file from becoming
2207 out-of-date at some point after having been staged).</p>
2208 <p class="Pp">The <code class="Cm">got update</code>, <code class="Cm">got
2209 rebase</code>, and <code class="Cm">got histedit</code> commands will
2210 refuse to run while staged changes exist. If staged changes cannot be
2211 committed because a staged path is out of date, the path must be
2212 unstaged with <code class="Cm">got unstage</code> before it can be
2213 updated with <code class="Cm">got update</code>, and may then be staged
2214 again if necessary.</p>
2215 </dd>
2216 <dt id="ug"><a class="permalink" href="#unstage"><code class="Cm" id="unstage">unstage</code></a>
2217 [<code class="Fl">-p</code>] [<code class="Fl">-F</code>
2218 <var class="Ar">response-script</var>] [<var class="Ar">path ...</var>]</dt>
2219 <dd>
2220 <div class="Bd Bd-indent"><code class="Li">(alias:
2221 <code class="Cm">ug</code>)</code></div>
2222 Merge staged changes back into the work tree and put affected paths back
2223 into non-staged status. If no <var class="Ar">path</var> is specified,
2224 unstage all staged changes across the entire work tree. Otherwise, unstage
2225 changes at or within the specified paths.
2226 <p class="Pp">Show the status of each affected file, using the following
2227 status codes:</p>
2228 <table class="Bl-column">
2229 <tr>
2230 <td>G</td>
2231 <td>file was unstaged</td>
2232 </tr>
2233 <tr>
2234 <td>C</td>
2235 <td>file was unstaged and conflicts occurred during merge</td>
2236 </tr>
2237 <tr>
2238 <td>!</td>
2239 <td>changes destined for a missing file were not merged</td>
2240 </tr>
2241 <tr>
2242 <td>D</td>
2243 <td>file was staged as deleted and still is deleted</td>
2244 </tr>
2245 <tr>
2246 <td>d</td>
2247 <td>file's deletion was prevented by local modifications</td>
2248 </tr>
2249 <tr>
2250 <td>~</td>
2251 <td>changes destined for a non-regular file were not merged</td>
2252 </tr>
2253 </table>
2254 <p class="Pp">The options for <code class="Cm">got unstage</code> are as
2255 follows:</p>
2256 <dl class="Bl-tag">
2257 <dt id="p~5"><a class="permalink" href="#p~5"><code class="Fl">-p</code></a></dt>
2258 <dd>Instead of unstaging the entire content of a changed file,
2259 interactively select or reject changes for unstaging based on
2260 &#x201C;y&#x201D; (unstage change), &#x201C;n&#x201D; (keep change
2261 staged), and &#x201C;q&#x201D; (quit unstaging this file) responses.
2262 If a file is staged in modified status, individual patches derived
2263 from the staged file content can be unstaged. Files staged in added or
2264 deleted status may only be unstaged in their entirety.</dd>
2265 <dt id="F~5"><a class="permalink" href="#F~5"><code class="Fl">-F</code></a>
2266 <var class="Ar">response-script</var></dt>
2267 <dd>With the <code class="Fl">-p</code> option, read &#x201C;y&#x201D;,
2268 &#x201C;n&#x201D;, and &#x201C;q&#x201D; responses line-by-line from
2269 the specified <var class="Ar">response-script</var> file instead of
2270 prompting interactively.</dd>
2271 </dl>
2272 </dd>
2273 <dt id="cat"><a class="permalink" href="#cat"><code class="Cm">cat</code></a>
2274 [<code class="Fl">-c</code> <var class="Ar">commit</var>]
2275 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]
2276 [<code class="Fl">-P</code>] <var class="Ar">arg ...</var></dt>
2277 <dd>Parse and print contents of objects to standard output in a line-based
2278 text format. Content of commit, tree, and tag objects is printed in a way
2279 similar to the actual content stored in such objects. Blob object contents
2280 are printed as they would appear in files on disk.
2281 <p class="Pp">Attempt to interpret each argument as a reference, a tag name,
2282 or an object ID SHA1 hash. References will be resolved to an object ID.
2283 Tag names will resolved to a tag object. An abbreviated hash argument
2284 will be expanded to a full SHA1 hash automatically, provided the
2285 abbreviation is unique.</p>
2286 <p class="Pp">If none of the above interpretations produce a valid result,
2287 or if the <code class="Fl">-P</code> option is used, attempt to
2288 interpret the argument as a path which will be resolved to the ID of an
2289 object found at this path in the repository.</p>
2290 <p class="Pp">The options for <code class="Cm">got cat</code> are as
2291 follows:</p>
2292 <dl class="Bl-tag">
2293 <dt id="c~13"><a class="permalink" href="#c~13"><code class="Fl">-c</code></a>
2294 <var class="Ar">commit</var></dt>
2295 <dd>Look up paths in the specified <var class="Ar">commit</var>. If this
2296 option is not used, paths are looked up in the commit resolved via the
2297 repository's HEAD reference. The expected argument is a commit ID SHA1
2298 hash or an existing reference or tag name which will be resolved to a
2299 commit ID. An abbreviated hash argument will be expanded to a full
2300 SHA1 hash automatically, provided the abbreviation is unique.</dd>
2301 <dt id="r~11"><a class="permalink" href="#r~11"><code class="Fl">-r</code></a>
2302 <var class="Ar">repository-path</var></dt>
2303 <dd>Use the repository at the specified path. If not specified, assume the
2304 repository is located at or above the current working directory. If
2305 this directory is a <code class="Nm">got</code> work tree, use the
2306 repository path associated with this work tree.</dd>
2307 <dt id="P~3"><a class="permalink" href="#P~3"><code class="Fl">-P</code></a></dt>
2308 <dd>Interpret all arguments as paths only. This option can be used to
2309 resolve ambiguity in cases where paths look like tag names, reference
2310 names, or object IDs.</dd>
2311 </dl>
2312 </dd>
2313 <dt id="info"><a class="permalink" href="#info"><code class="Cm">info</code></a>
2314 [<var class="Ar">path ...</var>]</dt>
2315 <dd>Display meta-data stored in a work tree. See
2316 <a class="Xr">got-worktree(5)</a> for details.
2317 <p class="Pp">The work tree to use is resolved implicitly by walking upwards
2318 from the current working directory.</p>
2319 <p class="Pp">If one or more <var class="Ar">path</var> arguments are
2320 specified, show additional per-file information for tracked files
2321 located at or within these paths. If a <var class="Ar">path</var>
2322 argument corresponds to the work tree's root directory, display
2323 information for all tracked files.</p>
2324 </dd>
2325 </dl>
2326 </section>
2327 <section class="Sh">
2328 <h1 class="Sh" id="ENVIRONMENT"><a class="permalink" href="#ENVIRONMENT">ENVIRONMENT</a></h1>
2329 <dl class="Bl-tag">
2330 <dt id="GOT_AUTHOR"><a class="permalink" href="#GOT_AUTHOR"><code class="Ev">GOT_AUTHOR</code></a></dt>
2331 <dd>The author's name and email address for <code class="Cm">got commit</code>
2332 and <code class="Cm">got import</code>, for example:
2333 &#x201C;<span class="An">Flan Hacker</span>
2334 &lt;<a class="Mt" href="mailto:flan_hacker@openbsd.org">flan_hacker@openbsd.org</a>&gt;&#x201D;.
2335 Because <a class="Xr">git(1)</a> may fail to parse commits without an
2336 email address in author data, <code class="Nm">got</code> attempts to
2337 reject <code class="Ev">GOT_AUTHOR</code> environment variables with a
2338 missing email address.
2339 <p class="Pp"><code class="Ev">GOT_AUTHOR will be overridden by
2340 configuration settings in</code> <a class="Xr">got.conf(5)</a> or by
2341 Git's <code class="Dv">user.name</code> and
2342 <code class="Dv">user.email</code> configuration settings in the
2343 repository's <span class="Pa">.git/config</span> file. The
2344 <code class="Dv">user.name</code> and <code class="Dv">user.email</code>
2345 configuration settings contained in Git's global
2346 <span class="Pa">~/.gitconfig</span> configuration file will only be
2347 used if neither <a class="Xr">got.conf(5)</a> nor the
2348 <code class="Ev">GOT_AUTHOR</code> environment variable provide author
2349 information.</p>
2350 </dd>
2351 <dt id="VISUAL"><a class="permalink" href="#VISUAL"><code class="Ev">VISUAL</code></a>,
2352 <code class="Ev">EDITOR</code></dt>
2353 <dd>The editor spawned by <code class="Cm">got commit</code>,
2354 <code class="Cm">got histedit</code>, <code class="Cm">got import</code>,
2355 or <code class="Cm">got tag</code>. If not set, the
2356 <a class="Xr">ed(1)</a> text editor will be spawned in order to give
2357 <a class="Xr">ed(1)</a> the attention it deserves.</dd>
2358 <dt id="GOT_LOG_DEFAULT_LIMIT"><a class="permalink" href="#GOT_LOG_DEFAULT_LIMIT"><code class="Ev">GOT_LOG_DEFAULT_LIMIT</code></a></dt>
2359 <dd>The default limit on the number of commits traversed by
2360 <code class="Cm">got log</code>. If set to zero, the limit is unbounded.
2361 This variable will be silently ignored if it is set to a non-numeric
2362 value.</dd>
2363 </dl>
2364 </section>
2365 <section class="Sh">
2366 <h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
2367 <dl class="Bl-tag Bl-compact">
2368 <dt><span class="Pa">got.conf</span></dt>
2369 <dd>Repository-wide configuration settings for <code class="Nm">got</code>. If
2370 present, a <a class="Xr">got.conf(5)</a> configuration file located in the
2371 root directory of a Git repository supersedes any relevant settings in
2372 Git's <span class="Pa">config</span> file.
2373 <p class="Pp"></p>
2374 </dd>
2375 <dt><span class="Pa">.got/got.conf</span></dt>
2376 <dd>Worktree-specific configuration settings for <code class="Nm">got</code>.
2377 If present, a <a class="Xr">got.conf(5)</a> configuration file in the
2378 <span class="Pa">.got</span> meta-data directory of a work tree supersedes
2379 any relevant settings in the repository's <a class="Xr">got.conf(5)</a>
2380 configuration file and Git's <span class="Pa">config</span> file.</dd>
2381 </dl>
2382 </section>
2383 <section class="Sh">
2384 <h1 class="Sh" id="EXIT_STATUS"><a class="permalink" href="#EXIT_STATUS">EXIT
2385 STATUS</a></h1>
2386 <p class="Pp">The <code class="Nm">got</code> utility exits&#x00A0;0 on success,
2387 and&#x00A0;&gt;0 if an error occurs.</p>
2388 </section>
2389 <section class="Sh">
2390 <h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
2391 <p class="Pp">Enable tab-completion of <code class="Nm">got</code> command names
2392 in <a class="Xr">ksh(1)</a>:</p>
2393 <p class="Pp"></p>
2394 <div class="Bd Bd-indent"><code class="Li">$ set -A complete_got_1 -- $(got -h
2395 2&gt;&amp;1 | sed -n s/commands://p)</code></div>
2396 <p class="Pp">Clone an existing Git repository for use with
2397 <code class="Nm">got</code>.</p>
2398 <p class="Pp"></p>
2399 <div class="Bd Bd-indent"><code class="Li">$ cd /var/git/</code></div>
2400 <div class="Bd Bd-indent"><code class="Li">$ got clone
2401 ssh://git@github.com/openbsd/src.git</code></div>
2402 <p class="Pp">Use of HTTP URLs currently requires <a class="Xr">git(1)</a>:</p>
2403 <p class="Pp"></p>
2404 <div class="Bd Bd-indent"><code class="Li">$ cd /var/git/</code></div>
2405 <div class="Bd Bd-indent"><code class="Li">$ git clone --bare
2406 https://github.com/openbsd/src.git</code></div>
2407 <p class="Pp">Alternatively, for quick and dirty local testing of
2408 <code class="Nm">got</code> a new Git repository could be created and
2409 populated with files, e.g. from a temporary CVS checkout located at
2410 <span class="Pa">/tmp/src</span>:</p>
2411 <p class="Pp"></p>
2412 <div class="Bd Bd-indent"><code class="Li">$ got init
2413 /var/git/src.git</code></div>
2414 <div class="Bd Bd-indent"><code class="Li">$ got import -r /var/git/src.git -I
2415 CVS -I obj /tmp/src</code></div>
2416 <p class="Pp">Check out a work tree from the Git repository to /usr/src:</p>
2417 <p class="Pp"></p>
2418 <div class="Bd Bd-indent"><code class="Li">$ got checkout /var/git/src.git
2419 /usr/src</code></div>
2420 <p class="Pp">View local changes in a work tree directory:</p>
2421 <p class="Pp"></p>
2422 <div class="Bd Bd-indent"><code class="Li">$ got diff | less</code></div>
2423 <p class="Pp">In a work tree, display files in a potentially problematic
2424 state:</p>
2425 <p class="Pp"></p>
2426 <div class="Bd Bd-indent"><code class="Li">$ got status -s 'C!~?'</code></div>
2427 <p class="Pp">Interactively revert selected local changes in a work tree
2428 directory:</p>
2429 <p class="Pp"></p>
2430 <div class="Bd Bd-indent"><code class="Li">$ got revert -p
2431 -R&#x00A0;.</code></div>
2432 <p class="Pp">In a work tree or a git repository directory, list all branch
2433 references:</p>
2434 <p class="Pp"></p>
2435 <div class="Bd Bd-indent"><code class="Li">$ got branch -l</code></div>
2436 <p class="Pp">In a work tree or a git repository directory, create a new branch
2437 called &#x201C;unified-buffer-cache&#x201D; which is forked off the
2438 &#x201C;master&#x201D; branch:</p>
2439 <p class="Pp"></p>
2440 <div class="Bd Bd-indent"><code class="Li">$ got branch -c master
2441 unified-buffer-cache</code></div>
2442 <p class="Pp">Switch an existing work tree to the branch
2443 &#x201C;unified-buffer-cache&#x201D;. Local changes in the work tree will be
2444 preserved and merged if necessary:</p>
2445 <p class="Pp"></p>
2446 <div class="Bd Bd-indent"><code class="Li">$ got update -b
2447 unified-buffer-cache</code></div>
2448 <p class="Pp">Create a new commit from local changes in a work tree directory.
2449 This new commit will become the head commit of the work tree's current
2450 branch:</p>
2451 <p class="Pp"></p>
2452 <div class="Bd Bd-indent"><code class="Li">$ got commit</code></div>
2453 <p class="Pp">In a work tree or a git repository directory, view changes
2454 committed in the 3 most recent commits to the work tree's branch, or the
2455 branch resolved via the repository's HEAD reference, respectively:</p>
2456 <p class="Pp"></p>
2457 <div class="Bd Bd-indent"><code class="Li">$ got log -p -l 3</code></div>
2458 <p class="Pp">As above, but display changes in the order in which
2459 <a class="Xr">patch(1)</a> could apply them in sequence:</p>
2460 <p class="Pp"></p>
2461 <div class="Bd Bd-indent"><code class="Li">$ got log -p -l 3 -R</code></div>
2462 <p class="Pp">In a work tree or a git repository directory, log the history of a
2463 subdirectory:</p>
2464 <p class="Pp"></p>
2465 <div class="Bd Bd-indent"><code class="Li">$ got log sys/uvm</code></div>
2466 <p class="Pp">While operating inside a work tree, paths are specified relative
2467 to the current working directory, so this command will log the subdirectory
2468 <span class="Pa">sys/uvm</span>:</p>
2469 <p class="Pp"></p>
2470 <div class="Bd Bd-indent"><code class="Li">$ cd sys/uvm &amp;&amp; got
2471 log&#x00A0;.</code></div>
2472 <p class="Pp">And this command has the same effect:</p>
2473 <p class="Pp"></p>
2474 <div class="Bd Bd-indent"><code class="Li">$ cd sys/dev/usb &amp;&amp; got log
2475 ../../uvm</code></div>
2476 <p class="Pp">And this command displays work tree meta-data about all tracked
2477 files:</p>
2478 <p class="Pp"></p>
2479 <div class="Bd Bd-indent"><code class="Li">$ cd /usr/src</code></div>
2480 <div class="Bd Bd-indent"><code class="Li">$ got info&#x00A0;. |
2481 less</code></div>
2482 <p class="Pp">Add new files and remove obsolete files in a work tree
2483 directory:</p>
2484 <p class="Pp"></p>
2485 <div class="Bd Bd-indent"><code class="Li">$ got add
2486 sys/uvm/uvm_ubc.c</code></div>
2487 <div class="Bd Bd-indent"><code class="Li">$ got remove
2488 sys/uvm/uvm_vnode.c</code></div>
2489 <p class="Pp">Create a new commit from local changes in a work tree directory
2490 with a pre-defined log message.</p>
2491 <p class="Pp"></p>
2492 <div class="Bd Bd-indent"><code class="Li">$ got commit -m 'unify the buffer
2493 cache'</code></div>
2494 <p class="Pp">Alternatively, create a new commit from local changes in a work
2495 tree directory with a log message that has been prepared in the file
2496 <span class="Pa">/tmp/msg</span>:</p>
2497 <p class="Pp"></p>
2498 <div class="Bd Bd-indent"><code class="Li">$ got commit -F /tmp/msg</code></div>
2499 <p class="Pp">Update any work tree checked out from the
2500 &#x201C;unified-buffer-cache&#x201D; branch to the latest commit on this
2501 branch:</p>
2502 <p class="Pp"></p>
2503 <div class="Bd Bd-indent"><code class="Li">$ got update</code></div>
2504 <p class="Pp">Roll file content on the unified-buffer-cache branch back by one
2505 commit, and then fetch the rolled-back change into the work tree as a local
2506 change to be amended and perhaps committed again:</p>
2507 <p class="Pp"></p>
2508 <div class="Bd Bd-indent"><code class="Li">$ got backout
2509 unified-buffer-cache</code></div>
2510 <div class="Bd Bd-indent"><code class="Li">$ got commit -m 'roll back
2511 previous'</code></div>
2512 <div class="Bd Bd-indent"><code class="Li">$ # now back out the previous backout
2513 :-)</code></div>
2514 <div class="Bd Bd-indent"><code class="Li">$ got backout
2515 unified-buffer-cache</code></div>
2516 <p class="Pp">Fetch new changes on the remote repository's
2517 &#x201C;master&#x201D; branch, making them visible on the local repository's
2518 &#x201C;origin/master&#x201D; branch:</p>
2519 <p class="Pp"></p>
2520 <div class="Bd Bd-indent"><code class="Li">$ cd /usr/src</code></div>
2521 <div class="Bd Bd-indent"><code class="Li">$ got fetch</code></div>
2522 <p class="Pp">In a repository created with a HTTP URL and <code class="Cm">git
2523 clone --bare</code> the <a class="Xr">git-fetch(1)</a> command must be used
2524 instead:</p>
2525 <p class="Pp"></p>
2526 <div class="Bd Bd-indent"><code class="Li">$ cd /var/git/src.git</code></div>
2527 <div class="Bd Bd-indent"><code class="Li">$ git fetch origin
2528 master:refs/remotes/origin/master</code></div>
2529 <p class="Pp">Rebase the local &#x201C;master&#x201D; branch to merge the new
2530 changes that are now visible on the &#x201C;origin/master&#x201D;
2531 branch:</p>
2532 <p class="Pp"></p>
2533 <div class="Bd Bd-indent"><code class="Li">$ cd /usr/src</code></div>
2534 <div class="Bd Bd-indent"><code class="Li">$ got update -b
2535 origin/master</code></div>
2536 <div class="Bd Bd-indent"><code class="Li">$ got rebase master</code></div>
2537 <p class="Pp">Rebase the &#x201C;unified-buffer-cache&#x201D; branch on top of
2538 the new head commit of the &#x201C;master&#x201D; branch.</p>
2539 <p class="Pp"></p>
2540 <div class="Bd Bd-indent"><code class="Li">$ got update -b master</code></div>
2541 <div class="Bd Bd-indent"><code class="Li">$ got rebase
2542 unified-buffer-cache</code></div>
2543 <p class="Pp">Create a patch from all changes on the unified-buffer-cache
2544 branch. The patch can be mailed out for review and applied to
2545 <span class="Ux">OpenBSD</span>'s CVS tree:</p>
2546 <p class="Pp"></p>
2547 <div class="Bd Bd-indent"><code class="Li">$ got diff master
2548 unified-buffer-cache &gt; /tmp/ubc.diff</code></div>
2549 <p class="Pp">Edit the entire commit history of the
2550 &#x201C;unified-buffer-cache&#x201D; branch:</p>
2551 <p class="Pp"></p>
2552 <div class="Bd Bd-indent"><code class="Li">$ got update -b
2553 unified-buffer-cache</code></div>
2554 <div class="Bd Bd-indent"><code class="Li">$ got update -c master</code></div>
2555 <div class="Bd Bd-indent"><code class="Li">$ got histedit</code></div>
2556 <p class="Pp">Before working against existing branches in a repository cloned
2557 with <code class="Cm">git clone --bare</code> instead of
2558 <code class="Cm">got clone</code>, a Git &#x201C;refspec&#x201D; must be
2559 configured to map all references in the remote repository into the
2560 &#x201C;refs/remotes&#x201D; namespace of the local repository. This can be
2561 achieved by setting Git's <span class="Pa">remote.origin.fetch</span>
2562 configuration variable to the value
2563 &#x201C;+refs/heads/*:refs/remotes/origin/*&#x201D; with the
2564 <code class="Cm">git config</code> command:</p>
2565 <p class="Pp"></p>
2566 <div class="Bd Bd-indent"><code class="Li">$ cd /var/git/repo</code></div>
2567 <div class="Bd Bd-indent"><code class="Li">$ git config remote.origin.fetch
2568 '+refs/heads/*:refs/remotes/origin/*'</code></div>
2569 <p class="Pp">Additionally, the &#x201C;mirror&#x201D; option must be
2570 disabled:</p>
2571 <p class="Pp"></p>
2572 <div class="Bd Bd-indent"><code class="Li">$ cd /var/git/repo</code></div>
2573 <div class="Bd Bd-indent"><code class="Li">$ git config remote.origin.mirror
2574 false</code></div>
2575 <p class="Pp">Alternatively, the following <a class="Xr">git-fetch(1)</a>
2576 configuration item can be added manually to the Git repository's
2577 <span class="Pa">config</span> file:</p>
2578 <p class="Pp"></p>
2579 <div class="Bd Bd-indent"><code class="Li">[remote
2580 &quot;origin&quot;]</code></div>
2581 <div class="Bd Bd-indent"><code class="Li">url = ...</code></div>
2582 <div class="Bd Bd-indent"><code class="Li">fetch =
2583 +refs/heads/*:refs/remotes/origin/*</code></div>
2584 <div class="Bd Bd-indent"><code class="Li">mirror = false</code></div>
2585 <p class="Pp">This configuration leaves the local repository's
2586 &#x201C;refs/heads&#x201D; namespace free for use by local branches checked
2587 out with <code class="Cm">got checkout</code> and, if needed, created with
2588 <code class="Cm">got branch</code>. Branches in the
2589 &#x201C;refs/remotes/origin&#x201D; namespace can now be updated with
2590 incoming changes from the remote repository with <code class="Cm">got
2591 fetch</code> or <a class="Xr">git-fetch(1)</a> without extra command line
2592 arguments. Newly fetched changes can be examined with <code class="Cm">got
2593 log</code>.</p>
2594 <p class="Pp">Display changes on the remote repository's version of the
2595 &#x201C;master&#x201D; branch, as of the last time <code class="Cm">got
2596 fetch</code> was run:</p>
2597 <p class="Pp"></p>
2598 <div class="Bd Bd-indent"><code class="Li">$ got log -c origin/master |
2599 less</code></div>
2600 <p class="Pp">As shown here, most commands accept abbreviated reference names
2601 such as &#x201C;origin/master&#x201D; instead of
2602 &#x201C;refs/remotes/origin/master&#x201D;. The latter is only needed in
2603 case of ambiguity.</p>
2604 <p class="Pp"><code class="Cm">got rebase</code> must be used to merge changes
2605 which are visible on the &#x201C;origin/master&#x201D; branch into the
2606 &#x201C;master&#x201D; branch. This will also merge local changes, if any,
2607 with the incoming changes:</p>
2608 <p class="Pp"></p>
2609 <div class="Bd Bd-indent"><code class="Li">$ got update -b
2610 origin/master</code></div>
2611 <div class="Bd Bd-indent"><code class="Li">$ got rebase master</code></div>
2612 <p class="Pp">In order to make changes committed to the
2613 &#x201C;unified-buffer-cache&#x201D; visible on the &#x201C;master&#x201D;
2614 branch, the &#x201C;unified-buffer-cache&#x201D; branch must first be
2615 rebased onto the &#x201C;master&#x201D; branch:</p>
2616 <p class="Pp"></p>
2617 <div class="Bd Bd-indent"><code class="Li">$ got update -b master</code></div>
2618 <div class="Bd Bd-indent"><code class="Li">$ got rebase
2619 unified-buffer-cache</code></div>
2620 <p class="Pp">Changes on the &#x201C;unified-buffer-cache&#x201D; branch can now
2621 be made visible on the &#x201C;master&#x201D; branch with
2622 <code class="Cm">got integrate</code>. Because the rebase operation switched
2623 the work tree to the &#x201C;unified-buffer-cache&#x201D; branch the work
2624 tree must be switched back to the &#x201C;master&#x201D; branch first:</p>
2625 <p class="Pp"></p>
2626 <div class="Bd Bd-indent"><code class="Li">$ got update -b master</code></div>
2627 <div class="Bd Bd-indent"><code class="Li">$ got integrate
2628 unified-buffer-cache</code></div>
2629 <p class="Pp">On the &#x201C;master&#x201D; branch, log messages for local
2630 changes can now be amended with &#x201C;OK&#x201D; by other developers and
2631 any other important new information:</p>
2632 <p class="Pp"></p>
2633 <div class="Bd Bd-indent"><code class="Li">$ got update -c
2634 origin/master</code></div>
2635 <div class="Bd Bd-indent"><code class="Li">$ got histedit -m</code></div>
2636 <p class="Pp">If the remote repository offers write access local changes on the
2637 &#x201C;master&#x201D; branch can be sent to the remote repository with
2638 <code class="Cm">got send</code>. Usually, <code class="Cm">got send</code>
2639 can be run without further arguments. The arguments shown here match
2640 defaults, provided the work tree's current branch is the
2641 &#x201C;master&#x201D; branch:</p>
2642 <p class="Pp"></p>
2643 <div class="Bd Bd-indent"><code class="Li">$ got send -b master
2644 origin</code></div>
2645 <p class="Pp">If the remote repository requires the HTTPS protocol the
2646 <a class="Xr">git-push(1)</a> command must be used instead:</p>
2647 <p class="Pp"></p>
2648 <div class="Bd Bd-indent"><code class="Li">$ cd /var/git/src.git</code></div>
2649 <div class="Bd Bd-indent"><code class="Li">$ git push origin master</code></div>
2650 </section>
2651 <section class="Sh">
2652 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
2653 ALSO</a></h1>
2654 <p class="Pp"><a class="Xr">gotadmin(1)</a>, <a class="Xr">tog(1)</a>,
2655 <a class="Xr">git-repository(5)</a>, <a class="Xr">got-worktree(5)</a>,
2656 <a class="Xr">got.conf(5)</a></p>
2657 </section>
2658 <section class="Sh">
2659 <h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
2660 <p class="Pp"><span class="An">Stefan Sperling</span>
2661 &lt;<a class="Mt" href="mailto:stsp@openbsd.org">stsp@openbsd.org</a>&gt;
2662 <br/>
2663 <span class="An">Martin Pieuchot</span>
2664 &lt;<a class="Mt" href="mailto:mpi@openbsd.org">mpi@openbsd.org</a>&gt;
2665 <br/>
2666 <span class="An">Joshua Stein</span>
2667 &lt;<a class="Mt" href="mailto:jcs@openbsd.org">jcs@openbsd.org</a>&gt;
2668 <br/>
2669 <span class="An">Ori Bernstein</span>
2670 &lt;<a class="Mt" href="mailto:ori@openbsd.org">ori@openbsd.org</a>&gt;</p>
2671 </section>
2672 <section class="Sh">
2673 <h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
2674 <p class="Pp"><code class="Nm">got</code> is a work-in-progress and some
2675 features remain to be implemented.</p>
2676 <p class="Pp">At present, the user has to fall back on <a class="Xr">git(1)</a>
2677 to perform some tasks. In particular:</p>
2678 <ul class="Bl-bullet">
2679 <li>Reading from remote repositories over HTTP or HTTPS protocols requires
2680 <a class="Xr">git-clone(1)</a> and <a class="Xr">git-fetch(1)</a>.</li>
2681 <li>Writing to remote repositories over HTTP or HTTPS protocols requires
2682 <a class="Xr">git-push(1)</a>.</li>
2683 <li>The creation of merge commits with more than two parent commits requires
2684 <a class="Xr">git-merge(1)</a>.</li>
2685 <li>In situations where files or directories were moved around
2686 <code class="Cm">got</code> will not automatically merge changes to new
2687 locations and <a class="Xr">git(1)</a> will usually produce better
2688 results.</li>
2689 </ul>
2690 </section>
2691 </div>
2692 <table class="foot">
2693 <tr>
2694 <td class="foot-date">November 23, 2021</td>
2695 <td class="foot-os">OpenBSD 7.0</td>
2696 </tr>
2697 </table>
2698 </body>
2699 </html>