bump version number

[got-portable.git] / gotadmin / gotadmin.1

.\"
.\" 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
.Op Fl hV
.Ar command
.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 init Oo Fl A Ar hashing-algorithm Oc Oo Fl b Ar branch Oc Ar repository-path
Create a new empty repository at the specified
.Ar repository-path .
.Pp
After
.Cm gotadmin init ,
the new repository must be populated before
.Cm got checkout
can be used.
The
.Cm got import
command can be used to populate the new repository with data from
a local directory.
Alternatively, on a server running
.Xr gotd 8 ,
the new repository can be made available to
.Xr got 1
or
.Xr git 1
clients by adding the repository to
.Xr gotd.conf 5
and restarting
.Xr 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
.Cm got send
or
.Cm git push .
.Pp
The options for
.Cm gotadmin init
are as follows:
.Bl -tag -width Ds
.It Fl A Ar hashing-algorithm
Configure the repository's
.Ar hashing-algorithm
used for the computation of Git object IDs.
Possible values are
.Cm sha1
.Pq the default
or
.Cm sha256 .
.It Fl b Ar branch
Make the repository's HEAD reference point to the specified
.Ar branch
instead of the default branch
.Dq main .
.El
.Pp
The
.Cm gotadmin init
command is equivalent to
.Cm got init .
.It Cm info Op Fl r Ar repository-path
Display information about a repository.
This includes some configuration settings from
.Xr 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.
.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.
If this directory is a
.Xr got 1
work tree, use the repository path associated with this work tree.
.El
.It Xo
.Cm pack
.Op Fl aDq
.Op Fl r Ar repository-path
.Op Fl x Ar reference
.Op Ar reference ...
.Xc
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 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.
.It Fl q
Suppress progress reporting output.
.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.
If this directory is a
.Xr got 1
work tree, use the repository path associated with this work tree.
.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
.Tg ix
.It Cm indexpack Ar packfile-path
.Dl Pq alias: Cm ix
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 .
.Tg ls
.It Xo
.Cm listpack
.Op Fl hs
.Ar packfile-path
.Xc
.Dl Pq alias: Cm ls
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 .
The corresponding pack index must exist and can be created with
.Cm gotadmin indexpack
if it is missing.
.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
.Tg cl
.It Xo
.Cm cleanup
.Op Fl anpq
.Op Fl r Ar repository-path
.Xc
.Dl Pq alias: Cm 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.
.Pp
Unreferenced objects are present in the repository but cannot be
reached via any reference in the entire
.Pa refs/
namespace.
Objects will usually become unreferenced as a result of deleting
branches, tags, or other references with
.Cm got branch -d ,
.Cm got ref -d ,
or
.Cm got fetch -X .
.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 are stored in pack files under
.Pa objects/pack/ .
.Pp
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
.Nm
.Cm pack Fl a .
.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 rebase -X ,
.Cm got histedit -X ,
or
.Cm got ref -d .
.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
For compatibility with Git, if a file with the extension
.Pa .keep
exists and corresponds to a pack file with the extension
.Pa .pack
then this pack file will not be removed.
.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 options for
.Cm gotadmin cleanup
are as follows:
.Bl -tag -width Ds
.It Fl 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
.Cm gotadmin cleanup
is running.
.It Fl n
Display the usual progress output and summary information but do not actually
remove any files from disk.
.It Fl p
Instead of purging unreferenced loose objects and redundant pack files,
remove any pack index files which do not have a corresponding pack file.
.It Fl q
Suppress progress reporting and disk space summary output.
.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.
If this directory is a
.Xr got 1
work tree, use the repository path associated with this work tree.
.El
.It Xo
.Cm dump
.Op Fl q
.Op Fl r Ar repository-path
.Op Fl x Ar reference
.Op Ar reference ...
.Xc
Dump the contents of the repository to standard output in Git bundle format.
.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
The options for
.Nm
.Cm dump
are as follows:
.Bl -tag -width Ds
.It Fl q
Suppress progress reporting output.
.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.
If this directory is a
.Xr got 1
work tree, use the repository path associated with this work tree.
.It Fl x Ar reference
Exclude objects reachable via the specified
.Ar reference
from the bundle.
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 Xo
.Cm load
.Op Fl nq
.Op Fl l Ar bundle-path
.Op Fl r Ar repository-path
.Op Ar reference ...
.Xc
Read a Git bundle stream from standard input and load its data into
a repository.
.Pp
If one or more
.Ar reference
arguments are provided then only load the specified references
from the bundle.
Otherwise, all references will be loaded.
.Pp
The options for
.Cm gotadmin load
are as follows:
.Bl -tag -width Ds
.It Fl l Ar bundle-path
List references available for loading from the bundle at the specified
.Ar bundle-path
and exit immediately.
If the
.Fl l
option is specified then no
.Ar reference
arguments are allowed.
The
.Fl l
option is incompatible with the
.Fl n
option.
.It Fl 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.
.It Fl q
Suppress progress reporting output.
.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.
If this directory is a
.Xr got 1
work tree, use the repository path associated with this work tree.
.El
.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 Christian Weisgerber Aq Mt naddy@openbsd.org
.An Josh Rickmar Aq Mt jrick@zettaport.com
.An Klemens Nanni Aq Mt kn@openbsd.org
.An Omar Polo Aq Mt op@openbsd.org
.An Ori Bernstein Aq Mt ori@openbsd.org
.An Stefan Sperling Aq Mt stsp@openbsd.org
.An Tracey Emery Aq Mt tracey@traceyemery.net
.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
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.