Blob


1 <!DOCTYPE html>
2 <html>
3 <!-- This is an automatically generated file. Do not edit.
4 Copyright (c) 2021 Stefan Sperling
6 Permission to use, copy, modify, and distribute this software for any
7 purpose with or without fee is hereby granted, provided that the above
8 copyright notice and this permission notice appear in all copies.
10 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 -->
18 <head>
19 <meta charset="utf-8"/>
20 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
21 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
22 <title>GOTADMIN(1)</title>
23 </head>
24 <body>
25 <table class="head">
26 <tr>
27 <td class="head-ltitle">GOTADMIN(1)</td>
28 <td class="head-vol">General Commands Manual</td>
29 <td class="head-rtitle">GOTADMIN(1)</td>
30 </tr>
31 </table>
32 <div class="manual-text">
33 <section class="Sh">
34 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
35 <p class="Pp"><code class="Nm">gotadmin</code> &#x2014; <span class="Nd">Game of
36 Trees repository administration</span></p>
37 </section>
38 <section class="Sh">
39 <h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
40 <table class="Nm">
41 <tr>
42 <td><code class="Nm">gotadmin</code></td>
43 <td><var class="Ar">command</var> [<code class="Fl">-h</code>]
44 [<var class="Ar">arg ...</var>]</td>
45 </tr>
46 </table>
47 </section>
48 <section class="Sh">
49 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
50 <p class="Pp"><code class="Nm">gotadmin</code> is the repository maintenance
51 tool for the <a class="Xr">got(1)</a> version control system.</p>
52 <p class="Pp"><a class="Xr">got(1)</a> stores the history of tracked files in a
53 Git repository, as used by the Git version control system.
54 <code class="Nm">gotadmin</code> provides commands for inspecting and
55 manipulating the on-disk state of Git repositories. The repository format is
56 described in <a class="Xr">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="info"><a class="permalink" href="#info"><code class="Cm">info</code></a>
71 [<code class="Fl">-r</code> <var class="Ar">repository-path</var>]</dt>
72 <dd>Display information about a repository. This includes some configuration
73 settings from <a class="Xr">got.conf(5)</a>, and the number of objects
74 stored in the repository, in packed or loose form, as well as the current
75 on-disk size of these objects.
76 <p class="Pp">The options for <code class="Cm">gotadmin info</code> are as
77 follows:</p>
78 <dl class="Bl-tag">
79 <dt id="r"><a class="permalink" href="#r"><code class="Fl">-r</code></a>
80 <var class="Ar">repository-path</var></dt>
81 <dd>Use the repository at the specified path. If not specified, assume the
82 repository is located at or above the current working directory. If
83 this directory is a <a class="Xr">got(1)</a> work tree, use the
84 repository path associated with this work tree.</dd>
85 </dl>
86 </dd>
87 <dt id="pack"><a class="permalink" href="#pack"><code class="Cm">pack</code></a>
88 [<code class="Fl">-a</code>] [<code class="Fl">-r</code>
89 <var class="Ar">repository-path</var>] [<code class="Fl">-x</code>
90 <var class="Ar">reference</var>] [<var class="Ar">reference ...</var>]</dt>
91 <dd>Generate a new pack file and a corresponding pack file index. By default,
92 add any loose objects which are reachable via any references to the
93 generated pack file.
94 <p class="Pp">If one or more <var class="Ar">reference</var> arguments is
95 specified, only add objects which are reachable via the specified
96 references. Each <var class="Ar">reference</var> argument may either
97 specify a specific reference or a reference namespace, in which case all
98 references within this namespace will be used.</p>
99 <p class="Pp"><code class="Cm">gotadmin pack</code> always ignores
100 references in the <span class="Pa">refs/got/</span> namespace,
101 effectively treating such references as if they did not refer to any
102 objects.</p>
103 <p class="Pp">The options for <code class="Cm">gotadmin pack</code> are as
104 follows:</p>
105 <dl class="Bl-tag">
106 <dt id="a"><a class="permalink" href="#a"><code class="Fl">-a</code></a></dt>
107 <dd>Add objects to the generated pack file even if they are already packed
108 in a different pack file. Unless this option is specified, only loose
109 objects will be added.</dd>
110 <dt id="r~2"><a class="permalink" href="#r~2"><code class="Fl">-r</code></a>
111 <var class="Ar">repository-path</var></dt>
112 <dd>Use the repository at the specified path. If not specified, assume the
113 repository is located at or above the current working directory. If
114 this directory is a <a class="Xr">got(1)</a> work tree, use the
115 repository path associated with this work tree.</dd>
116 <dt id="x"><a class="permalink" href="#x"><code class="Fl">-x</code></a>
117 <var class="Ar">reference</var></dt>
118 <dd>Exclude objects reachable via the specified
119 <var class="Ar">reference</var> from the pack file. The
120 <var class="Ar">reference</var> argument may either specify a specific
121 reference or a reference namespace, in which case all references
122 within this namespace will be excluded. The <code class="Fl">-x</code>
123 option may be specified multiple times to build a list of references
124 to exclude.
125 <p class="Pp">Exclusion takes precedence over inclusion. If a reference
126 appears in both the included and excluded lists, it will be
127 excluded.</p>
128 </dd>
129 </dl>
130 </dd>
131 <dt id="ix"><a class="permalink" href="#indexpack"><code class="Cm" id="indexpack">indexpack</code></a>
132 <var class="Ar">packfile-path</var></dt>
133 <dd>
134 <div class="Bd Bd-indent"><code class="Li">(alias:
135 <code class="Cm">ix</code>)</code></div>
136 Create a pack index for the pack file at
137 <var class="Ar">packfile-path</var>.
138 <p class="Pp">A pack index is required for using the corresponding pack file
139 with <a class="Xr">got(1)</a>. Usually, a pack index will be created by
140 commands such as <code class="Cm">gotadmin pack</code> or
141 <code class="Cm">got fetch</code> as part of regular operation. The
142 <code class="Cm">gotadmin indexpack</code> command may be used to
143 recover from a corrupt or missing index. A given pack file will always
144 yield the same bit-identical index.</p>
145 <p class="Pp">The provided <var class="Ar">packfile-path</var> must be
146 located within the <span class="Pa">objects/pack/</span> directory of
147 the repository and should end in <span class="Pa">.pack</span>. The
148 filename of the corresponding pack index is equivalent, except that it
149 ends in <span class="Pa">.idx</span>.</p>
150 </dd>
151 <dt id="ls"><a class="permalink" href="#listpack"><code class="Cm" id="listpack">listpack</code></a>
152 [<code class="Fl">-h</code>] [<code class="Fl">-s</code>]
153 <var class="Ar">packfile-path</var></dt>
154 <dd>
155 <div class="Bd Bd-indent"><code class="Li">(alias:
156 <code class="Cm">ls</code>)</code></div>
157 List the contents of the pack file at <var class="Ar">packfile-path</var>.
158 <p class="Pp">Each object contained in the pack file will be displayed on a
159 single line. The information shown includes the object ID, object type,
160 object offset, and object size.</p>
161 <p class="Pp">If a packed object is deltified against another object the
162 delta base will be shown as well. For offset deltas, the delta base is
163 identified via an offset into the pack file. For reference deltas, the
164 delta base is identified via an object ID.</p>
165 <p class="Pp">The provided <var class="Ar">packfile-path</var> must be
166 located within the <span class="Pa">objects/pack/</span> directory of
167 the repository and should end in <span class="Pa">.pack</span>.</p>
168 <p class="Pp">The options for <code class="Cm">gotadmin listpack</code> are
169 as follows:</p>
170 <dl class="Bl-tag">
171 <dt id="h~2"><a class="permalink" href="#h~2"><code class="Fl">-h</code></a></dt>
172 <dd>Show object sizes in human-readable form.</dd>
173 <dt id="s"><a class="permalink" href="#s"><code class="Fl">-s</code></a></dt>
174 <dd>Display statistics about the pack file after listing objects. This
175 includes the total number of objects stored in the pack file and a
176 break-down of the number of objects per object type.</dd>
177 </dl>
178 </dd>
179 <dt id="cl"><a class="permalink" href="#cleanup"><code class="Cm" id="cleanup">cleanup</code></a>
180 [<code class="Fl">-a</code>] [<code class="Fl">-p</code>]
181 [<code class="Fl">-n</code>] [<code class="Fl">-r</code>
182 <var class="Ar">repository-path</var>] [<code class="Fl">-q</code>]</dt>
183 <dd>
184 <div class="Bd Bd-indent"><code class="Li">(alias:
185 <code class="Cm">cl</code>)</code></div>
186 Purge unreferenced loose objects from the repository and display the amount
187 of disk space which has been freed as a result.
188 <p class="Pp">Unreferenced objects are present in the repository but cannot
189 be reached via any reference in the entire <span class="Pa">refs/</span>
190 namespace.</p>
191 <p class="Pp">Loose objects are stored as individual files beneath the
192 repository's <span class="Pa">objects/</span> directory, spread across
193 256 sub-directories named after the 256 possible hexadecimal values of
194 the first byte of an object identifier.</p>
195 <p class="Pp">Packed objects stored in pack files under
196 <span class="Pa">objects/pack/</span> will not be purged. However, if
197 redundant copies of packed objects exist in loose form, such redundant
198 copies will be purged.</p>
199 <p class="Pp">Objects will usually become unreferenced as a result of
200 deleting branches or tags with <code class="Cm">got branch -d</code> or
201 <code class="Cm">got tag -d</code>. Deleting arbitrary references with
202 <code class="Cm">got ref -d</code> may also leave unreferenced objects
203 behind.</p>
204 <p class="Pp">In order to determine the set of objects which are referenced,
205 search all references for commit objects and tag objects, and traverse
206 the corresponding tree object hierarchies. Any loose object IDs not
207 encountered during this search are unreferenced and thus subject to
208 removal. Display the number of commits which have been searched to
209 indicate progress.</p>
210 <p class="Pp">References in the <span class="Pa">refs/got</span> namespace
211 may prevent objects from being purged. This includes references in the
212 <span class="Pa">refs/got/worktree</span> namespace created by
213 <code class="Cm">got checkout</code> and <code class="Cm">got
214 update</code>, as well as references in the
215 <span class="Pa">refs/got/backup</span> namespace created by
216 <code class="Cm">got rebase</code> and <code class="Cm">got
217 histedit</code>. <code class="Cm">gotadmin cleanup</code> will only
218 purge corresponding objects once such references have been deleted with
219 <code class="Cm">got ref -d</code>.</p>
220 <p class="Pp">Some Git repositories contain pack index files which lack a
221 corresponding pack file, which is an inconsistent repository state. In
222 such cases, <code class="Cm">gotadmin cleanup -p -n</code> will display
223 a list of affected pack index files. Whenever possible the missing pack
224 files should be restored. If restoring missing pack files is not
225 possible then affected pack index files can be removed with
226 <code class="Cm">gotadmin cleanup -p</code>.</p>
227 <p class="Pp">The &#x201C;preciousObjects&#x201D; Git extension is intended
228 to prevent the removal of objects from a repository.
229 <code class="Cm">gotadmin cleanup</code> will refuse to operate on
230 repositories where this extension is active.</p>
231 <p class="Pp">The options for <code class="Cm">gotadmin cleanup</code> are
232 as follows:</p>
233 <dl class="Bl-tag">
234 <dt id="a~2"><a class="permalink" href="#a~2"><code class="Fl">-a</code></a></dt>
235 <dd>Delete all loose objects. By default, objects which are newer than an
236 implementation-defined modification timestamp are kept on disk to
237 prevent race conditions with other commands that add new objects to
238 the repository while <code class="Cm">gotadmin cleanup</code> is
239 running.</dd>
240 <dt id="p"><a class="permalink" href="#p"><code class="Fl">-p</code></a></dt>
241 <dd>Instead of purging unreferenced loose objects, remove any pack index
242 files which do not have a corresponding pack file.</dd>
243 <dt id="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
244 <dd>Display the usual progress output and summary information but do not
245 actually remove any files from disk.</dd>
246 <dt id="r~3"><a class="permalink" href="#r~3"><code class="Fl">-r</code></a>
247 <var class="Ar">repository-path</var></dt>
248 <dd>Use the repository at the specified path. If not specified, assume the
249 repository is located at or above the current working directory. If
250 this directory is a <a class="Xr">got(1)</a> work tree, use the
251 repository path associated with this work tree.</dd>
252 <dt id="q"><a class="permalink" href="#q"><code class="Fl">-q</code></a></dt>
253 <dd>Suppress progress reporting and disk space summary output.</dd>
254 </dl>
255 </dd>
256 </dl>
257 </section>
258 <section class="Sh">
259 <h1 class="Sh" id="EXIT_STATUS"><a class="permalink" href="#EXIT_STATUS">EXIT
260 STATUS</a></h1>
261 <p class="Pp">The <code class="Nm">gotadmin</code> utility exits&#x00A0;0 on
262 success, and&#x00A0;&gt;0 if an error occurs.</p>
263 </section>
264 <section class="Sh">
265 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
266 ALSO</a></h1>
267 <p class="Pp"><a class="Xr">got(1)</a>, <a class="Xr">tog(1)</a>,
268 <a class="Xr">git-repository(5)</a>, <a class="Xr">got.conf(5)</a></p>
269 </section>
270 <section class="Sh">
271 <h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
272 <p class="Pp"><span class="An">Stefan Sperling</span>
273 &lt;<a class="Mt" href="mailto:stsp@openbsd.org">stsp@openbsd.org</a>&gt;
274 <br/>
275 <span class="An">Ori Bernstein</span>
276 &lt;<a class="Mt" href="mailto:ori@openbsd.org">ori@openbsd.org</a>&gt;</p>
277 </section>
278 <section class="Sh">
279 <h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
280 <p class="Pp"><code class="Nm">gotadmin</code> is a work-in-progress and some
281 features remain to be implemented.</p>
282 <p class="Pp">At present, the user has to fall back on <a class="Xr">git(1)</a>
283 to perform some tasks. In particular:</p>
284 <ul class="Bl-bullet">
285 <li>Removing redundant or unreferenced packed objects requires
286 <a class="Xr">git-gc(1)</a> and perhaps
287 <a class="Xr">git-repack(1)</a>.</li>
288 <li>Exporting data from repositories requires
289 <a class="Xr">git-fast-export(1)</a>.</li>
290 <li>Importing data into repositories requires
291 <a class="Xr">git-fast-import(1)</a>.</li>
292 </ul>
293 </section>
294 <section class="Sh">
295 <h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
296 <p class="Pp">Disk space savings reported by <code class="Cm">gotadmin
297 cleanup</code> will be misleading if the repository contains object files
298 that were hard-linked from another repository. Such hard-links will be
299 created by certain <a class="Xr">git(1)</a> commands. By itself,
300 <a class="Xr">got(1)</a> will never create hard-linked object files.</p>
301 </section>
302 </div>
303 <table class="foot">
304 <tr>
305 <td class="foot-date">November 23, 2021</td>
306 <td class="foot-os">OpenBSD 7.0</td>
307 </tr>
308 </table>
309 </body>
310 </html>