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>] [<code class="Fl">-q</code>]
91 [<var class="Ar">reference ...</var>]</dt>
92 <dd>Generate a new pack file and a corresponding pack file index. By default,
93 add any loose objects which are reachable via any references to the
94 generated pack file.
95 <p class="Pp">If one or more <var class="Ar">reference</var> arguments is
96 specified, only add objects which are reachable via the specified
97 references. Each <var class="Ar">reference</var> argument may either
98 specify a specific reference or a reference namespace, in which case all
99 references within this namespace will be used.</p>
100 <p class="Pp"><code class="Cm">gotadmin pack</code> always ignores
101 references in the <span class="Pa">refs/got/</span> namespace,
102 effectively treating such references as if they did not refer to any
103 objects.</p>
104 <p class="Pp">The options for <code class="Cm">gotadmin pack</code> are as
105 follows:</p>
106 <dl class="Bl-tag">
107 <dt id="a"><a class="permalink" href="#a"><code class="Fl">-a</code></a></dt>
108 <dd>Add objects to the generated pack file even if they are already packed
109 in a different pack file. Unless this option is specified, only loose
110 objects will be added.</dd>
111 <dt id="r~2"><a class="permalink" href="#r~2"><code class="Fl">-r</code></a>
112 <var class="Ar">repository-path</var></dt>
113 <dd>Use the repository at the specified path. If not specified, assume the
114 repository is located at or above the current working directory. If
115 this directory is a <a class="Xr">got(1)</a> work tree, use the
116 repository path associated with this work tree.</dd>
117 <dt id="x"><a class="permalink" href="#x"><code class="Fl">-x</code></a>
118 <var class="Ar">reference</var></dt>
119 <dd>Exclude objects reachable via the specified
120 <var class="Ar">reference</var> from the pack file. The
121 <var class="Ar">reference</var> argument may either specify a specific
122 reference or a reference namespace, in which case all references
123 within this namespace will be excluded. The <code class="Fl">-x</code>
124 option may be specified multiple times to build a list of references
125 to exclude.
126 <p class="Pp">Exclusion takes precedence over inclusion. If a reference
127 appears in both the included and excluded lists, it will be
128 excluded.</p>
129 </dd>
130 <dt id="q"><a class="permalink" href="#q"><code class="Fl">-q</code></a></dt>
131 <dd>Suppress progress reporting output.</dd>
132 </dl>
133 </dd>
134 <dt id="ix"><a class="permalink" href="#indexpack"><code class="Cm" id="indexpack">indexpack</code></a>
135 <var class="Ar">packfile-path</var></dt>
136 <dd>
137 <div class="Bd Bd-indent"><code class="Li">(alias:
138 <code class="Cm">ix</code>)</code></div>
139 Create a pack index for the pack file at
140 <var class="Ar">packfile-path</var>.
141 <p class="Pp">A pack index is required for using the corresponding pack file
142 with <a class="Xr">got(1)</a>. Usually, a pack index will be created by
143 commands such as <code class="Cm">gotadmin pack</code> or
144 <code class="Cm">got fetch</code> as part of regular operation. The
145 <code class="Cm">gotadmin indexpack</code> command may be used to
146 recover from a corrupt or missing index. A given pack file will always
147 yield the same bit-identical index.</p>
148 <p class="Pp">The provided <var class="Ar">packfile-path</var> must be
149 located within the <span class="Pa">objects/pack/</span> directory of
150 the repository and should end in <span class="Pa">.pack</span>. The
151 filename of the corresponding pack index is equivalent, except that it
152 ends in <span class="Pa">.idx</span>.</p>
153 </dd>
154 <dt id="ls"><a class="permalink" href="#listpack"><code class="Cm" id="listpack">listpack</code></a>
155 [<code class="Fl">-h</code>] [<code class="Fl">-s</code>]
156 <var class="Ar">packfile-path</var></dt>
157 <dd>
158 <div class="Bd Bd-indent"><code class="Li">(alias:
159 <code class="Cm">ls</code>)</code></div>
160 List the contents of the pack file at <var class="Ar">packfile-path</var>.
161 <p class="Pp">Each object contained in the pack file will be displayed on a
162 single line. The information shown includes the object ID, object type,
163 object offset, and object size.</p>
164 <p class="Pp">If a packed object is deltified against another object, the
165 delta base will be shown as well. For offset deltas, the delta base is
166 identified via an offset into the pack file. For reference deltas, the
167 delta base is identified via an object ID.</p>
168 <p class="Pp">The provided <var class="Ar">packfile-path</var> must be
169 located within the <span class="Pa">objects/pack/</span> directory of
170 the repository and should end in <span class="Pa">.pack</span>. The
171 corresponding pack index must exist and can be created with
172 <code class="Cm">gotadmin indexpack</code> if it is missing.</p>
173 <p class="Pp">The options for <code class="Cm">gotadmin listpack</code> are
174 as follows:</p>
175 <dl class="Bl-tag">
176 <dt id="h~2"><a class="permalink" href="#h~2"><code class="Fl">-h</code></a></dt>
177 <dd>Show object sizes in human-readable form.</dd>
178 <dt id="s"><a class="permalink" href="#s"><code class="Fl">-s</code></a></dt>
179 <dd>Display statistics about the pack file after listing objects. This
180 includes the total number of objects stored in the pack file and a
181 break-down of the number of objects per object type.</dd>
182 </dl>
183 </dd>
184 <dt id="cl"><a class="permalink" href="#cleanup"><code class="Cm" id="cleanup">cleanup</code></a>
185 [<code class="Fl">-a</code>] [<code class="Fl">-p</code>]
186 [<code class="Fl">-n</code>] [<code class="Fl">-r</code>
187 <var class="Ar">repository-path</var>] [<code class="Fl">-q</code>]</dt>
188 <dd>
189 <div class="Bd Bd-indent"><code class="Li">(alias:
190 <code class="Cm">cl</code>)</code></div>
191 Purge unreferenced loose objects from the repository and display the amount
192 of disk space which has been freed as a result.
193 <p class="Pp">Unreferenced objects are present in the repository but cannot
194 be reached via any reference in the entire <span class="Pa">refs/</span>
195 namespace.</p>
196 <p class="Pp">Loose objects are stored as individual files beneath the
197 repository's <span class="Pa">objects/</span> directory, spread across
198 256 sub-directories named after the 256 possible hexadecimal values of
199 the first byte of an object identifier.</p>
200 <p class="Pp">Packed objects stored in pack files under
201 <span class="Pa">objects/pack/</span> will not be purged. However, if
202 redundant copies of packed objects exist in loose form, such redundant
203 copies will be purged.</p>
204 <p class="Pp">Objects will usually become unreferenced as a result of
205 deleting branches or tags with <code class="Cm">got branch -d</code> or
206 <code class="Cm">got tag -d</code>. Deleting arbitrary references with
207 <code class="Cm">got ref -d</code> may also leave unreferenced objects
208 behind.</p>
209 <p class="Pp">In order to determine the set of objects which are referenced,
210 search all references for commit objects and tag objects, and traverse
211 the corresponding tree object hierarchies. Any loose object IDs not
212 encountered during this search are unreferenced and thus subject to
213 removal. Display the number of commits which have been searched to
214 indicate progress.</p>
215 <p class="Pp">References in the <span class="Pa">refs/got</span> namespace
216 may prevent objects from being purged. This includes references in the
217 <span class="Pa">refs/got/worktree</span> namespace created by
218 <code class="Cm">got checkout</code> and <code class="Cm">got
219 update</code>, as well as references in the
220 <span class="Pa">refs/got/backup</span> namespace created by
221 <code class="Cm">got rebase</code> and <code class="Cm">got
222 histedit</code>. <code class="Cm">gotadmin cleanup</code> will only
223 purge corresponding objects once such references have been deleted with
224 <code class="Cm">got ref -d</code>.</p>
225 <p class="Pp">Some Git repositories contain pack index files which lack a
226 corresponding pack file, which is an inconsistent repository state. In
227 such cases, <code class="Cm">gotadmin cleanup -p -n</code> will display
228 a list of affected pack index files. Whenever possible, the missing pack
229 files should be restored. If restoring missing pack files is not
230 possible, then affected pack index files can be removed with
231 <code class="Cm">gotadmin cleanup -p</code>.</p>
232 <p class="Pp">The &#x201C;preciousObjects&#x201D; Git extension is intended
233 to prevent the removal of objects from a repository.
234 <code class="Cm">gotadmin cleanup</code> will refuse to operate on
235 repositories where this extension is active.</p>
236 <p class="Pp">The options for <code class="Cm">gotadmin cleanup</code> are
237 as follows:</p>
238 <dl class="Bl-tag">
239 <dt id="a~2"><a class="permalink" href="#a~2"><code class="Fl">-a</code></a></dt>
240 <dd>Delete all loose objects. By default, objects which are newer than an
241 implementation-defined modification timestamp are kept on disk to
242 prevent race conditions with other commands that add new objects to
243 the repository while <code class="Cm">gotadmin cleanup</code> is
244 running.</dd>
245 <dt id="p"><a class="permalink" href="#p"><code class="Fl">-p</code></a></dt>
246 <dd>Instead of purging unreferenced loose objects, remove any pack index
247 files which do not have a corresponding pack file.</dd>
248 <dt id="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
249 <dd>Display the usual progress output and summary information but do not
250 actually remove any files from disk.</dd>
251 <dt id="r~3"><a class="permalink" href="#r~3"><code class="Fl">-r</code></a>
252 <var class="Ar">repository-path</var></dt>
253 <dd>Use the repository at the specified path. If not specified, assume the
254 repository is located at or above the current working directory. If
255 this directory is a <a class="Xr">got(1)</a> work tree, use the
256 repository path associated with this work tree.</dd>
257 <dt id="q~2"><a class="permalink" href="#q~2"><code class="Fl">-q</code></a></dt>
258 <dd>Suppress progress reporting and disk space summary output.</dd>
259 </dl>
260 </dd>
261 </dl>
262 </section>
263 <section class="Sh">
264 <h1 class="Sh" id="EXIT_STATUS"><a class="permalink" href="#EXIT_STATUS">EXIT
265 STATUS</a></h1>
266 <p class="Pp">The <code class="Nm">gotadmin</code> utility exits&#x00A0;0 on
267 success, and&#x00A0;&gt;0 if an error occurs.</p>
268 </section>
269 <section class="Sh">
270 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
271 ALSO</a></h1>
272 <p class="Pp"><a class="Xr">got(1)</a>, <a class="Xr">tog(1)</a>,
273 <a class="Xr">git-repository(5)</a>, <a class="Xr">got.conf(5)</a></p>
274 </section>
275 <section class="Sh">
276 <h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
277 <p class="Pp"><span class="An">Stefan Sperling</span>
278 &lt;<a class="Mt" href="mailto:stsp@openbsd.org">stsp@openbsd.org</a>&gt;
279 <br/>
280 <span class="An">Ori Bernstein</span>
281 &lt;<a class="Mt" href="mailto:ori@openbsd.org">ori@openbsd.org</a>&gt;</p>
282 </section>
283 <section class="Sh">
284 <h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
285 <p class="Pp"><code class="Nm">gotadmin</code> is a work-in-progress and some
286 features remain to be implemented.</p>
287 <p class="Pp">At present, the user has to fall back on <a class="Xr">git(1)</a>
288 to perform some tasks. In particular:</p>
289 <ul class="Bl-bullet">
290 <li>Removing redundant or unreferenced packed objects requires
291 <a class="Xr">git-gc(1)</a> and perhaps
292 <a class="Xr">git-repack(1)</a>.</li>
293 <li>Exporting data from repositories requires
294 <a class="Xr">git-fast-export(1)</a>.</li>
295 <li>Importing data into repositories requires
296 <a class="Xr">git-fast-import(1)</a>.</li>
297 </ul>
298 </section>
299 <section class="Sh">
300 <h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
301 <p class="Pp">Disk space savings reported by <code class="Cm">gotadmin
302 cleanup</code> will be misleading if the repository contains object files
303 that were hard-linked from another repository. Such hard-links will be
304 created by certain <a class="Xr">git(1)</a> commands. By itself,
305 <a class="Xr">got(1)</a> will never create hard-linked object files.</p>
306 </section>
307 </div>
308 <table class="foot">
309 <tr>
310 <td class="foot-date">May 10, 2022</td>
311 <td class="foot-os">OpenBSD 7.1</td>
312 </tr>
313 </table>
314 </body>
315 </html>