Blob


1 .\"
2 .\" Copyright (c) 2021 Stefan Sperling
3 .\"
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd $Mdocdate$
17 .Dt GOTADMIN 1
18 .Os
19 .Sh NAME
20 .Nm gotadmin
21 .Nd Game of Trees repository administration
22 .Sh SYNOPSIS
23 .Nm
24 .Op Fl hV
25 .Ar command
26 .Op Ar arg ...
27 .Sh DESCRIPTION
28 .Nm
29 is the repository maintenance tool for the
30 .Xr got 1
31 version control system.
32 .Pp
33 .Xr got 1
34 stores the history of tracked files in a Git repository, as used
35 by the Git version control system.
36 .Nm
37 provides commands for inspecting and manipulating the on-disk state of
38 Git repositories.
39 The repository format is described in
40 .Xr git-repository 5 .
41 .Pp
42 .Nm
43 provides global and command-specific options.
44 Global options must precede the command name, and are as follows:
45 .Bl -tag -width tenletters
46 .It Fl h
47 Display usage information and exit immediately.
48 .It Fl V , -version
49 Display program version and exit immediately.
50 .El
51 .Pp
52 The commands for
53 .Nm
54 are as follows:
55 .Bl -tag -width checkout
56 .It Cm init Oo Fl b Ar branch Oc Ar repository-path
57 Create a new empty repository at the specified
58 .Ar repository-path .
59 .Pp
60 After
61 .Cm gotadmin init ,
62 the
63 .Cm got import
64 command must be used to populate the empty repository before
65 .Cm got checkout
66 can be used.
67 .Pp
68 The options for
69 .Cm gotadmin init
70 are as follows:
71 .Bl -tag -width Ds
72 .It Fl b Ar branch
73 Make the repository's HEAD reference point to the specified
74 .Ar branch
75 instead of the default branch
76 .Dq main .
77 .El
78 .It Cm info Op Fl r Ar repository-path
79 Display information about a repository.
80 This includes some configuration settings from
81 .Xr got.conf 5 ,
82 and the number of objects stored in the repository, in packed or
83 loose form, as well as the current on-disk size of these objects.
84 .Pp
85 The options for
86 .Cm gotadmin info
87 are as follows:
88 .Bl -tag -width Ds
89 .It Fl r Ar repository-path
90 Use the repository at the specified path.
91 If not specified, assume the repository is located at or above the current
92 working directory.
93 If this directory is a
94 .Xr got 1
95 work tree, use the repository path associated with this work tree.
96 .El
97 .It Xo
98 .Cm pack
99 .Op Fl aDq
100 .Op Fl r Ar repository-path
101 .Op Fl x Ar reference
102 .Op Ar reference ...
103 .Xc
104 Generate a new pack file and a corresponding pack file index.
105 By default, add any loose objects which are reachable via any references
106 to the generated pack file.
107 .Pp
108 If one or more
109 .Ar reference
110 arguments is specified, only add objects which are reachable via the specified
111 references.
112 Each
113 .Ar reference
114 argument may either specify a specific reference or a reference namespace,
115 in which case all references within this namespace will be used.
116 .Pp
117 .Cm gotadmin pack
118 always ignores references in the
119 .Pa refs/got/
120 namespace, effectively treating such references as if they did not refer
121 to any objects.
122 .Pp
123 The options for
124 .Cm gotadmin pack
125 are as follows:
126 .Bl -tag -width Ds
127 .It Fl a
128 Add objects to the generated pack file even if they are already packed
129 in a different pack file.
130 Unless this option is specified, only loose objects will be added.
131 .It Fl D
132 Force the use of ref-delta representation for deltified objects.
133 If this option is not specified, offset-deltas will be used to represent
134 deltified objects.
135 .It Fl q
136 Suppress progress reporting output.
137 .It Fl r Ar repository-path
138 Use the repository at the specified path.
139 If not specified, assume the repository is located at or above the current
140 working directory.
141 If this directory is a
142 .Xr got 1
143 work tree, use the repository path associated with this work tree.
144 .It Fl x Ar reference
145 Exclude objects reachable via the specified
146 .Ar reference
147 from the pack file.
148 The
149 .Ar reference
150 argument may either specify a specific reference or a reference namespace,
151 in which case all references within this namespace will be excluded.
152 The
153 .Fl x
154 option may be specified multiple times to build a list of references to exclude.
155 .Pp
156 Exclusion takes precedence over inclusion.
157 If a reference appears in both the included and excluded lists, it will
158 be excluded.
159 .El
160 .Tg ix
161 .It Cm indexpack Ar packfile-path
162 .Dl Pq alias: Cm ix
163 Create a pack index for the pack file at
164 .Ar packfile-path .
165 .Pp
166 A pack index is required for using the corresponding pack file with
167 .Xr got 1 .
168 Usually, a pack index will be created by commands such as
169 .Cm gotadmin pack
170 or
171 .Cm got fetch
172 as part of regular operation.
173 The
174 .Cm gotadmin indexpack
175 command may be used to recover from a corrupt or missing index.
176 A given pack file will always yield the same bit-identical index.
177 .Pp
178 The provided
179 .Ar packfile-path
180 must be located within the
181 .Pa objects/pack/
182 directory of the repository and should end in
183 .Pa .pack .
184 The filename of the corresponding pack index is equivalent, except
185 that it ends in
186 .Pa .idx .
187 .Tg ls
188 .It Xo
189 .Cm listpack
190 .Op Fl hs
191 .Ar packfile-path
192 .Xc
193 .Dl Pq alias: Cm ls
194 List the contents of the pack file at
195 .Ar packfile-path .
196 .Pp
197 Each object contained in the pack file will be displayed on a single line.
198 The information shown includes the object ID, object type, object offset,
199 and object size.
200 .Pp
201 If a packed object is deltified against another object, the delta base
202 will be shown as well.
203 For offset deltas, the delta base is identified via an offset into the
204 pack file.
205 For reference deltas, the delta base is identified via an object ID.
206 .Pp
207 The provided
208 .Ar packfile-path
209 must be located within the
210 .Pa objects/pack/
211 directory of the repository and should end in
212 .Pa .pack .
213 The corresponding pack index must exist and can be created with
214 .Cm gotadmin indexpack
215 if it is missing.
216 .Pp
217 The options for
218 .Cm gotadmin listpack
219 are as follows:
220 .Bl -tag -width Ds
221 .It Fl h
222 Show object sizes in human-readable form.
223 .It Fl s
224 Display statistics about the pack file after listing objects.
225 This includes the total number of objects stored in the pack file
226 and a break-down of the number of objects per object type.
227 .El
228 .Tg cl
229 .It Xo
230 .Cm cleanup
231 .Op Fl anpq
232 .Op Fl r Ar repository-path
233 .Xc
234 .Dl Pq alias: Cm cl
235 Purge unreferenced loose objects and redundant pack files from the
236 repository and display the amount of disk space which has been freed
237 as a result.
238 .Pp
239 Unreferenced objects are present in the repository but cannot be
240 reached via any reference in the entire
241 .Pa refs/
242 namespace.
243 Objects will usually become unreferenced as a result of deleting
244 branches, tags, or other references with
245 .Cm got branch -d ,
246 .Cm got ref -d ,
247 or
248 .Cm got fetch -X .
249 .Pp
250 Loose objects are stored as individual files beneath the repository's
251 .Pa objects/
252 directory,
253 spread across 256 sub-directories named after the 256 possible
254 hexadecimal values of the first byte of an object identifier.
255 .Pp
256 Packed objects are stored in pack files under
257 .Pa objects/pack/ .
258 .Pp
259 If redundant copies of packed objects exist in loose form, such
260 redundant copies will be purged.
261 If all the objects of a pack file are present in other pack files,
262 the redundant pack file will be purged.
263 Pack files will usually become redundant as a result of repacking the
264 repository with
265 .Nm
266 .Cm pack Fl a .
267 .Pp
268 References in the
269 .Pa refs/got
270 namespace may prevent objects from being purged.
271 This includes references in the
272 .Pa refs/got/worktree
273 namespace created by
274 .Cm got checkout
275 and
276 .Cm got update ,
277 as well as references in the
278 .Pa refs/got/backup
279 namespace created by
280 .Cm got rebase
281 and
282 .Cm got histedit .
283 .Cm gotadmin cleanup
284 will only purge corresponding objects once such references have been
285 deleted with
286 .Cm got rebase -X ,
287 .Cm got histedit -X ,
288 or
289 .Cm got ref -d .
290 .Pp
291 The
292 .Dq preciousObjects
293 Git extension is intended to prevent the removal of objects from a repository.
294 .Cm gotadmin cleanup
295 will refuse to operate on repositories where this extension is active.
296 .Pp
297 For compatibility with Git, if a file with the extension
298 .Pa .keep
299 exists and corresponds to a pack file with the extension
300 .Pa .pack
301 then this pack file will not be removed.
302 .Pp
303 Some Git repositories contain pack index files which lack a corresponding
304 pack file, which is an inconsistent repository state.
305 In such cases,
306 .Cm gotadmin cleanup -p -n
307 will display a list of affected pack index files.
308 Whenever possible, the missing pack files should be restored.
309 If restoring missing pack files is not possible, then affected pack index
310 files can be removed with
311 .Cm gotadmin cleanup -p .
312 .Pp
313 The options for
314 .Cm gotadmin cleanup
315 are as follows:
316 .Bl -tag -width Ds
317 .It Fl a
318 Delete all loose objects.
319 By default, objects which are newer than an implementation-defined
320 modification timestamp are kept on disk to prevent race conditions
321 with other commands that add new objects to the repository while
322 .Cm gotadmin cleanup
323 is running.
324 .It Fl n
325 Display the usual progress output and summary information but do not actually
326 remove any files from disk.
327 .It Fl p
328 Instead of purging unreferenced loose objects and redundant pack files,
329 remove any pack index files which do not have a corresponding pack file.
330 .It Fl q
331 Suppress progress reporting and disk space summary output.
332 .It Fl r Ar repository-path
333 Use the repository at the specified path.
334 If not specified, assume the repository is located at or above the current
335 working directory.
336 If this directory is a
337 .Xr got 1
338 work tree, use the repository path associated with this work tree.
339 .El
340 .It Xo
341 .Cm dump
342 .Op Fl q
343 .Op Fl r Ar repository-path
344 .Op Fl x Ar reference
345 .Op Ar reference ...
346 .Xc
347 Dump the contents of the repository to standard output in Git bundle format.
348 .Pp
349 If one or more
350 .Ar reference
351 arguments is specified, only add objects which are reachable via the specified
352 references.
353 Each
354 .Ar reference
355 argument may either specify a specific reference or a reference namespace,
356 in which case all references within this namespace will be used.
357 .Pp
358 The options for
359 .Nm
360 .Cm dump
361 are as follows:
362 .Bl -tag -width Ds
363 .It Fl q
364 Suppress progress reporting output.
365 .It Fl r Ar repository-path
366 Use the repository at the specified path.
367 If not specified, assume the repository is located at or above the current
368 working directory.
369 If this directory is a
370 .Xr got 1
371 work tree, use the repository path associated with this work tree.
372 .It Fl x Ar reference
373 Exclude objects reachable via the specified
374 .Ar reference
375 from the bundle.
376 The
377 .Ar reference
378 argument may either specify a specific reference or a reference namespace,
379 in which case all references within this namespace will be excluded.
380 The
381 .Fl x
382 option may be specified multiple times to build a list of references to exclude.
383 .Pp
384 Exclusion takes precedence over inclusion.
385 If a reference appears in both the included and excluded lists, it will
386 be excluded.
387 .El
388 .It Xo
389 .Cm load
390 .Op Fl nq
391 .Op Fl l Ar bundle-path
392 .Op Fl r Ar repository-path
393 .Op Ar reference ...
394 .Xc
395 Read a Git bundle stream from standard input and load its data into
396 a repository.
397 .Pp
398 If one or more
399 .Ar reference
400 arguments are provided then only load the specified references
401 from the bundle.
402 Otherwise, all references will be loaded.
403 .Pp
404 The options for
405 .Cm gotadmin load
406 are as follows:
407 .Bl -tag -width Ds
408 .It Fl l Ar bundle-path
409 List references available for loading from the bundle at the specified
410 .Ar bundle-path
411 and exit immediately.
412 If the
413 .Fl l
414 option is specified then no
415 .Ar reference
416 arguments are allowed.
417 The
418 .Fl l
419 option is incompatible with the
420 .Fl n
421 option.
422 .It Fl n
423 Attempt to load the bundle but don't install new packfile or update any
424 reference.
425 Can be used to verify the integrity of the bundle.
426 .It Fl q
427 Suppress progress reporting output.
428 .It Fl r Ar repository-path
429 Use the repository at the specified path.
430 If not specified, assume the repository is located at or above the
431 current working directory.
432 If this directory is a
433 .Xr got 1
434 work tree, use the repository path associated with this work tree.
435 .El
436 .El
437 .Sh EXIT STATUS
438 .Ex -std gotadmin
439 .Sh SEE ALSO
440 .Xr got 1 ,
441 .Xr tog 1 ,
442 .Xr git-repository 5 ,
443 .Xr got.conf 5
444 .Sh AUTHORS
445 .An Christian Weisgerber Aq Mt naddy@openbsd.org
446 .An Josh Rickmar Aq Mt jrick@zettaport.com
447 .An Klemens Nanni Aq Mt kn@openbsd.org
448 .An Omar Polo Aq Mt op@openbsd.org
449 .An Ori Bernstein Aq Mt ori@openbsd.org
450 .An Stefan Sperling Aq Mt stsp@openbsd.org
451 .An Tracey Emery Aq Mt tracey@traceyemery.net
452 .Sh CAVEATS
453 .Nm
454 is a work-in-progress and some features remain to be implemented.
455 .Pp
456 At present, the user has to fall back on
457 .Xr git 1
458 to perform some tasks.
459 In particular:
460 .Bl -bullet
461 .It
462 Exporting data from repositories requires
463 .Xr git-fast-export 1 .
464 .It
465 Importing data into repositories requires
466 .Xr git-fast-import 1 .
467 .El
468 .Sh BUGS
469 Disk space savings reported by
470 .Cm gotadmin cleanup
471 will be misleading if the repository contains object files that were
472 hard-linked from another repository.
473 Such hard-links will be created by certain
474 .Xr git 1
475 commands.
476 By itself,
477 .Xr got 1
478 will never create hard-linked object files.