Ubuntu Manpage: gotadmin — Game of Trees repository administration

NAME

     gotadmin — Game of Trees repository administration

SYNOPSIS

     gotadmin [-hV] command [arg ...]

DESCRIPTION

gotadmin is the repository maintenance tool for the got(1) version control system.

got(1) stores the history of tracked files in a Git repository, as used by the Git version
control system. gotadmin provides commands for inspecting and manipulating the on-disk
state of Git repositories. The repository format is described in git-repository(5).

gotadmin provides global and command-specific options. Global options must precede the
command name, and are as follows:

-h Display usage information and exit immediately.

-V, --version
Display program version and exit immediately.

The commands for gotadmin are as follows:

init [-b branch] repository-path
Create a new empty repository at the specified repository-path.

After gotadmin init, the got import command must be used to populate the empty
repository before got checkout can be used.

The options for gotadmin init are as follows:

-b branch
Make the repository's HEAD reference point to the specified branch instead
of the default branch “main”.

info [-r repository-path]
Display information about a repository. This includes some configuration settings
from got.conf(5), and the number of objects stored in the repository, in packed or
loose form, as well as the current on-disk size of these objects.

The options for gotadmin info are as follows:

-r repository-path
Use the repository at the specified path. If not specified, assume the
repository is located at or above the current working directory. If this
directory is a got(1) work tree, use the repository path associated with
this work tree.

pack [-aDq] [-r repository-path] [-x reference] [reference ...]
Generate a new pack file and a corresponding pack file index. By default, add any
loose objects which are reachable via any references to the generated pack file.

If one or more reference arguments is specified, only add objects which are
reachable via the specified references. Each reference argument may either
specify a specific reference or a reference namespace, in which case all
references within this namespace will be used.

gotadmin pack always ignores references in the refs/got/ namespace, effectively
treating such references as if they did not refer to any objects.

The options for gotadmin pack are as follows:

-a Add objects to the generated pack file even if they are already packed in
a different pack file. Unless this option is specified, only loose
objects will be added.

-D Force the use of ref-delta representation for deltified objects. If this
option is not specified, offset-deltas will be used to represent deltified
objects.

-q Suppress progress reporting output.

-x reference
Exclude objects reachable via the specified reference from the pack file.
The reference argument may either specify a specific reference or a
reference namespace, in which case all references within this namespace
will be excluded. The -x option may be specified multiple times to build
a list of references to exclude.

Exclusion takes precedence over inclusion. If a reference appears in both
the included and excluded lists, it will be excluded.

indexpack packfile-path
(alias: ix)
Create a pack index for the pack file at packfile-path.

A pack index is required for using the corresponding pack file with got(1).
Usually, a pack index will be created by commands such as gotadmin pack or got
fetch as part of regular operation. The gotadmin indexpack command may be used to
recover from a corrupt or missing index. A given pack file will always yield the
same bit-identical index.

The provided packfile-path must be located within the objects/pack/ directory of
the repository and should end in .pack. The filename of the corresponding pack
index is equivalent, except that it ends in .idx.

listpack [-hs] packfile-path
(alias: ls)
List the contents of the pack file at packfile-path.

Each object contained in the pack file will be displayed on a single line. The
information shown includes the object ID, object type, object offset, and object
size.

If a packed object is deltified against another object, the delta base will be
shown as well. For offset deltas, the delta base is identified via an offset into
the pack file. For reference deltas, the delta base is identified via an object
ID.

The provided packfile-path must be located within the objects/pack/ directory of
the repository and should end in .pack. The corresponding pack index must exist
and can be created with gotadmin indexpack if it is missing.

The options for gotadmin listpack are as follows:

-h Show object sizes in human-readable form.

-s Display statistics about the pack file after listing objects. This
includes the total number of objects stored in the pack file and a break-
down of the number of objects per object type.

cleanup [-anpq] [-r repository-path]
(alias: cl)
Purge unreferenced loose objects from the repository and display the amount of
disk space which has been freed as a result.

Unreferenced objects are present in the repository but cannot be reached via any
reference in the entire refs/ namespace.

Loose objects are stored as individual files beneath the repository's objects/
directory, spread across 256 sub-directories named after the 256 possible
hexadecimal values of the first byte of an object identifier.

Packed objects stored in pack files under objects/pack/ will not be purged.
However, if redundant copies of packed objects exist in loose form, such redundant
copies will be purged.

Objects will usually become unreferenced as a result of deleting branches or tags
with got branch -d or got tag -d. Deleting arbitrary references with got ref -d
may also leave unreferenced objects behind.

In order to determine the set of objects which are referenced, search all
references for commit objects and tag objects, and traverse the corresponding tree
object hierarchies. Any loose object IDs not encountered during this search are
unreferenced and thus subject to removal. Display the number of commits which
have been searched to indicate progress.

References in the refs/got namespace may prevent objects from being purged. This
includes references in the refs/got/worktree namespace created by got checkout and
got update, as well as references in the refs/got/backup namespace created by got
rebase and got histedit. gotadmin cleanup will only purge corresponding objects
once such references have been deleted with got ref -d.

Some Git repositories contain pack index files which lack a corresponding pack
file, which is an inconsistent repository state. In such cases, gotadmin cleanup
-p -n will display a list of affected pack index files. Whenever possible, the
missing pack files should be restored. If restoring missing pack files is not
possible, then affected pack index files can be removed with gotadmin cleanup -p.

The “preciousObjects” Git extension is intended to prevent the removal of objects
from a repository. gotadmin cleanup will refuse to operate on repositories where
this extension is active.

The options for gotadmin cleanup are as follows:

-a Delete all loose objects. By default, objects which are newer than an
implementation-defined modification timestamp are kept on disk to prevent
race conditions with other commands that add new objects to the repository
while gotadmin cleanup is running.

-n Display the usual progress output and summary information but do not
actually remove any files from disk.

-p Instead of purging unreferenced loose objects, remove any pack index files
which do not have a corresponding pack file.

-q Suppress progress reporting and disk space summary output.

EXIT STATUS

     The gotadmin utility exits 0 on success, and >0 if an error occurs.

AUTHORS

     Christian Weisgerber <naddy@openbsd.org>
     Josh Rickmar <jrick@zettaport.com>
     Klemens Nanni <kn@openbsd.org>
     Ori Bernstein <ori@openbsd.org>
     Stefan Sperling <stsp@openbsd.org>
     Tracey Emery <tracey@traceyemery.net>

CAVEATS

     gotadmin is a work-in-progress and some features remain to be implemented.

     At present, the user has to fall back on git(1) to perform some tasks.  In particular:

     •   Removing redundant or unreferenced packed objects requires git-gc(1) and perhaps
         git-repack(1).

     •   Exporting data from repositories requires git-fast-export(1).

     •   Importing data into repositories requires git-fast-import(1).

BUGS

     Disk space savings reported by gotadmin cleanup will be misleading if the repository
     contains object files that were hard-linked from another repository.  Such hard-links will
     be created by certain git(1) commands.  By itself, got(1) will never create hard-linked
     object files.