kmx git

.\"
.\" Copyright (c) 2021 Stefan Sperling
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt GOTADMIN 1
.Os
.Sh NAME
.Nm gotadmin
.Nd Game of Trees repository administration
.Sh SYNOPSIS
.Nm
.Ar command
.Op Fl h
.Op Ar arg ...
.Sh DESCRIPTION
.Nm
is the repository maintenance tool for the
.Xr got 1
version control system.
.Pp
.Xr got 1
stores the history of tracked files in a Git repository, as used
by the Git version control system.
.Nm
provides commands for inspecting and manipulating the on-disk state of
Git repositories.
The repository format is described in
.Xr git-repository 5 .
.Pp
.Nm
provides global and command-specific options.
Global options must precede the command name, and are as follows:
.Bl -tag -width tenletters
.It Fl h
Display usage information and exit immediately.
.It Fl V , -version
Display program version and exit immediately.
.El
.Pp
The commands for
.Nm
are as follows:
.Bl -tag -width checkout
.It Cm info Oo Fl r Ar repository-path Oc
Display information about a repository.
This includes some configuration settings from
.Xr 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.
.Pp
The options for
.Cm gotadmin info
are as follows:
.Bl -tag -width Ds
.It Fl r Ar repository-path
Use the repository at the specified path.
If not specified, assume the repository is located at or above the current
working directory.
.El
.It Cm pack Oo Fl a Oc Oo Fl r Ar repository-path Oc Oo Fl x Ar reference Oc Op Ar 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.
.Pp
If one or more
.Ar reference
arguments is specified, only add objects which are reachable via the specified
references.
Each
.Ar reference
argument may either specify a specific reference or a reference namespace,
in which case all references within this namespace will be used.
.Pp
.Cm gotadmin pack
always ignores references in the
.Pa refs/got/
namespace, effectively treating such references as if they did not refer
to any objects.
.Pp
The options for
.Cm gotadmin pack
are as follows:
.Bl -tag -width Ds
.It Fl 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.
.It Fl r Ar repository-path
Use the repository at the specified path.
If not specified, assume the repository is located at or above the current
working directory.
.It Fl x Ar reference
Exclude objects reachable via the specified
.Ar reference
from the pack file.
The
.Ar reference
argument may either specify a specific reference or a reference namespace,
in which case all references within this namespace will be excluded.
The
.Fl x
option may be specified multiple times to build a list of references to exclude.
.Pp
Exclusion takes precedence over inclusion.
If a reference appears in both the included and excluded lists, it will
be excluded.
.El
.It Cm indexpack Ar packfile-path
Create a pack index for the pack file at
.Ar packfile-path .
.Pp
A pack index is required for using the corresponding pack file with
.Xr got 1 .
Usually, a pack index will be created by commands such as
.Cm gotadmin pack
or
.Cm got fetch
as part of regular operation.
The
.Cm 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.
.Pp
The provided
.Ar packfile-path
must be located within the
.Pa objects/pack/
directory of the repository and should end in
.Pa .pack .
The filename of the corresponding pack index is equivalent, except
that it ends in
.Pa .idx .
.Pp
.It Cm ix
Short alias for
.Cm indexpack .
.It Cm listpack Oo Fl h Oc Oo Fl s Oc Ar packfile-path
List the contents of the pack file at
.Ar packfile-path .
.Pp
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.
.Pp
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.
.Pp
The provided
.Ar packfile-path
must be located within the
.Pa objects/pack/
directory of the repository and should end in
.Pa .pack .
.Pp
The options for
.Cm gotadmin listpack
are as follows:
.Bl -tag -width Ds
.It Fl h
Show object sizes in human-readable form.
.It Fl 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.
.El
.It Cm ls
Short alias for
.Cm listpack .
.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
Purge unreferenced loose objects from the repository and display
the amount of disk space which has been freed as a result.
.Pp
Unreferenced objects are present in the repository but cannot be
reached via any reference in the entire
.Pa refs/
namespace.
.Pp
Loose objects are stored as individual files beneath the repository's
.Pa objects/
directory,
spread across 256 sub-directories named after the 256 possible
hexadecimal values of the first byte of an object identifier.
.Pp
Packed objects stored in pack files under
.Pa objects/pack/ 
will not be purged.
However, if redundant copies of packed objects exist in loose form,
such redundant copies will be purged.
.Pp
Objects will usually become unreferenced as a result of deleting
branches or tags with
.Cm got branch -d
or
.Cm got tag -d .
Deleting arbitrary references with
.Cm got ref -d 
may also leave unreferenced objects behind.
.Pp
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.
.Pp
References in the
.Pa refs/got
namespace may prevent objects from being purged.
This includes references in the
.Pa refs/got/worktree
namespace created by
.Cm got checkout
and
.Cm got update ,
as well as references in the
.Pa refs/got/backup
namespace created by
.Cm got rebase
and
.Cm got histedit .
.Cm gotadmin cleanup
will only purge corresponding objects once such references have been
deleted with
.Cm got ref -d .
.Pp
Some Git repositories contain pack index files which lack a corresponding
pack file, which is an inconsistent repository state.
In such cases,
.Cm 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
.Cm gotadmin cleanup -p .
.Pp
The
.Dq preciousObjects
Git extension is intended to prevent the removal of objects from a repository.
.Cm gotadmin cleanup 
will refuse to operate on repositories where this extension is active.
.Pp
The options for
.Cm gotadmin cleanup
are as follows:
.Bl -tag -width Ds
.It Fl 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
.Cm gotadmin cleanup
is running.
.It Fl p
Instead of purging unreferenced loose objects, remove any pack index files
which do not have a corresponding pack file.
.It Fl n
Display the usual progress output and summary information but do not actually
remove any files from disk.
.It Fl r Ar repository-path
Use the repository at the specified path.
If not specified, assume the repository is located at or above the current
working directory.
.It Fl q
Suppress progress reporting and disk space summary output.
.El
.It Cm cl
Short alias for
.Cm cleanup .
.El
.Sh EXIT STATUS
.Ex -std gotadmin
.Sh SEE ALSO
.Xr got 1 ,
.Xr tog 1 ,
.Xr git-repository 5 ,
.Xr got.conf 5
.Sh AUTHORS
.An Stefan Sperling Aq Mt stsp@openbsd.org
.An Ori Bernstein Aq Mt ori@openbsd.org
.Sh CAVEATS
.Nm
is a work-in-progress and some features remain to be implemented.
.Pp
At present, the user has to fall back on
.Xr git 1
to perform some tasks.
In particular:
.Bl -bullet
.It
Removing redundant or unreferenced packed objects requires
.Xr git-gc 1
and perhaps
.Xr git-repack 1 .
.It
Exporting data from repositories requires
.Xr git-fast-export 1 .
.It
Importing data into repositories requires
.Xr git-fast-import 1 .
.El
.Sh BUGS
Disk space savings reported by
.Cm 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
.Xr git 1
commands.
By itself,
.Xr got 1
will never create hard-linked object files.
thodg/got/gotadmin/gotadmin.1

Commit

gotadmin/gotadmin.1
