1 <!DOCTYPE html>
2 <html>
3 <head>
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>
8 </head>
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.
23 -->
24 <body>
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">
30 <section class="Sh">
31 <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 <p class="Pp"><code class="Nm">gotadmin</code> &#x2014;
33 <span class="Nd" role="doc-subtitle">Game of Trees repository
34 administration</span></p>
35 </section>
36 <section class="Sh">
37 <h2 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h2>
38 <table class="Nm">
39 <tr>
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>
43 </tr>
44 </table>
45 </section>
46 <section class="Sh">
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
50 control system.</p>
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
59 are as follows:</p>
60 <dl class="Bl-tag">
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>
66 </dl>
67 <p class="Pp">The commands for <code class="Nm">gotadmin</code> are as
68 follows:</p>
69 <dl class="Bl-tag">
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
78 used.</p>
79 <p class="Pp">The options for <code class="Cm">gotadmin init</code> are as
80 follows:</p>
81 <dl class="Bl-tag">
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 &#x201C;main&#x201D;.</dd>
87 </dl>
88 </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
95 objects.
96 <p class="Pp">The options for <code class="Cm">gotadmin info</code> are as
97 follows:</p>
98 <dl class="Bl-tag">
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
105 work tree.</dd>
106 </dl>
107 </dd>
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
114 generated pack file.
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
123 objects.</p>
124 <p class="Pp">The options for <code class="Cm">gotadmin pack</code> are as
125 follows:</p>
126 <dl class="Bl-tag">
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
143 work tree.</dd>
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
152 to exclude.
153 <p class="Pp">Exclusion takes precedence over inclusion. If a reference
154 appears in both the included and excluded lists, it will be
155 excluded.</p>
156 </dd>
157 </dl>
158 </dd>
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>
161 <dd>
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>
178 </dd>
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>
181 <dd>
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
198 as follows:</p>
199 <dl class="Bl-tag">
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>
206 </dl>
207 </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>
211 <dd>
212 <div class="Bd Bd-indent"><code class="Li">(alias:
213 <code class="Cm">cl</code>)</code></div>
214 Purge unreferenced loose objects from the repository and display the amount
215 of disk space which has been freed as a result.
216 <p class="Pp">Unreferenced objects are present in the repository but cannot
217 be reached via any reference in the entire <span class="Pa">refs/</span>
218 namespace.</p>
219 <p class="Pp">Loose objects are stored as individual files beneath the
220 repository's <span class="Pa">objects/</span> directory, spread across
221 256 sub-directories named after the 256 possible hexadecimal values of
222 the first byte of an object identifier.</p>
223 <p class="Pp">Packed objects stored in pack files under
224 <span class="Pa">objects/pack/</span> will not be purged. However, if
225 redundant copies of packed objects exist in loose form, such redundant
226 copies will be purged.</p>
227 <p class="Pp">Objects will usually become unreferenced as a result of
228 deleting branches or tags with <code class="Cm">got branch -d</code> or
229 <code class="Cm">got tag -d</code>. Deleting arbitrary references with
230 <code class="Cm">got ref -d</code> may also leave unreferenced objects
231 behind.</p>
232 <p class="Pp">In order to determine the set of objects which are referenced,
233 search all references for commit objects and tag objects, and traverse
234 the corresponding tree object hierarchies. Any loose object IDs not
235 encountered during this search are unreferenced and thus subject to
236 removal. Display the number of commits which have been searched to
237 indicate progress.</p>
238 <p class="Pp">References in the <span class="Pa">refs/got</span> namespace
239 may prevent objects from being purged. This includes references in the
240 <span class="Pa">refs/got/worktree</span> namespace created by
241 <code class="Cm">got checkout</code> and <code class="Cm">got
242 update</code>, as well as references in the
243 <span class="Pa">refs/got/backup</span> namespace created by
244 <code class="Cm">got rebase</code> and <code class="Cm">got
245 histedit</code>. <code class="Cm">gotadmin cleanup</code> will only
246 purge corresponding objects once such references have been deleted with
247 <code class="Cm">got ref -d</code>.</p>
248 <p class="Pp">Some Git repositories contain pack index files which lack a
249 corresponding pack file, which is an inconsistent repository state. In
250 such cases, <code class="Cm">gotadmin cleanup -p -n</code> will display
251 a list of affected pack index files. Whenever possible, the missing pack
252 files should be restored. If restoring missing pack files is not
253 possible, then affected pack index files can be removed with
254 <code class="Cm">gotadmin cleanup -p</code>.</p>
255 <p class="Pp">The &#x201C;preciousObjects&#x201D; Git extension is intended
256 to prevent the removal of objects from a repository.
257 <code class="Cm">gotadmin cleanup</code> will refuse to operate on
258 repositories where this extension is active.</p>
259 <p class="Pp">The options for <code class="Cm">gotadmin cleanup</code> are
260 as follows:</p>
261 <dl class="Bl-tag">
262 <dt id="a~2"><a class="permalink" href="#a~2"><code class="Fl">-a</code></a></dt>
263 <dd>Delete all loose objects. By default, objects which are newer than an
264 implementation-defined modification timestamp are kept on disk to
265 prevent race conditions with other commands that add new objects to
266 the repository while <code class="Cm">gotadmin cleanup</code> is
267 running.</dd>
268 <dt id="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
269 <dd>Display the usual progress output and summary information but do not
270 actually remove any files from disk.</dd>
271 <dt id="p"><a class="permalink" href="#p"><code class="Fl">-p</code></a></dt>
272 <dd>Instead of purging unreferenced loose objects, remove any pack index
273 files which do not have a corresponding pack file.</dd>
274 <dt id="q~2"><a class="permalink" href="#q~2"><code class="Fl">-q</code></a></dt>
275 <dd>Suppress progress reporting and disk space summary output.</dd>
276 <dt id="r~3"><a class="permalink" href="#r~3"><code class="Fl">-r</code></a>
277 <var class="Ar">repository-path</var></dt>
278 <dd>Use the repository at the specified path. If not specified, assume the
279 repository is located at or above the current working directory. If
280 this directory is a <a class="Xr" aria-label="got, section
281 1">got(1)</a> work tree, use the repository path associated with this
282 work tree.</dd>
283 </dl>
284 </dd>
285 </dl>
286 </section>
287 <section class="Sh">
288 <h2 class="Sh" id="EXIT_STATUS"><a class="permalink" href="#EXIT_STATUS">EXIT
289 STATUS</a></h2>
290 <p class="Pp">The <code class="Nm">gotadmin</code> utility exits&#x00A0;0 on
291 success, and&#x00A0;&gt;0 if an error occurs.</p>
292 </section>
293 <section class="Sh">
294 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
295 ALSO</a></h2>
296 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
297 <a class="Xr" aria-label="tog, section 1">tog(1)</a>,
298 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
299 <a class="Xr" aria-label="got.conf, section 5">got.conf(5)</a></p>
300 </section>
301 <section class="Sh">
302 <h2 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h2>
303 <p class="Pp"><span class="An">Christian Weisgerber</span>
304 &lt;<a class="Mt" href=""></a>&gt;
305 <br/>
306 <span class="An">Josh Rickmar</span>
307 &lt;<a class="Mt" href=""></a>&gt;
308 <br/>
309 <span class="An">Klemens Nanni</span>
310 &lt;<a class="Mt" href=""></a>&gt;
311 <br/>
312 <span class="An">Ori Bernstein</span>
313 &lt;<a class="Mt" href=""></a>&gt;
314 <br/>
315 <span class="An">Stefan Sperling</span>
316 &lt;<a class="Mt" href=""></a>&gt;
317 <br/>
318 <span class="An">Tracey Emery</span>
319 &lt;<a class="Mt" href=""></a>&gt;</p>
320 </section>
321 <section class="Sh">
322 <h2 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h2>
323 <p class="Pp"><code class="Nm">gotadmin</code> is a work-in-progress and some
324 features remain to be implemented.</p>
325 <p class="Pp">At present, the user has to fall back on
326 <a class="Xr" aria-label="git, section 1">git(1)</a> to perform some tasks.
327 In particular:</p>
328 <ul class="Bl-bullet">
329 <li>Removing redundant or unreferenced packed objects requires
330 <a class="Xr" aria-label="git-gc, section 1">git-gc(1)</a> and perhaps
331 <a class="Xr" aria-label="git-repack, section 1">git-repack(1)</a>.</li>
332 <li>Exporting data from repositories requires
333 <a class="Xr" aria-label="git-fast-export, section
334 1">git-fast-export(1)</a>.</li>
335 <li>Importing data into repositories requires
336 <a class="Xr" aria-label="git-fast-import, section
337 1">git-fast-import(1)</a>.</li>
338 </ul>
339 </section>
340 <section class="Sh">
341 <h2 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h2>
342 <p class="Pp">Disk space savings reported by <code class="Cm">gotadmin
343 cleanup</code> will be misleading if the repository contains object files
344 that were hard-linked from another repository. Such hard-links will be
345 created by certain <a class="Xr" aria-label="git, section 1">git(1)</a>
346 commands. By itself, <a class="Xr" aria-label="got, section 1">got(1)</a>
347 will never create hard-linked object files.</p>
348 </section>
349 </main>
350 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
351 line"><span class="foot-left"></span><span class="foot-date">February 22,
352 2023</span> <span class="foot-os">OpenBSD 7.2</span></div>
353 </body>
354 </html>