gotadmin/gotadmin.1

   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 aq
 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 q
 132 Suppress progress reporting output.
 133 .It Fl r Ar repository-path
 134 Use the repository at the specified path.
 135 If not specified, assume the repository is located at or above the current
 136 working directory.
 137 If this directory is a
 138 .Xr got 1
 139 work tree, use the repository path associated with this work tree.
 140 .It Fl x Ar reference
 141 Exclude objects reachable via the specified
 142 .Ar reference
 143 from the pack file.
 144 The
 145 .Ar reference
 146 argument may either specify a specific reference or a reference namespace,
 147 in which case all references within this namespace will be excluded.
 148 The
 149 .Fl x
 150 option may be specified multiple times to build a list of references to exclude.
 151 .Pp
 152 Exclusion takes precedence over inclusion.
 153 If a reference appears in both the included and excluded lists, it will
 154 be excluded.
 155 .El
 156 .Tg ix
 157 .It Cm indexpack Ar packfile-path
 158 .Dl Pq alias: Cm ix
 159 Create a pack index for the pack file at
 160 .Ar packfile-path .
 161 .Pp
 162 A pack index is required for using the corresponding pack file with
 163 .Xr got 1 .
 164 Usually, a pack index will be created by commands such as
 165 .Cm gotadmin pack
 166 or
 167 .Cm got fetch
 168 as part of regular operation.
 169 The
 170 .Cm gotadmin indexpack
 171 command may be used to recover from a corrupt or missing index.
 172 A given pack file will always yield the same bit-identical index.
 173 .Pp
 174 The provided
 175 .Ar packfile-path
 176 must be located within the
 177 .Pa objects/pack/
 178 directory of the repository and should end in
 179 .Pa .pack .
 180 The filename of the corresponding pack index is equivalent, except
 181 that it ends in
 182 .Pa .idx .
 183 .Tg ls
 184 .It Xo
 185 .Cm listpack
 186 .Op Fl hs
 187 .Ar packfile-path
 188 .Xc
 189 .Dl Pq alias: Cm ls
 190 List the contents of the pack file at
 191 .Ar packfile-path .
 192 .Pp
 193 Each object contained in the pack file will be displayed on a single line.
 194 The information shown includes the object ID, object type, object offset,
 195 and object size.
 196 .Pp
 197 If a packed object is deltified against another object, the delta base
 198 will be shown as well.
 199 For offset deltas, the delta base is identified via an offset into the
 200 pack file.
 201 For reference deltas, the delta base is identified via an object ID.
 202 .Pp
 203 The provided
 204 .Ar packfile-path
 205 must be located within the
 206 .Pa objects/pack/
 207 directory of the repository and should end in
 208 .Pa .pack .
 209 The corresponding pack index must exist and can be created with
 210 .Cm gotadmin indexpack
 211 if it is missing.
 212 .Pp
 213 The options for
 214 .Cm gotadmin listpack
 215 are as follows:
 216 .Bl -tag -width Ds
 217 .It Fl h
 218 Show object sizes in human-readable form.
 219 .It Fl s
 220 Display statistics about the pack file after listing objects.
 221 This includes the total number of objects stored in the pack file
 222 and a break-down of the number of objects per object type.
 223 .El
 224 .Tg cl
 225 .It Xo
 226 .Cm cleanup
 227 .Op Fl anpq
 228 .Op Fl r Ar repository-path
 229 .Xc
 230 .Dl Pq alias: Cm cl
 231 Purge unreferenced loose objects from the repository and display
 232 the amount of disk space which has been freed as a result.
 233 .Pp
 234 Unreferenced objects are present in the repository but cannot be
 235 reached via any reference in the entire
 236 .Pa refs/
 237 namespace.
 238 .Pp
 239 Loose objects are stored as individual files beneath the repository's
 240 .Pa objects/
 241 directory,
 242 spread across 256 sub-directories named after the 256 possible
 243 hexadecimal values of the first byte of an object identifier.
 244 .Pp
 245 Packed objects stored in pack files under
 246 .Pa objects/pack/
 247 will not be purged.
 248 However, if redundant copies of packed objects exist in loose form,
 249 such redundant copies will be purged.
 250 .Pp
 251 Objects will usually become unreferenced as a result of deleting
 252 branches or tags with
 253 .Cm got branch -d
 254 or
 255 .Cm got tag -d .
 256 Deleting arbitrary references with
 257 .Cm got ref -d
 258 may also leave unreferenced objects behind.
 259 .Pp
 260 In order to determine the set of objects which are referenced, search
 261 all references for commit objects and tag objects, and traverse the
 262 corresponding tree object hierarchies.
 263 Any loose object IDs not encountered during this search are unreferenced
 264 and thus subject to removal.
 265 Display the number of commits which have been searched to indicate progress.
 266 .Pp
 267 References in the
 268 .Pa refs/got
 269 namespace may prevent objects from being purged.
 270 This includes references in the
 271 .Pa refs/got/worktree
 272 namespace created by
 273 .Cm got checkout
 274 and
 275 .Cm got update ,
 276 as well as references in the
 277 .Pa refs/got/backup
 278 namespace created by
 279 .Cm got rebase
 280 and
 281 .Cm got histedit .
 282 .Cm gotadmin cleanup
 283 will only purge corresponding objects once such references have been
 284 deleted with
 285 .Cm got ref -d .
 286 .Pp
 287 Some Git repositories contain pack index files which lack a corresponding
 288 pack file, which is an inconsistent repository state.
 289 In such cases,
 290 .Cm gotadmin cleanup -p -n
 291 will display a list of affected pack index files.
 292 Whenever possible, the missing pack files should be restored.
 293 If restoring missing pack files is not possible, then affected pack index
 294 files can be removed with
 295 .Cm gotadmin cleanup -p .
 296 .Pp
 297 The
 298 .Dq preciousObjects
 299 Git extension is intended to prevent the removal of objects from a repository.
 300 .Cm gotadmin cleanup
 301 will refuse to operate on repositories where this extension is active.
 302 .Pp
 303 The options for
 304 .Cm gotadmin cleanup
 305 are as follows:
 306 .Bl -tag -width Ds
 307 .It Fl a
 308 Delete all loose objects.
 309 By default, objects which are newer than an implementation-defined
 310 modification timestamp are kept on disk to prevent race conditions
 311 with other commands that add new objects to the repository while
 312 .Cm gotadmin cleanup
 313 is running.
 314 .It Fl n
 315 Display the usual progress output and summary information but do not actually
 316 remove any files from disk.
 317 .It Fl p
 318 Instead of purging unreferenced loose objects, remove any pack index files
 319 which do not have a corresponding pack file.
 320 .It Fl q
 321 Suppress progress reporting and disk space summary output.
 322 .It Fl r Ar repository-path
 323 Use the repository at the specified path.
 324 If not specified, assume the repository is located at or above the current
 325 working directory.
 326 If this directory is a
 327 .Xr got 1
 328 work tree, use the repository path associated with this work tree.
 329 .El
 330 .El
 331 .Sh EXIT STATUS
 332 .Ex -std gotadmin
 333 .Sh SEE ALSO
 334 .Xr got 1 ,
 335 .Xr tog 1 ,
 336 .Xr git-repository 5 ,
 337 .Xr got.conf 5
 338 .Sh AUTHORS
 339 .An Christian Weisgerber Aq Mt naddy@openbsd.org
 340 .An Josh Rickmar Aq Mt jrick@zettaport.com
 341 .An Klemens Nanni Aq Mt kn@openbsd.org
 342 .An Ori Bernstein Aq Mt ori@openbsd.org
 343 .An Stefan Sperling Aq Mt stsp@openbsd.org
 344 .An Tracey Emery Aq Mt tracey@traceyemery.net
 345 .Sh CAVEATS
 346 .Nm
 347 is a work-in-progress and some features remain to be implemented.
 348 .Pp
 349 At present, the user has to fall back on
 350 .Xr git 1
 351 to perform some tasks.
 352 In particular:
 353 .Bl -bullet
 354 .It
 355 Removing redundant or unreferenced packed objects requires
 356 .Xr git-gc 1
 357 and perhaps
 358 .Xr git-repack 1 .
 359 .It
 360 Exporting data from repositories requires
 361 .Xr git-fast-export 1 .
 362 .It
 363 Importing data into repositories requires
 364 .Xr git-fast-import 1 .
 365 .El
 366 .Sh BUGS
 367 Disk space savings reported by
 368 .Cm gotadmin cleanup
 369 will be misleading if the repository contains object files that were
 370 hard-linked from another repository.
 371 Such hard-links will be created by certain
 372 .Xr git 1
 373 commands.
 374 By itself,
 375 .Xr got 1
 376 will never create hard-linked object files.