2 20662ea0 2021-04-10 stsp .\" Copyright (c) 2021 Stefan Sperling
4 20662ea0 2021-04-10 stsp .\" Permission to use, copy, modify, and distribute this software for any
5 20662ea0 2021-04-10 stsp .\" purpose with or without fee is hereby granted, provided that the above
6 20662ea0 2021-04-10 stsp .\" copyright notice and this permission notice appear in all copies.
8 20662ea0 2021-04-10 stsp .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 20662ea0 2021-04-10 stsp .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 20662ea0 2021-04-10 stsp .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 20662ea0 2021-04-10 stsp .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 20662ea0 2021-04-10 stsp .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 20662ea0 2021-04-10 stsp .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 20662ea0 2021-04-10 stsp .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 20662ea0 2021-04-10 stsp .Dd $Mdocdate$
17 20662ea0 2021-04-10 stsp .Dt GOTADMIN 1
20 20662ea0 2021-04-10 stsp .Nm gotadmin
21 20662ea0 2021-04-10 stsp .Nd Game of Trees repository administration
22 20662ea0 2021-04-10 stsp .Sh SYNOPSIS
26 20662ea0 2021-04-10 stsp .Op Ar arg ...
27 20662ea0 2021-04-10 stsp .Sh DESCRIPTION
29 20662ea0 2021-04-10 stsp is the repository maintenance tool for the
31 20662ea0 2021-04-10 stsp version control system.
34 20662ea0 2021-04-10 stsp stores the history of tracked files in a Git repository, as used
35 20662ea0 2021-04-10 stsp by the Git version control system.
37 20662ea0 2021-04-10 stsp provides commands for inspecting and manipulating the on-disk state of
38 20662ea0 2021-04-10 stsp Git repositories.
39 20662ea0 2021-04-10 stsp The repository format is described in
40 20662ea0 2021-04-10 stsp .Xr git-repository 5 .
43 20662ea0 2021-04-10 stsp provides global and command-specific options.
44 20662ea0 2021-04-10 stsp Global options must precede the command name, and are as follows:
45 20662ea0 2021-04-10 stsp .Bl -tag -width tenletters
47 20662ea0 2021-04-10 stsp Display usage information and exit immediately.
48 20662ea0 2021-04-10 stsp .It Fl V , -version
49 20662ea0 2021-04-10 stsp Display program version and exit immediately.
52 20662ea0 2021-04-10 stsp The commands for
54 20662ea0 2021-04-10 stsp are as follows:
55 20662ea0 2021-04-10 stsp .Bl -tag -width checkout
56 02a5c5d0 2022-07-04 stsp .It Cm init Ar repository-path
57 02a5c5d0 2022-07-04 stsp Create a new empty repository at the specified
58 02a5c5d0 2022-07-04 stsp .Ar repository-path .
61 02a5c5d0 2022-07-04 stsp .Cm gotadmin init ,
63 02a5c5d0 2022-07-04 stsp .Cm got import
64 02a5c5d0 2022-07-04 stsp command must be used to populate the empty repository before
65 02a5c5d0 2022-07-04 stsp .Cm got checkout
66 02a5c5d0 2022-07-04 stsp can be used.
67 20662ea0 2021-04-10 stsp .It Cm info Oo Fl r Ar repository-path Oc
68 20662ea0 2021-04-10 stsp Display information about a repository.
69 20662ea0 2021-04-10 stsp This includes some configuration settings from
70 20662ea0 2021-04-10 stsp .Xr got.conf 5 ,
71 20662ea0 2021-04-10 stsp and the number of objects stored in the repository, in packed or
72 20662ea0 2021-04-10 stsp loose form, as well as the current on-disk size of these objects.
74 20662ea0 2021-04-10 stsp The options for
75 20662ea0 2021-04-10 stsp .Cm gotadmin info
76 20662ea0 2021-04-10 stsp are as follows:
77 20662ea0 2021-04-10 stsp .Bl -tag -width Ds
78 20662ea0 2021-04-10 stsp .It Fl r Ar repository-path
79 20662ea0 2021-04-10 stsp Use the repository at the specified path.
80 20662ea0 2021-04-10 stsp If not specified, assume the repository is located at or above the current
81 20662ea0 2021-04-10 stsp working directory.
82 7d69d862 2021-11-15 stsp If this directory is a
84 7d69d862 2021-11-15 stsp work tree, use the repository path associated with this work tree.
86 20e420c8 2022-04-11 stsp .It Cm pack Oo Fl a Oc Oo Fl r Ar repository-path Oc Oo Fl x Ar reference Oc Oo Fl q Oc Op Ar reference ...
87 05118f5a 2021-06-22 stsp Generate a new pack file and a corresponding pack file index.
88 05118f5a 2021-06-22 stsp By default, add any loose objects which are reachable via any references
89 05118f5a 2021-06-22 stsp to the generated pack file.
91 05118f5a 2021-06-22 stsp If one or more
92 05118f5a 2021-06-22 stsp .Ar reference
93 05118f5a 2021-06-22 stsp arguments is specified, only add objects which are reachable via the specified
96 05118f5a 2021-06-22 stsp .Ar reference
97 05118f5a 2021-06-22 stsp argument may either specify a specific reference or a reference namespace,
98 05118f5a 2021-06-22 stsp in which case all references within this namespace will be used.
100 05118f5a 2021-06-22 stsp .Cm gotadmin pack
101 05118f5a 2021-06-22 stsp always ignores references in the
102 05118f5a 2021-06-22 stsp .Pa refs/got/
103 05118f5a 2021-06-22 stsp namespace, effectively treating such references as if they did not refer
104 05118f5a 2021-06-22 stsp to any objects.
106 05118f5a 2021-06-22 stsp The options for
107 05118f5a 2021-06-22 stsp .Cm gotadmin pack
108 05118f5a 2021-06-22 stsp are as follows:
109 05118f5a 2021-06-22 stsp .Bl -tag -width Ds
111 05118f5a 2021-06-22 stsp Add objects to the generated pack file even if they are already packed
112 05118f5a 2021-06-22 stsp in a different pack file.
113 05118f5a 2021-06-22 stsp Unless this option is specified, only loose objects will be added.
114 05118f5a 2021-06-22 stsp .It Fl r Ar repository-path
115 05118f5a 2021-06-22 stsp Use the repository at the specified path.
116 05118f5a 2021-06-22 stsp If not specified, assume the repository is located at or above the current
117 05118f5a 2021-06-22 stsp working directory.
118 7d69d862 2021-11-15 stsp If this directory is a
120 7d69d862 2021-11-15 stsp work tree, use the repository path associated with this work tree.
121 05118f5a 2021-06-22 stsp .It Fl x Ar reference
122 05118f5a 2021-06-22 stsp Exclude objects reachable via the specified
123 05118f5a 2021-06-22 stsp .Ar reference
124 05118f5a 2021-06-22 stsp from the pack file.
126 05118f5a 2021-06-22 stsp .Ar reference
127 05118f5a 2021-06-22 stsp argument may either specify a specific reference or a reference namespace,
128 05118f5a 2021-06-22 stsp in which case all references within this namespace will be excluded.
131 05118f5a 2021-06-22 stsp option may be specified multiple times to build a list of references to exclude.
133 05118f5a 2021-06-22 stsp Exclusion takes precedence over inclusion.
134 05118f5a 2021-06-22 stsp If a reference appears in both the included and excluded lists, it will
135 05118f5a 2021-06-22 stsp be excluded.
137 20e420c8 2022-04-11 stsp Suppress progress reporting output.
140 05118f5a 2021-06-22 stsp .It Cm indexpack Ar packfile-path
141 4683a10b 2021-11-04 kn .Dl Pq alias: Cm ix
142 05118f5a 2021-06-22 stsp Create a pack index for the pack file at
143 05118f5a 2021-06-22 stsp .Ar packfile-path .
145 05118f5a 2021-06-22 stsp A pack index is required for using the corresponding pack file with
146 05118f5a 2021-06-22 stsp .Xr got 1 .
147 05118f5a 2021-06-22 stsp Usually, a pack index will be created by commands such as
148 05118f5a 2021-06-22 stsp .Cm gotadmin pack
150 05118f5a 2021-06-22 stsp .Cm got fetch
151 05118f5a 2021-06-22 stsp as part of regular operation.
153 05118f5a 2021-06-22 stsp .Cm gotadmin indexpack
154 05118f5a 2021-06-22 stsp command may be used to recover from a corrupt or missing index.
155 05118f5a 2021-06-22 stsp A given pack file will always yield the same bit-identical index.
157 05118f5a 2021-06-22 stsp The provided
158 05118f5a 2021-06-22 stsp .Ar packfile-path
159 05118f5a 2021-06-22 stsp must be located within the
160 05118f5a 2021-06-22 stsp .Pa objects/pack/
161 05118f5a 2021-06-22 stsp directory of the repository and should end in
162 05118f5a 2021-06-22 stsp .Pa .pack .
163 05118f5a 2021-06-22 stsp The filename of the corresponding pack index is equivalent, except
164 05118f5a 2021-06-22 stsp that it ends in
167 05118f5a 2021-06-22 stsp .It Cm listpack Oo Fl h Oc Oo Fl s Oc Ar packfile-path
168 4683a10b 2021-11-04 kn .Dl Pq alias: Cm ls
169 05118f5a 2021-06-22 stsp List the contents of the pack file at
170 05118f5a 2021-06-22 stsp .Ar packfile-path .
172 05118f5a 2021-06-22 stsp Each object contained in the pack file will be displayed on a single line.
173 05118f5a 2021-06-22 stsp The information shown includes the object ID, object type, object offset,
174 05118f5a 2021-06-22 stsp and object size.
176 e38d4cde 2022-03-21 naddy If a packed object is deltified against another object, the delta base
177 05118f5a 2021-06-22 stsp will be shown as well.
178 05118f5a 2021-06-22 stsp For offset deltas, the delta base is identified via an offset into the
180 05118f5a 2021-06-22 stsp For reference deltas, the delta base is identified via an object ID.
182 05118f5a 2021-06-22 stsp The provided
183 05118f5a 2021-06-22 stsp .Ar packfile-path
184 05118f5a 2021-06-22 stsp must be located within the
185 05118f5a 2021-06-22 stsp .Pa objects/pack/
186 05118f5a 2021-06-22 stsp directory of the repository and should end in
187 05118f5a 2021-06-22 stsp .Pa .pack .
188 8e26059c 2022-03-10 stsp The corresponding pack index must exist and can be created with
189 8e26059c 2022-03-10 stsp .Cm gotadmin indexpack
190 8e26059c 2022-03-10 stsp if it is missing.
192 05118f5a 2021-06-22 stsp The options for
193 05118f5a 2021-06-22 stsp .Cm gotadmin listpack
194 05118f5a 2021-06-22 stsp are as follows:
195 05118f5a 2021-06-22 stsp .Bl -tag -width Ds
197 05118f5a 2021-06-22 stsp Show object sizes in human-readable form.
199 0c079dbc 2021-10-06 kn Display statistics about the pack file after listing objects.
200 05118f5a 2021-06-22 stsp This includes the total number of objects stored in the pack file
201 05118f5a 2021-06-22 stsp and a break-down of the number of objects per object type.
204 ef8ec606 2021-07-27 stsp .It Cm cleanup Oo Fl a Oc Oo Fl p Oc Oo Fl n Oc Oo Fl r Ar repository-path Oc Oo Fl q Oc
205 4683a10b 2021-11-04 kn .Dl Pq alias: Cm cl
206 b3d68e7f 2021-07-03 stsp Purge unreferenced loose objects from the repository and display
207 b3d68e7f 2021-07-03 stsp the amount of disk space which has been freed as a result.
209 b3d68e7f 2021-07-03 stsp Unreferenced objects are present in the repository but cannot be
210 b3d68e7f 2021-07-03 stsp reached via any reference in the entire
214 b3d68e7f 2021-07-03 stsp Loose objects are stored as individual files beneath the repository's
215 b3d68e7f 2021-07-03 stsp .Pa objects/
217 b3d68e7f 2021-07-03 stsp spread across 256 sub-directories named after the 256 possible
218 b3d68e7f 2021-07-03 stsp hexadecimal values of the first byte of an object identifier.
220 b3d68e7f 2021-07-03 stsp Packed objects stored in pack files under
221 0c079dbc 2021-10-06 kn .Pa objects/pack/
222 b3d68e7f 2021-07-03 stsp will not be purged.
223 b3d68e7f 2021-07-03 stsp However, if redundant copies of packed objects exist in loose form,
224 b3d68e7f 2021-07-03 stsp such redundant copies will be purged.
226 b3d68e7f 2021-07-03 stsp Objects will usually become unreferenced as a result of deleting
227 b3d68e7f 2021-07-03 stsp branches or tags with
228 b3d68e7f 2021-07-03 stsp .Cm got branch -d
230 b3d68e7f 2021-07-03 stsp .Cm got tag -d .
231 b3d68e7f 2021-07-03 stsp Deleting arbitrary references with
232 0c079dbc 2021-10-06 kn .Cm got ref -d
233 b3d68e7f 2021-07-03 stsp may also leave unreferenced objects behind.
235 b3d68e7f 2021-07-03 stsp In order to determine the set of objects which are referenced, search
236 b3d68e7f 2021-07-03 stsp all references for commit objects and tag objects, and traverse the
237 b3d68e7f 2021-07-03 stsp corresponding tree object hierarchies.
238 b3d68e7f 2021-07-03 stsp Any loose object IDs not encountered during this search are unreferenced
239 b3d68e7f 2021-07-03 stsp and thus subject to removal.
240 b3d68e7f 2021-07-03 stsp Display the number of commits which have been searched to indicate progress.
242 b3d68e7f 2021-07-03 stsp References in the
243 b3d68e7f 2021-07-03 stsp .Pa refs/got
244 b3d68e7f 2021-07-03 stsp namespace may prevent objects from being purged.
245 b3d68e7f 2021-07-03 stsp This includes references in the
246 b3d68e7f 2021-07-03 stsp .Pa refs/got/worktree
247 b3d68e7f 2021-07-03 stsp namespace created by
248 b3d68e7f 2021-07-03 stsp .Cm got checkout
250 b3d68e7f 2021-07-03 stsp .Cm got update ,
251 b3d68e7f 2021-07-03 stsp as well as references in the
252 b3d68e7f 2021-07-03 stsp .Pa refs/got/backup
253 b3d68e7f 2021-07-03 stsp namespace created by
254 b3d68e7f 2021-07-03 stsp .Cm got rebase
256 b3d68e7f 2021-07-03 stsp .Cm got histedit .
257 b3d68e7f 2021-07-03 stsp .Cm gotadmin cleanup
258 b3d68e7f 2021-07-03 stsp will only purge corresponding objects once such references have been
259 b3d68e7f 2021-07-03 stsp deleted with
260 b3d68e7f 2021-07-03 stsp .Cm got ref -d .
262 1124fe40 2021-07-07 stsp Some Git repositories contain pack index files which lack a corresponding
263 1124fe40 2021-07-07 stsp pack file, which is an inconsistent repository state.
264 1124fe40 2021-07-07 stsp In such cases,
265 1124fe40 2021-07-07 stsp .Cm gotadmin cleanup -p -n
266 1124fe40 2021-07-07 stsp will display a list of affected pack index files.
267 e38d4cde 2022-03-21 naddy Whenever possible, the missing pack files should be restored.
268 e38d4cde 2022-03-21 naddy If restoring missing pack files is not possible, then affected pack index
269 1124fe40 2021-07-07 stsp files can be removed with
270 1124fe40 2021-07-07 stsp .Cm gotadmin cleanup -p .
273 9188bd78 2021-07-03 stsp .Dq preciousObjects
274 9188bd78 2021-07-03 stsp Git extension is intended to prevent the removal of objects from a repository.
275 0c079dbc 2021-10-06 kn .Cm gotadmin cleanup
276 9188bd78 2021-07-03 stsp will refuse to operate on repositories where this extension is active.
278 b3d68e7f 2021-07-03 stsp The options for
279 d4445ca5 2021-07-03 stsp .Cm gotadmin cleanup
280 b3d68e7f 2021-07-03 stsp are as follows:
281 b3d68e7f 2021-07-03 stsp .Bl -tag -width Ds
283 ef8ec606 2021-07-27 stsp Delete all loose objects.
284 ef8ec606 2021-07-27 stsp By default, objects which are newer than an implementation-defined
285 ef8ec606 2021-07-27 stsp modification timestamp are kept on disk to prevent race conditions
286 ef8ec606 2021-07-27 stsp with other commands that add new objects to the repository while
287 ef8ec606 2021-07-27 stsp .Cm gotadmin cleanup
288 ef8ec606 2021-07-27 stsp is running.
290 1124fe40 2021-07-07 stsp Instead of purging unreferenced loose objects, remove any pack index files
291 1124fe40 2021-07-07 stsp which do not have a corresponding pack file.
293 b3d68e7f 2021-07-03 stsp Display the usual progress output and summary information but do not actually
294 1124fe40 2021-07-07 stsp remove any files from disk.
295 b3d68e7f 2021-07-03 stsp .It Fl r Ar repository-path
296 b3d68e7f 2021-07-03 stsp Use the repository at the specified path.
297 b3d68e7f 2021-07-03 stsp If not specified, assume the repository is located at or above the current
298 b3d68e7f 2021-07-03 stsp working directory.
299 7d69d862 2021-11-15 stsp If this directory is a
301 7d69d862 2021-11-15 stsp work tree, use the repository path associated with this work tree.
303 b3d68e7f 2021-07-03 stsp Suppress progress reporting and disk space summary output.
306 20662ea0 2021-04-10 stsp .Sh EXIT STATUS
307 20662ea0 2021-04-10 stsp .Ex -std gotadmin
308 20662ea0 2021-04-10 stsp .Sh SEE ALSO
309 20662ea0 2021-04-10 stsp .Xr got 1 ,
310 20662ea0 2021-04-10 stsp .Xr tog 1 ,
311 20662ea0 2021-04-10 stsp .Xr git-repository 5 ,
312 20662ea0 2021-04-10 stsp .Xr got.conf 5
313 20662ea0 2021-04-10 stsp .Sh AUTHORS
314 8ca658b9 2022-07-05 stsp .An Christian Weisgerber Aq Mt naddy@openbsd.org
315 8ca658b9 2022-07-05 stsp .An Josh Rickmar Aq Mt jrick@zettaport.com
316 8ca658b9 2022-07-05 stsp .An Klemens Nanni Aq Mt kn@openbsd.org
317 05118f5a 2021-06-22 stsp .An Ori Bernstein Aq Mt ori@openbsd.org
318 8ca658b9 2022-07-05 stsp .An Stefan Sperling Aq Mt stsp@openbsd.org
319 8ca658b9 2022-07-05 stsp .An Tracey Emery Aq Mt tracey@traceyemery.net
320 7e36bc2b 2021-06-25 stsp .Sh CAVEATS
322 7e36bc2b 2021-06-25 stsp is a work-in-progress and some features remain to be implemented.
324 7e36bc2b 2021-06-25 stsp At present, the user has to fall back on
326 7e36bc2b 2021-06-25 stsp to perform some tasks.
327 7e36bc2b 2021-06-25 stsp In particular:
328 7e36bc2b 2021-06-25 stsp .Bl -bullet
330 b3d68e7f 2021-07-03 stsp Removing redundant or unreferenced packed objects requires
331 b3d68e7f 2021-07-03 stsp .Xr git-gc 1
332 b3d68e7f 2021-07-03 stsp and perhaps
333 b3d68e7f 2021-07-03 stsp .Xr git-repack 1 .
335 7e36bc2b 2021-06-25 stsp Exporting data from repositories requires
336 7e36bc2b 2021-06-25 stsp .Xr git-fast-export 1 .
338 7e36bc2b 2021-06-25 stsp Importing data into repositories requires
339 7e36bc2b 2021-06-25 stsp .Xr git-fast-import 1 .
342 aaf7c342 2021-07-03 stsp Disk space savings reported by
343 aaf7c342 2021-07-03 stsp .Cm gotadmin cleanup
344 aaf7c342 2021-07-03 stsp will be misleading if the repository contains object files that were
345 aaf7c342 2021-07-03 stsp hard-linked from another repository.
346 aaf7c342 2021-07-03 stsp Such hard-links will be created by certain
351 aaf7c342 2021-07-03 stsp will never create hard-linked object files.
