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">-b</code> <var class="Ar">branch</var>]
72 <var class="Ar">repository-path</var></dt>
73 <dd>Create a new empty repository at the specified
74 <var class="Ar">repository-path</var>.
75 <p class="Pp">After <code class="Cm">gotadmin init</code>, the
76 <code class="Cm">got import</code> command must be used to populate the
77 empty repository before <code class="Cm">got checkout</code> can be
79 <p class="Pp">The options for <code class="Cm">gotadmin init</code> are as
82 <dt id="b"><a class="permalink" href="#b"><code class="Fl">-b</code></a>
83 <var class="Ar">branch</var></dt>
84 <dd>Make the repository's HEAD reference point to the specified
85 <var class="Ar">branch</var> instead of the default branch
86 “main”.</dd>
89 <dt id="info"><a class="permalink" href="#info"><code class="Cm">info</code></a>
90 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]</dt>
91 <dd>Display information about a repository. This includes some configuration
92 settings from <a class="Xr" aria-label="got.conf, section
93 5">got.conf(5)</a>, and the number of objects stored in the repository, in
94 packed or loose form, as well as the current on-disk size of these
96 <p class="Pp">The options for <code class="Cm">gotadmin info</code> are as
99 <dt id="r"><a class="permalink" href="#r"><code class="Fl">-r</code></a>
100 <var class="Ar">repository-path</var></dt>
101 <dd>Use the repository at the specified path. If not specified, assume the
102 repository is located at or above the current working directory. If
103 this directory is a <a class="Xr" aria-label="got, section
104 1">got(1)</a> work tree, use the repository path associated with this
108 <dt id="pack"><a class="permalink" href="#pack"><code class="Cm">pack</code></a>
109 [<code class="Fl">-aDq</code>] [<code class="Fl">-r</code>
110 <var class="Ar">repository-path</var>] [<code class="Fl">-x</code>
111 <var class="Ar">reference</var>] [<var class="Ar">reference ...</var>]</dt>
112 <dd>Generate a new pack file and a corresponding pack file index. By default,
113 add any loose objects which are reachable via any references to the
115 <p class="Pp">If one or more <var class="Ar">reference</var> arguments is
116 specified, only add objects which are reachable via the specified
117 references. Each <var class="Ar">reference</var> argument may either
118 specify a specific reference or a reference namespace, in which case all
119 references within this namespace will be used.</p>
120 <p class="Pp"><code class="Cm">gotadmin pack</code> always ignores
121 references in the <span class="Pa">refs/got/</span> namespace,
122 effectively treating such references as if they did not refer to any
124 <p class="Pp">The options for <code class="Cm">gotadmin pack</code> are as
127 <dt id="a"><a class="permalink" href="#a"><code class="Fl">-a</code></a></dt>
128 <dd>Add objects to the generated pack file even if they are already packed
129 in a different pack file. Unless this option is specified, only loose
130 objects will be added.</dd>
131 <dt id="D"><a class="permalink" href="#D"><code class="Fl">-D</code></a></dt>
132 <dd>Force the use of ref-delta representation for deltified objects. If
133 this option is not specified, offset-deltas will be used to represent
134 deltified objects.</dd>
135 <dt id="q"><a class="permalink" href="#q"><code class="Fl">-q</code></a></dt>
136 <dd>Suppress progress reporting output.</dd>
137 <dt id="r~2"><a class="permalink" href="#r~2"><code class="Fl">-r</code></a>
138 <var class="Ar">repository-path</var></dt>
139 <dd>Use the repository at the specified path. If not specified, assume the
140 repository is located at or above the current working directory. If
141 this directory is a <a class="Xr" aria-label="got, section
142 1">got(1)</a> work tree, use the repository path associated with this
144 <dt id="x"><a class="permalink" href="#x"><code class="Fl">-x</code></a>
145 <var class="Ar">reference</var></dt>
146 <dd>Exclude objects reachable via the specified
147 <var class="Ar">reference</var> from the pack file. The
148 <var class="Ar">reference</var> argument may either specify a specific
149 reference or a reference namespace, in which case all references
150 within this namespace will be excluded. The <code class="Fl">-x</code>
151 option may be specified multiple times to build a list of references
153 <p class="Pp">Exclusion takes precedence over inclusion. If a reference
154 appears in both the included and excluded lists, it will be
159 <dt id="ix"><a class="permalink" href="#indexpack"><code class="Cm" id="indexpack">indexpack</code></a>
160 <var class="Ar">packfile-path</var></dt>
162 <div class="Bd Bd-indent"><code class="Li">(alias:
163 <code class="Cm">ix</code>)</code></div>
164 Create a pack index for the pack file at
165 <var class="Ar">packfile-path</var>.
166 <p class="Pp">A pack index is required for using the corresponding pack file
167 with <a class="Xr" aria-label="got, section 1">got(1)</a>. Usually, a
168 pack index will be created by commands such as <code class="Cm">gotadmin
169 pack</code> or <code class="Cm">got fetch</code> as part of regular
170 operation. The <code class="Cm">gotadmin indexpack</code> command may be
171 used to recover from a corrupt or missing index. A given pack file will
172 always yield the same bit-identical index.</p>
173 <p class="Pp">The provided <var class="Ar">packfile-path</var> must be
174 located within the <span class="Pa">objects/pack/</span> directory of
175 the repository and should end in <span class="Pa">.pack</span>. The
176 filename of the corresponding pack index is equivalent, except that it
177 ends in <span class="Pa">.idx</span>.</p>
179 <dt id="ls"><a class="permalink" href="#listpack"><code class="Cm" id="listpack">listpack</code></a>
180 [<code class="Fl">-hs</code>] <var class="Ar">packfile-path</var></dt>
182 <div class="Bd Bd-indent"><code class="Li">(alias:
183 <code class="Cm">ls</code>)</code></div>
184 List the contents of the pack file at <var class="Ar">packfile-path</var>.
185 <p class="Pp">Each object contained in the pack file will be displayed on a
186 single line. The information shown includes the object ID, object type,
187 object offset, and object size.</p>
188 <p class="Pp">If a packed object is deltified against another object, the
189 delta base will be shown as well. For offset deltas, the delta base is
190 identified via an offset into the pack file. For reference deltas, the
191 delta base is identified via an object ID.</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 corresponding pack index must exist and can be created with
196 <code class="Cm">gotadmin indexpack</code> if it is missing.</p>
197 <p class="Pp">The options for <code class="Cm">gotadmin listpack</code> are
200 <dt id="h~2"><a class="permalink" href="#h~2"><code class="Fl">-h</code></a></dt>
201 <dd>Show object sizes in human-readable form.</dd>
202 <dt id="s"><a class="permalink" href="#s"><code class="Fl">-s</code></a></dt>
203 <dd>Display statistics about the pack file after listing objects. This
204 includes the total number of objects stored in the pack file and a
205 break-down of the number of objects per object type.</dd>
208 <dt id="cl"><a class="permalink" href="#cleanup"><code class="Cm" id="cleanup">cleanup</code></a>
209 [<code class="Fl">-anpq</code>] [<code class="Fl">-r</code>
210 <var class="Ar">repository-path</var>]</dt>
212 <div class="Bd Bd-indent"><code class="Li">(alias:
213 <code class="Cm">cl</code>)</code></div>
214 Purge unreferenced loose objects and redundant pack files from the
215 repository and display the amount of disk space which has been freed as a
217 <p class="Pp">Unreferenced objects are present in the repository but cannot
218 be reached via any reference in the entire <span class="Pa">refs/</span>
219 namespace. Objects will usually become unreferenced as a result of
220 deleting branches, tags, or other references with <code class="Cm">got
221 branch -d</code>, <code class="Cm">got ref -d</code>, or
222 <code class="Cm">got fetch -X</code>.</p>
223 <p class="Pp">Loose objects are stored as individual files beneath the
224 repository's <span class="Pa">objects/</span> directory, spread across
225 256 sub-directories named after the 256 possible hexadecimal values of
226 the first byte of an object identifier.</p>
227 <p class="Pp">Packed objects are stored in pack files under
228 <span class="Pa">objects/pack/</span>.</p>
229 <p class="Pp">If redundant copies of packed objects exist in loose form,
230 such redundant copies will be purged. If all the objects of a pack file
231 are present in other pack files, the redundant pack file will be purged.
232 Pack files will usually become redundant as a result of repacking the
233 repository with <code class="Nm">gotadmin</code>
234 <code class="Cm">pack</code> <code class="Fl">-a</code>.</p>
235 <p class="Pp">References in the <span class="Pa">refs/got</span> namespace
236 may prevent objects from being purged. This includes references in the
237 <span class="Pa">refs/got/worktree</span> namespace created by
238 <code class="Cm">got checkout</code> and <code class="Cm">got
239 update</code>, as well as references in the
240 <span class="Pa">refs/got/backup</span> namespace created by
241 <code class="Cm">got rebase</code> and <code class="Cm">got
242 histedit</code>. <code class="Cm">gotadmin cleanup</code> will only
243 purge corresponding objects once such references have been deleted with
244 <code class="Cm">got rebase -X</code>, <code class="Cm">got histedit
245 -X</code>, or <code class="Cm">got ref -d</code>.</p>
246 <p class="Pp">The “preciousObjects” Git extension is intended
247 to prevent the removal of objects from a repository.
248 <code class="Cm">gotadmin cleanup</code> will refuse to operate on
249 repositories where this extension is active.</p>
250 <p class="Pp">For compatibility with Git, if a file with the extension
251 <span class="Pa">.keep</span> exists and corresponds to a pack file with
252 the extension <span class="Pa">.pack</span> then this pack file will not
254 <p class="Pp">Some Git repositories contain pack index files which lack a
255 corresponding pack file, which is an inconsistent repository state. In
256 such cases, <code class="Cm">gotadmin cleanup -p -n</code> will display
257 a list of affected pack index files. Whenever possible, the missing pack
258 files should be restored. If restoring missing pack files is not
259 possible, then affected pack index files can be removed with
260 <code class="Cm">gotadmin cleanup -p</code>.</p>
261 <p class="Pp">The options for <code class="Cm">gotadmin cleanup</code> are
264 <dt id="a~2"><a class="permalink" href="#a~2"><code class="Fl">-a</code></a></dt>
265 <dd>Delete all redundant loose and packed objects. By default, objects
266 which are newer than an implementation-defined modification timestamp
267 are kept on disk to prevent race conditions with other commands that
268 add new objects to the repository while <code class="Cm">gotadmin
269 cleanup</code> is running.</dd>
270 <dt id="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
271 <dd>Display the usual progress output and summary information but do not
272 actually remove any files from disk.</dd>
273 <dt id="p"><a class="permalink" href="#p"><code class="Fl">-p</code></a></dt>
274 <dd>Instead of purging unreferenced loose objects and redundant pack
275 files, remove any pack index files which do not have a corresponding
277 <dt id="q~2"><a class="permalink" href="#q~2"><code class="Fl">-q</code></a></dt>
278 <dd>Suppress progress reporting and disk space summary output.</dd>
279 <dt id="r~3"><a class="permalink" href="#r~3"><code class="Fl">-r</code></a>
280 <var class="Ar">repository-path</var></dt>
281 <dd>Use the repository at the specified path. If not specified, assume the
282 repository is located at or above the current working directory. If
283 this directory is a <a class="Xr" aria-label="got, section
284 1">got(1)</a> work tree, use the repository path associated with this
288 <dt id="dump"><a class="permalink" href="#dump"><code class="Cm">dump</code></a>
289 [<code class="Fl">-q</code>] [<code class="Fl">-r</code>
290 <var class="Ar">repository-path</var>] [<code class="Fl">-x</code>
291 <var class="Ar">reference</var>] [<var class="Ar">reference ...</var>]</dt>
292 <dd>Dump the contents of the repository to standard output in Git bundle
294 <p class="Pp">If one or more <var class="Ar">reference</var> arguments is
295 specified, only add objects which are reachable via the specified
296 references. Each <var class="Ar">reference</var> argument may either
297 specify a specific reference or a reference namespace, in which case all
298 references within this namespace will be used.</p>
299 <p class="Pp">The options for <code class="Nm">gotadmin</code>
300 <code class="Cm">dump</code> are as follows:</p>
302 <dt id="q~3"><a class="permalink" href="#q~3"><code class="Fl">-q</code></a></dt>
303 <dd>Suppress progress reporting output.</dd>
304 <dt id="r~4"><a class="permalink" href="#r~4"><code class="Fl">-r</code></a>
305 <var class="Ar">repository-path</var></dt>
306 <dd>Use the repository at the specified path. If not specified, assume the
307 repository is located at or above the current working directory. If
308 this directory is a <a class="Xr" aria-label="got, section
309 1">got(1)</a> work tree, use the repository path associated with this
311 <dt id="x~2"><a class="permalink" href="#x~2"><code class="Fl">-x</code></a>
312 <var class="Ar">reference</var></dt>
313 <dd>Exclude objects reachable via the specified
314 <var class="Ar">reference</var> from the bundle. The
315 <var class="Ar">reference</var> argument may either specify a specific
316 reference or a reference namespace, in which case all references
317 within this namespace will be excluded. The <code class="Fl">-x</code>
318 option may be specified multiple times to build a list of references
320 <p class="Pp">Exclusion takes precedence over inclusion. If a reference
321 appears in both the included and excluded lists, it will be
326 <dt id="load"><a class="permalink" href="#load"><code class="Cm">load</code></a>
327 [<code class="Fl">-nq</code>] [<code class="Fl">-l</code>
328 <var class="Ar">bundle-path</var>] [<code class="Fl">-r</code>
329 <var class="Ar">repository-path</var>] [<var class="Ar">reference
331 <dd>Read a Git bundle stream from standard input and load its data into a
333 <p class="Pp">If one or more <var class="Ar">reference</var> arguments are
334 provided then only load the specified references from the bundle.
335 Otherwise, all references will be loaded.</p>
336 <p class="Pp">The options for <code class="Cm">gotadmin load</code> are as
339 <dt id="l"><a class="permalink" href="#l"><code class="Fl">-l</code></a>
340 <var class="Ar">bundle-path</var></dt>
341 <dd>List references available for loading from the bundle at the specified
342 <var class="Ar">bundle-path</var> and exit immediately. If the
343 <code class="Fl">-l</code> option is specified then no
344 <var class="Ar">reference</var> arguments are allowed. The
345 <code class="Fl">-l</code> option is incompatible with the
346 <code class="Fl">-n</code> option.</dd>
347 <dt id="n~2"><a class="permalink" href="#n~2"><code class="Fl">-n</code></a></dt>
348 <dd>Attempt to load the bundle but don't install new packfile or update
349 any reference. Can be used to verify the integrity of the bundle.</dd>
350 <dt id="q~4"><a class="permalink" href="#q~4"><code class="Fl">-q</code></a></dt>
351 <dd>Suppress progress reporting output.</dd>
352 <dt id="r~5"><a class="permalink" href="#r~5"><code class="Fl">-r</code></a>
353 <var class="Ar">repository-path</var></dt>
354 <dd>Use the repository at the specified path. If not specified, assume the
355 repository is located at or above the current working directory. If
356 this directory is a <a class="Xr" aria-label="got, section
357 1">got(1)</a> work tree, use the repository path associated with this
364 <h2 class="Sh" id="EXIT_STATUS"><a class="permalink" href="#EXIT_STATUS">EXIT
366 <p class="Pp">The <code class="Nm">gotadmin</code> utility exits 0 on
367 success, and >0 if an error occurs.</p>
370 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
372 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
373 <a class="Xr" aria-label="tog, section 1">tog(1)</a>,
374 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
375 <a class="Xr" aria-label="got.conf, section 5">got.conf(5)</a></p>
378 <h2 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h2>
379 <p class="Pp"><span class="An">Christian Weisgerber</span>
380 <<a class="Mt" href="mailto:naddy@openbsd.org">naddy@openbsd.org</a>>
382 <span class="An">Josh Rickmar</span>
383 <<a class="Mt" href="mailto:jrick@zettaport.com">jrick@zettaport.com</a>>
385 <span class="An">Klemens Nanni</span>
386 <<a class="Mt" href="mailto:kn@openbsd.org">kn@openbsd.org</a>>
388 <span class="An">Omar Polo</span>
389 <<a class="Mt" href="mailto:op@openbsd.org">op@openbsd.org</a>>
391 <span class="An">Ori Bernstein</span>
392 <<a class="Mt" href="mailto:ori@openbsd.org">ori@openbsd.org</a>>
394 <span class="An">Stefan Sperling</span>
395 <<a class="Mt" href="mailto:stsp@openbsd.org">stsp@openbsd.org</a>>
397 <span class="An">Tracey Emery</span>
398 <<a class="Mt" href="mailto:tracey@traceyemery.net">tracey@traceyemery.net</a>></p>
401 <h2 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h2>
402 <p class="Pp"><code class="Nm">gotadmin</code> is a work-in-progress and some
403 features remain to be implemented.</p>
404 <p class="Pp">At present, the user has to fall back on
405 <a class="Xr" aria-label="git, section 1">git(1)</a> to perform some tasks.
407 <ul class="Bl-bullet">
408 <li>Exporting data from repositories requires
409 <a class="Xr" aria-label="git-fast-export, section
410 1">git-fast-export(1)</a>.</li>
411 <li>Importing data into repositories requires
412 <a class="Xr" aria-label="git-fast-import, section
413 1">git-fast-import(1)</a>.</li>
417 <h2 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h2>
418 <p class="Pp">Disk space savings reported by <code class="Cm">gotadmin
419 cleanup</code> will be misleading if the repository contains object files
420 that were hard-linked from another repository. Such hard-links will be
421 created by certain <a class="Xr" aria-label="git, section 1">git(1)</a>
422 commands. By itself, <a class="Xr" aria-label="got, section 1">got(1)</a>
423 will never create hard-linked object files.</p>
426 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
427 line"><span class="foot-left"></span><span class="foot-date">March 11,
428 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
