git-maintenance(1)
==================

NAME
----
git-maintenance - Run tasks to optimize Git repository data


SYNOPSIS
--------
[verse]
'git maintenance' run [<options>]
'git maintenance' start [--scheduler=<scheduler>]
'git maintenance' (stop|register|unregister) [<options>]


DESCRIPTION
-----------
Run tasks to optimize Git repository data, speeding up other Git commands
and reducing storage requirements for the repository.

Git commands that add repository data, such as `git add` or `git fetch`,
are optimized for a responsive user experience. These commands do not take
time to optimize the Git data, since such optimizations scale with the full
size of the repository while these user commands each perform a relatively
small action.

The `git maintenance` command provides flexibility for how to optimize the
Git repository.

SUBCOMMANDS
-----------

run::
	Run one or more maintenance tasks. If one or more `--task` options
	are specified, then those tasks are run in that order. Otherwise,
	the tasks are determined by which `maintenance.<task>.enabled`
	config options are true. By default, only `maintenance.gc.enabled`
	is true.

start::
	Start running maintenance on the current repository. This performs
	the same config updates as the `register` subcommand, then updates
	the background scheduler to run `git maintenance run --scheduled`
	on an hourly basis.

stop::
	Halt the background maintenance schedule. The current repository
	is not removed from the list of maintained repositories, in case
	the background maintenance is restarted later.

register::
	Initialize Git config values so any scheduled maintenance will start
	running on this repository. This adds the repository to the
	`maintenance.repo` config variable in the current user's global config,
	or the config specified by --config-file option, and enables some
	recommended configuration values for `maintenance.<task>.schedule`. The
	tasks that are enabled are safe for running in the background without
	disrupting foreground processes.
+
The `register` subcommand will also set the `maintenance.strategy` config
value to `incremental`, if this value is not previously set. The
`incremental` strategy uses the following schedule for each maintenance
task:
+
--
* `gc`: disabled.
* `commit-graph`: hourly.
* `prefetch`: hourly.
* `loose-objects`: daily.
* `incremental-repack`: daily.
--
+
`git maintenance register` will also disable foreground maintenance by
setting `maintenance.auto = false` in the current repository. This config
setting will remain after a `git maintenance unregister` command.

unregister::
	Remove the current repository from background maintenance. This
	only removes the repository from the configured list. It does not
	stop the background maintenance processes from running.
+
The `unregister` subcommand will report an error if the current repository
is not already registered. Use the `--force` option to return success even
when the current repository is not registered.

TASKS
-----

commit-graph::
	The `commit-graph` job updates the `commit-graph` files incrementally,
	then verifies that the written data is correct. The incremental
	write is safe to run alongside concurrent Git processes since it
	will not expire `.graph` files that were in the previous
	`commit-graph-chain` file. They will be deleted by a later run based
	on the expiration delay.

prefetch::
	The `prefetch` task updates the object directory with the latest
	objects from all registered remotes. For each remote, a `git fetch`
	command is run. The configured refspec is modified to place all
	requested refs within `refs/prefetch/`. Also, tags are not updated.
+
This is done to avoid disrupting the remote-tracking branches. The end users
expect these refs to stay unmoved unless they initiate a fetch.  However,
with the prefetch task, the objects necessary to complete a later real fetch
would already be obtained, making the real fetch faster.  In the ideal case,
it will just become an update to