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
[-A
hashing-algorithm] [-b
branch] repository-path- Create a new empty repository at the specified
repository-path.
After
gotadmin init
, the new repository must be populated beforegot checkout
can be used. Thegot 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 viagot send
orgit push
.The options for
gotadmin init
are as follows:-A
hashing-algorithm- Configure the repository's hashing-algorithm
used for the computation of Git object IDs. Possible values are
sha1
(the default) orsha256
. -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 togot init
. info
[-r
repository-path]- Display information about a repository. This includes some configuration
settings from got.conf(5), the object ID hashing algorithm, 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.
-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.
-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-
Create a pack index for the pack file at packfile-path.
(alias:
ix
)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
orgot fetch
as part of regular operation. Thegotadmin 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-
List the contents of the pack file at packfile-path.
(alias:
ls
)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]-
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.
(alias:
cl
)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
, orgot 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
andgot update
, as well as references in the refs/got/backup namespace created bygot rebase
andgot histedit
.gotadmin cleanup
will only purge corresponding objects once such references have been deleted withgot rebase -X
,got histedit -X
, orgot 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 withgotadmin 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.
-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.
dump
[-q
] [-r
repository-path] [-x
reference] [reference ...]- Dump the contents of the repository to standard output in Git bundle
format.
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.
The options for
gotadmin
dump
are as follows:-q
- Suppress progress reporting output.
-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.
-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.
-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.
EXIT STATUS
The gotadmin
utility exits 0 on
success, and >0 if an error occurs.
SEE ALSO
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.