Ubuntu Manpage: gotadmin — Game of Trees repository administration

name
synopsis
description
exit status
see also
authors
caveats
bugs

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 new repository must be populated before got checkout can be used. The
got import command can be used to populate the new repository with data from a local directory.
Alternatively, on a server running gotd(8), the new repository can be made available to got(1) or
git(1) clients by adding the repository to gotd.conf(5) and restarting gotd(8). Clients may then
clone the new repository from the server, populate the cloned repository, and then populate the
new repository on the server via got send or git push.

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”.

The gotadmin init command is equivalent to got init.

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 and redundant pack files 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. Objects will usually become unreferenced as a result of deleting
branches, tags, or other references with got branch -d, got ref -d, or got fetch -X.

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 are stored in pack files under objects/pack/.

If redundant copies of packed objects exist in loose form, such redundant copies will be purged.
If all the objects of a pack file are present in other pack files, the redundant pack file will
be purged. Pack files will usually become redundant as a result of repacking the repository with
gotadmin pack -a.

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
rebase -X, got histedit -X, or got ref -d.

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.

For compatibility with Git, if a file with the extension .keep exists and corresponds to a pack
file with the extension .pack then this pack file will not be removed.

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 options for gotadmin cleanup are as follows:

-a Delete all redundant loose and packed 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 and redundant pack files, remove any pack
index files which do not have a corresponding pack file.

-q Suppress progress reporting and disk space summary output.

dump [-q] [-r repository-path] [-x reference] [reference ...]
Dump the contents of the repository to standard output in Git bundle format.

The options for gotadmin dump are as follows:

-q Suppress progress reporting output.

-x reference
Exclude objects reachable via the specified reference from the bundle. 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.

load [-nq] [-l bundle-path] [-r repository-path] [reference ...]
Read a Git bundle stream from standard input and load its data into a repository.

If one or more reference arguments are provided then only load the specified references from the
bundle. Otherwise, all references will be loaded.

The options for gotadmin load are as follows:

-l bundle-path
List references available for loading from the bundle at the specified bundle-path and
exit immediately. If the -l option is specified then no reference arguments are allowed.
The -l option is incompatible with the -n option.

-n Attempt to load the bundle but don't install new packfile or update any reference. Can
be used to verify the integrity of the bundle.

-q Suppress progress reporting 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>
     Omar Polo <op@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:

     •   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.

NAME

SYNOPSIS

DESCRIPTION

EXIT STATUS

SEE ALSO

AUTHORS

CAVEATS

BUGS