4 <meta charset="utf-8"/>
5 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
6 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
7 <title>GOTADMIN(1)</title>
9 <!-- This is an automatically generated file. Do not edit.
10 Copyright (c) 2021 Stefan Sperling
12 Permission to use, copy, modify, and distribute this software for any
13 purpose with or without fee is hereby granted, provided that the above
14 copyright notice and this permission notice appear in all copies.
16 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 <div class="head" role="doc-pageheader" aria-label="Manual header
26 line"><span class="head-ltitle">GOTADMIN(1)</span>
27 <span class="head-vol">General Commands Manual</span>
28 <span class="head-rtitle">GOTADMIN(1)</span></div>
29 <main class="manual-text">
31 <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 <p class="Pp"><code class="Nm">gotadmin</code> —
33 <span class="Nd" role="doc-subtitle">Game of Trees repository
34 administration</span></p>
37 <h2 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h2>
40 <td><code class="Nm">gotadmin</code></td>
41 <td>[<code class="Fl">-hV</code>] <var class="Ar">command</var>
42 [<var class="Ar">arg ...</var>]</td>
47 <h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
48 <p class="Pp"><code class="Nm">gotadmin</code> is the repository maintenance
49 tool for the <a class="Xr" aria-label="got, section 1">got(1)</a> version
51 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a> stores the
52 history of tracked files in a Git repository, as used by the Git version
53 control system. <code class="Nm">gotadmin</code> provides commands for
54 inspecting and manipulating the on-disk state of Git repositories. The
55 repository format is described in <a class="Xr" aria-label="git-repository,
56 section 5">git-repository(5)</a>.</p>
57 <p class="Pp"><code class="Nm">gotadmin</code> provides global and
58 command-specific options. Global options must precede the command name, and
61 <dt id="h"><a class="permalink" href="#h"><code class="Fl">-h</code></a></dt>
62 <dd>Display usage information and exit immediately.</dd>
63 <dt id="V"><a class="permalink" href="#V"><code class="Fl">-V</code></a>,
64 <code class="Fl">--version</code></dt>
65 <dd>Display program version and exit immediately.</dd>
67 <p class="Pp">The commands for <code class="Nm">gotadmin</code> are as
70 <dt id="init"><a class="permalink" href="#init"><code class="Cm">init</code></a>
71 [<code class="Fl">-A</code> <var class="Ar">hashing-algorithm</var>]
72 [<code class="Fl">-b</code> <var class="Ar">branch</var>]
73 <var class="Ar">repository-path</var></dt>
74 <dd>Create a new empty repository at the specified
75 <var class="Ar">repository-path</var>.
76 <p class="Pp">After <code class="Cm">gotadmin init</code>, the new
77 repository must be populated before <code class="Cm">got checkout</code>
78 can be used. The <code class="Cm">got import</code> command can be used
79 to populate the new repository with data from a local directory.
80 Alternatively, on a server running <a class="Xr" aria-label="gotd,
81 section 8">gotd(8)</a>, the new repository can be made available to
82 <a class="Xr" aria-label="got, section 1">got(1)</a> or
83 <a class="Xr" aria-label="git, section 1">git(1)</a> clients by adding
84 the repository to <a class="Xr" aria-label="gotd.conf, section
85 5">gotd.conf(5)</a> and restarting <a class="Xr" aria-label="gotd,
86 section 8">gotd(8)</a>. Clients may then clone the new repository from
87 the server, populate the cloned repository, and then populate the new
88 repository on the server via <code class="Cm">got send</code> or
89 <code class="Cm">git push</code>.</p>
90 <p class="Pp">The options for <code class="Cm">gotadmin init</code> are as
93 <dt id="A"><a class="permalink" href="#A"><code class="Fl">-A</code></a>
94 <var class="Ar">hashing-algorithm</var></dt>
95 <dd>Configure the repository's <var class="Ar">hashing-algorithm</var>
96 used for the computation of Git object IDs. Possible values are
97 <code class="Cm">sha1</code> (the default) or
98 <code class="Cm">sha256</code>.</dd>
99 <dt id="b"><a class="permalink" href="#b"><code class="Fl">-b</code></a>
100 <var class="Ar">branch</var></dt>
101 <dd>Make the repository's HEAD reference point to the specified
102 <var class="Ar">branch</var> instead of the default branch
103 “main”.</dd>
105 <p class="Pp">The <code class="Cm">gotadmin init</code> command is
106 equivalent to <code class="Cm">got init</code>.</p>
108 <dt id="info"><a class="permalink" href="#info"><code class="Cm">info</code></a>
109 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]</dt>
110 <dd>Display information about a repository. This includes some configuration
111 settings from <a class="Xr" aria-label="got.conf, section
112 5">got.conf(5)</a>, the object ID hashing algorithm, and the number of
113 objects stored in the repository, in packed or loose form, as well as the
114 current on-disk size of these objects.
115 <p class="Pp">The options for <code class="Cm">gotadmin info</code> are as
118 <dt id="r"><a class="permalink" href="#r"><code class="Fl">-r</code></a>
119 <var class="Ar">repository-path</var></dt>
120 <dd>Use the repository at the specified path. If not specified, assume the
121 repository is located at or above the current working directory. If
122 this directory is a <a class="Xr" aria-label="got, section
123 1">got(1)</a> work tree, use the repository path associated with this
127 <dt id="pack"><a class="permalink" href="#pack"><code class="Cm">pack</code></a>
128 [<code class="Fl">-aDq</code>] [<code class="Fl">-r</code>
129 <var class="Ar">repository-path</var>] [<code class="Fl">-x</code>
130 <var class="Ar">reference</var>] [<var class="Ar">reference ...</var>]</dt>
131 <dd>Generate a new pack file and a corresponding pack file index. By default,
132 add any loose objects which are reachable via any references to the
134 <p class="Pp">If one or more <var class="Ar">reference</var> arguments is
135 specified, only add objects which are reachable via the specified
136 references. Each <var class="Ar">reference</var> argument may either
137 specify a specific reference or a reference namespace, in which case all
138 references within this namespace will be used.</p>
139 <p class="Pp"><code class="Cm">gotadmin pack</code> always ignores
140 references in the <span class="Pa">refs/got/</span> namespace,
141 effectively treating such references as if they did not refer to any
143 <p class="Pp">The options for <code class="Cm">gotadmin pack</code> are as
146 <dt id="a"><a class="permalink" href="#a"><code class="Fl">-a</code></a></dt>
147 <dd>Add objects to the generated pack file even if they are already packed
148 in a different pack file. Unless this option is specified, only loose
149 objects will be added.</dd>
150 <dt id="D"><a class="permalink" href="#D"><code class="Fl">-D</code></a></dt>
151 <dd>Force the use of ref-delta representation for deltified objects. If
152 this option is not specified, offset-deltas will be used to represent
153 deltified objects.</dd>
154 <dt id="q"><a class="permalink" href="#q"><code class="Fl">-q</code></a></dt>
155 <dd>Suppress progress reporting output.</dd>
156 <dt id="r~2"><a class="permalink" href="#r~2"><code class="Fl">-r</code></a>
157 <var class="Ar">repository-path</var></dt>
158 <dd>Use the repository at the specified path. If not specified, assume the
159 repository is located at or above the current working directory. If
160 this directory is a <a class="Xr" aria-label="got, section
161 1">got(1)</a> work tree, use the repository path associated with this
163 <dt id="x"><a class="permalink" href="#x"><code class="Fl">-x</code></a>
164 <var class="Ar">reference</var></dt>
165 <dd>Exclude objects reachable via the specified
166 <var class="Ar">reference</var> from the pack file. The
167 <var class="Ar">reference</var> argument may either specify a specific
168 reference or a reference namespace, in which case all references
169 within this namespace will be excluded. The <code class="Fl">-x</code>
170 option may be specified multiple times to build a list of references
172 <p class="Pp">Exclusion takes precedence over inclusion. If a reference
173 appears in both the included and excluded lists, it will be
178 <dt id="ix"><a class="permalink" href="#indexpack"><code class="Cm" id="indexpack">indexpack</code></a>
179 <var class="Ar">packfile-path</var></dt>
181 <div class="Bd Bd-indent"><code class="Li">(alias:
182 <code class="Cm">ix</code>)</code></div>
183 Create a pack index for the pack file at
184 <var class="Ar">packfile-path</var>.
185 <p class="Pp">A pack index is required for using the corresponding pack file
186 with <a class="Xr" aria-label="got, section 1">got(1)</a>. Usually, a
187 pack index will be created by commands such as <code class="Cm">gotadmin
188 pack</code> or <code class="Cm">got fetch</code> as part of regular
189 operation. The <code class="Cm">gotadmin indexpack</code> command may be
190 used to recover from a corrupt or missing index. A given pack file will
191 always yield the same bit-identical index.</p>
192 <p class="Pp">The provided <var class="Ar">packfile-path</var> must be
193 located within the <span class="Pa">objects/pack/</span> directory of
194 the repository and should end in <span class="Pa">.pack</span>. The
195 filename of the corresponding pack index is equivalent, except that it
196 ends in <span class="Pa">.idx</span>.</p>
198 <dt id="ls"><a class="permalink" href="#listpack"><code class="Cm" id="listpack">listpack</code></a>
199 [<code class="Fl">-hs</code>] <var class="Ar">packfile-path</var></dt>
201 <div class="Bd Bd-indent"><code class="Li">(alias:
202 <code class="Cm">ls</code>)</code></div>
203 List the contents of the pack file at <var class="Ar">packfile-path</var>.
204 <p class="Pp">Each object contained in the pack file will be displayed on a
205 single line. The information shown includes the object ID, object type,
206 object offset, and object size.</p>
207 <p class="Pp">If a packed object is deltified against another object, the
208 delta base will be shown as well. For offset deltas, the delta base is
209 identified via an offset into the pack file. For reference deltas, the
210 delta base is identified via an object ID.</p>
211 <p class="Pp">The provided <var class="Ar">packfile-path</var> must be
212 located within the <span class="Pa">objects/pack/</span> directory of
213 the repository and should end in <span class="Pa">.pack</span>. The
214 corresponding pack index must exist and can be created with
215 <code class="Cm">gotadmin indexpack</code> if it is missing.</p>
216 <p class="Pp">The options for <code class="Cm">gotadmin listpack</code> are
219 <dt id="h~2"><a class="permalink" href="#h~2"><code class="Fl">-h</code></a></dt>
220 <dd>Show object sizes in human-readable form.</dd>
221 <dt id="s"><a class="permalink" href="#s"><code class="Fl">-s</code></a></dt>
222 <dd>Display statistics about the pack file after listing objects. This
223 includes the total number of objects stored in the pack file and a
224 break-down of the number of objects per object type.</dd>
227 <dt id="cl"><a class="permalink" href="#cleanup"><code class="Cm" id="cleanup">cleanup</code></a>
228 [<code class="Fl">-anpq</code>] [<code class="Fl">-r</code>
229 <var class="Ar">repository-path</var>]</dt>
231 <div class="Bd Bd-indent"><code class="Li">(alias:
232 <code class="Cm">cl</code>)</code></div>
233 Purge unreferenced loose objects and redundant pack files from the
234 repository and display the amount of disk space which has been freed as a
236 <p class="Pp">Unreferenced objects are present in the repository but cannot
237 be reached via any reference in the entire <span class="Pa">refs/</span>
238 namespace. Objects will usually become unreferenced as a result of
239 deleting branches, tags, or other references with <code class="Cm">got
240 branch -d</code>, <code class="Cm">got ref -d</code>, or
241 <code class="Cm">got fetch -X</code>.</p>
242 <p class="Pp">Loose objects are stored as individual files beneath the
243 repository's <span class="Pa">objects/</span> directory, spread across
244 256 sub-directories named after the 256 possible hexadecimal values of
245 the first byte of an object identifier.</p>
246 <p class="Pp">Packed objects are stored in pack files under
247 <span class="Pa">objects/pack/</span>.</p>
248 <p class="Pp">If redundant copies of packed objects exist in loose form,
249 such redundant copies will be purged. If all the objects of a pack file
250 are present in other pack files, the redundant pack file will be purged.
251 Pack files will usually become redundant as a result of repacking the
252 repository with <code class="Nm">gotadmin</code>
253 <code class="Cm">pack</code> <code class="Fl">-a</code>.</p>
254 <p class="Pp">References in the <span class="Pa">refs/got</span> namespace
255 may prevent objects from being purged. This includes references in the
256 <span class="Pa">refs/got/worktree</span> namespace created by
257 <code class="Cm">got checkout</code> and <code class="Cm">got
258 update</code>, as well as references in the
259 <span class="Pa">refs/got/backup</span> namespace created by
260 <code class="Cm">got rebase</code> and <code class="Cm">got
261 histedit</code>. <code class="Cm">gotadmin cleanup</code> will only
262 purge corresponding objects once such references have been deleted with
263 <code class="Cm">got rebase -X</code>, <code class="Cm">got histedit
264 -X</code>, or <code class="Cm">got ref -d</code>.</p>
265 <p class="Pp">The “preciousObjects” Git extension is intended
266 to prevent the removal of objects from a repository.
267 <code class="Cm">gotadmin cleanup</code> will refuse to operate on
268 repositories where this extension is active.</p>
269 <p class="Pp">For compatibility with Git, if a file with the extension
270 <span class="Pa">.keep</span> exists and corresponds to a pack file with
271 the extension <span class="Pa">.pack</span> then this pack file will not
273 <p class="Pp">Some Git repositories contain pack index files which lack a
274 corresponding pack file, which is an inconsistent repository state. In
275 such cases, <code class="Cm">gotadmin cleanup -p -n</code> will display
276 a list of affected pack index files. Whenever possible, the missing pack
277 files should be restored. If restoring missing pack files is not
278 possible, then affected pack index files can be removed with
279 <code class="Cm">gotadmin cleanup -p</code>.</p>
280 <p class="Pp">The options for <code class="Cm">gotadmin cleanup</code> are
283 <dt id="a~2"><a class="permalink" href="#a~2"><code class="Fl">-a</code></a></dt>
284 <dd>Delete all redundant loose and packed objects. By default, objects
285 which are newer than an implementation-defined modification timestamp
286 are kept on disk to prevent race conditions with other commands that
287 add new objects to the repository while <code class="Cm">gotadmin
288 cleanup</code> is running.</dd>
289 <dt id="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
290 <dd>Display the usual progress output and summary information but do not
291 actually remove any files from disk.</dd>
292 <dt id="p"><a class="permalink" href="#p"><code class="Fl">-p</code></a></dt>
293 <dd>Instead of purging unreferenced loose objects and redundant pack
294 files, remove any pack index files which do not have a corresponding
296 <dt id="q~2"><a class="permalink" href="#q~2"><code class="Fl">-q</code></a></dt>
297 <dd>Suppress progress reporting and disk space summary output.</dd>
298 <dt id="r~3"><a class="permalink" href="#r~3"><code class="Fl">-r</code></a>
299 <var class="Ar">repository-path</var></dt>
300 <dd>Use the repository at the specified path. If not specified, assume the
301 repository is located at or above the current working directory. If
302 this directory is a <a class="Xr" aria-label="got, section
303 1">got(1)</a> work tree, use the repository path associated with this
307 <dt id="dump"><a class="permalink" href="#dump"><code class="Cm">dump</code></a>
308 [<code class="Fl">-q</code>] [<code class="Fl">-r</code>
309 <var class="Ar">repository-path</var>] [<code class="Fl">-x</code>
310 <var class="Ar">reference</var>] [<var class="Ar">reference ...</var>]</dt>
311 <dd>Dump the contents of the repository to standard output in Git bundle
313 <p class="Pp">If one or more <var class="Ar">reference</var> arguments is
314 specified, only add objects which are reachable via the specified
315 references. Each <var class="Ar">reference</var> argument may either
316 specify a specific reference or a reference namespace, in which case all
317 references within this namespace will be used.</p>
318 <p class="Pp">The options for <code class="Nm">gotadmin</code>
319 <code class="Cm">dump</code> are as follows:</p>
321 <dt id="q~3"><a class="permalink" href="#q~3"><code class="Fl">-q</code></a></dt>
322 <dd>Suppress progress reporting output.</dd>
323 <dt id="r~4"><a class="permalink" href="#r~4"><code class="Fl">-r</code></a>
324 <var class="Ar">repository-path</var></dt>
325 <dd>Use the repository at the specified path. If not specified, assume the
326 repository is located at or above the current working directory. If
327 this directory is a <a class="Xr" aria-label="got, section
328 1">got(1)</a> work tree, use the repository path associated with this
330 <dt id="x~2"><a class="permalink" href="#x~2"><code class="Fl">-x</code></a>
331 <var class="Ar">reference</var></dt>
332 <dd>Exclude objects reachable via the specified
333 <var class="Ar">reference</var> from the bundle. The
334 <var class="Ar">reference</var> argument may either specify a specific
335 reference or a reference namespace, in which case all references
336 within this namespace will be excluded. The <code class="Fl">-x</code>
337 option may be specified multiple times to build a list of references
339 <p class="Pp">Exclusion takes precedence over inclusion. If a reference
340 appears in both the included and excluded lists, it will be
345 <dt id="load"><a class="permalink" href="#load"><code class="Cm">load</code></a>
346 [<code class="Fl">-nq</code>] [<code class="Fl">-l</code>
347 <var class="Ar">bundle-path</var>] [<code class="Fl">-r</code>
348 <var class="Ar">repository-path</var>] [<var class="Ar">reference
350 <dd>Read a Git bundle stream from standard input and load its data into a
352 <p class="Pp">If one or more <var class="Ar">reference</var> arguments are
353 provided then only load the specified references from the bundle.
354 Otherwise, all references will be loaded.</p>
355 <p class="Pp">The options for <code class="Cm">gotadmin load</code> are as
358 <dt id="l"><a class="permalink" href="#l"><code class="Fl">-l</code></a>
359 <var class="Ar">bundle-path</var></dt>
360 <dd>List references available for loading from the bundle at the specified
361 <var class="Ar">bundle-path</var> and exit immediately. If the
362 <code class="Fl">-l</code> option is specified then no
363 <var class="Ar">reference</var> arguments are allowed. The
364 <code class="Fl">-l</code> option is incompatible with the
365 <code class="Fl">-n</code> option.</dd>
366 <dt id="n~2"><a class="permalink" href="#n~2"><code class="Fl">-n</code></a></dt>
367 <dd>Attempt to load the bundle but don't install new packfile or update
368 any reference. Can be used to verify the integrity of the bundle.</dd>
369 <dt id="q~4"><a class="permalink" href="#q~4"><code class="Fl">-q</code></a></dt>
370 <dd>Suppress progress reporting output.</dd>
371 <dt id="r~5"><a class="permalink" href="#r~5"><code class="Fl">-r</code></a>
372 <var class="Ar">repository-path</var></dt>
373 <dd>Use the repository at the specified path. If not specified, assume the
374 repository is located at or above the current working directory. If
375 this directory is a <a class="Xr" aria-label="got, section
376 1">got(1)</a> work tree, use the repository path associated with this
383 <h2 class="Sh" id="EXIT_STATUS"><a class="permalink" href="#EXIT_STATUS">EXIT
385 <p class="Pp">The <code class="Nm">gotadmin</code> utility exits 0 on
386 success, and >0 if an error occurs.</p>
389 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
391 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
392 <a class="Xr" aria-label="tog, section 1">tog(1)</a>,
393 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
394 <a class="Xr" aria-label="got.conf, section 5">got.conf(5)</a></p>
397 <h2 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h2>
398 <p class="Pp"><span class="An">Christian Weisgerber</span>
399 <<a class="Mt" href="mailto:naddy@openbsd.org">naddy@openbsd.org</a>>
401 <span class="An">Josh Rickmar</span>
402 <<a class="Mt" href="mailto:jrick@zettaport.com">jrick@zettaport.com</a>>
404 <span class="An">Klemens Nanni</span>
405 <<a class="Mt" href="mailto:kn@openbsd.org">kn@openbsd.org</a>>
407 <span class="An">Omar Polo</span>
408 <<a class="Mt" href="mailto:op@openbsd.org">op@openbsd.org</a>>
410 <span class="An">Ori Bernstein</span>
411 <<a class="Mt" href="mailto:ori@openbsd.org">ori@openbsd.org</a>>
413 <span class="An">Stefan Sperling</span>
414 <<a class="Mt" href="mailto:stsp@openbsd.org">stsp@openbsd.org</a>>
416 <span class="An">Tracey Emery</span>
417 <<a class="Mt" href="mailto:tracey@traceyemery.net">tracey@traceyemery.net</a>></p>
420 <h2 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h2>
421 <p class="Pp"><code class="Nm">gotadmin</code> is a work-in-progress and some
422 features remain to be implemented.</p>
423 <p class="Pp">At present, the user has to fall back on
424 <a class="Xr" aria-label="git, section 1">git(1)</a> to perform some tasks.
426 <ul class="Bl-bullet">
427 <li>Exporting data from repositories requires
428 <a class="Xr" aria-label="git-fast-export, section
429 1">git-fast-export(1)</a>.</li>
430 <li>Importing data into repositories requires
431 <a class="Xr" aria-label="git-fast-import, section
432 1">git-fast-import(1)</a>.</li>
436 <h2 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h2>
437 <p class="Pp">Disk space savings reported by <code class="Cm">gotadmin
438 cleanup</code> will be misleading if the repository contains object files
439 that were hard-linked from another repository. Such hard-links will be
440 created by certain <a class="Xr" aria-label="git, section 1">git(1)</a>
441 commands. By itself, <a class="Xr" aria-label="got, section 1">got(1)</a>
442 will never create hard-linked object files.</p>
445 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
446 line"><span class="foot-left"></span><span class="foot-date">December 28,
447 2024</span> <span class="foot-os">OpenBSD 7.6</span></div>
