'\" t
.\" Title: git-maintenance
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 02/22/2023
.\" Manual: Git Manual
.\" Source: Git 2.30.2
.\" Language: English
.\"
.TH "GIT\-MAINTENANCE" "1" "02/22/2023" "Git 2\&.30\&.2" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-maintenance \- Run tasks to optimize Git repository data
.SH "SYNOPSIS"
.sp
.nf
\fIgit maintenance\fR run []
.fi
.sp
.SH "DESCRIPTION"
.sp
Run tasks to optimize Git repository data, speeding up other Git commands and reducing storage requirements for the repository\&.
.sp
Git commands that add repository data, such as \fBgit add\fR or \fBgit fetch\fR, 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\&.
.sp
The \fBgit maintenance\fR command provides flexibility for how to optimize the Git repository\&.
.SH "SUBCOMMANDS"
.PP
register
.RS 4
Initialize Git config values so any scheduled maintenance will start running on this repository\&. This adds the repository to the
\fBmaintenance\&.repo\fR
config variable in the current user\(cqs global config and enables some recommended configuration values for
\fBmaintenance\&.\&.schedule\fR\&. The tasks that are enabled are safe for running in the background without disrupting foreground processes\&.
.sp
The
\fBregister\fR
subcommand will also set the
\fBmaintenance\&.strategy\fR
config value to
\fBincremental\fR, if this value is not previously set\&. The
\fBincremental\fR
strategy uses the following schedule for each maintenance task:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgc\fR: disabled\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcommit\-graph\fR: hourly\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBprefetch\fR: hourly\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBloose\-objects\fR: daily\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBincremental\-repack\fR: daily\&.
.RE
.sp
\fBgit maintenance register\fR
will also disable foreground maintenance by setting
\fBmaintenance\&.auto = false\fR
in the current repository\&. This config setting will remain after a
\fBgit maintenance unregister\fR
command\&.
.RE
.PP
run
.RS 4
Run one or more maintenance tasks\&. If one or more
\fB\-\-task\fR
options are specified, then those tasks are run in that order\&. Otherwise, the tasks are determined by which
\fBmaintenance\&.\&.enabled\fR
config options are true\&. By default, only
\fBmaintenance\&.gc\&.enabled\fR
is true\&.
.RE
.PP
start
.RS 4
Start running maintenance on the current repository\&. This performs the same config updates as the
\fBregister\fR
subcommand, then updates the background scheduler to run
\fBgit maintenance run \-\-scheduled\fR
on an hourly basis\&.
.RE
.PP
stop
.RS 4
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\&.
.RE
.PP
unregister
.RS 4
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\&.
.RE
.SH "TASKS"
.PP
commit\-graph
.RS 4
The
\fBcommit\-graph\fR
job updates the
\fBcommit\-graph\fR
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
\fB\&.graph\fR
files that were in the previous
\fBcommit\-graph\-chain\fR
file\&. They will be deleted by a later run based on the expiration delay\&.
.RE
.PP
prefetch
.RS 4
The
\fBprefetch\fR
task updates the object directory with the latest objects from all registered remotes\&. For each remote, a
\fBgit fetch\fR
command is run\&. The refmap is custom to avoid updating local or remote branches (those in
\fBrefs/heads\fR
or
\fBrefs/remotes\fR)\&. Instead, the remote refs are stored in
\fBrefs/prefetch//\fR\&. Also, tags are not updated\&.
.sp
This is done to avoid disrupting the remote\-tracking branches\&. The end users expect these refs to stay unmoved unless they initiate a fetch\&. With prefetch task, however, the objects necessary to complete a later real fetch would already be obtained, so the real fetch would go faster\&. In the ideal case, it will just become an update to a bunch of remote\-tracking branches without any object transfer\&.
.RE
.PP
gc
.RS 4
Clean up unnecessary files and optimize the local repository\&. "GC" stands for "garbage collection," but this task performs many smaller tasks\&. This task can be expensive for large repositories, as it repacks all Git objects into a single pack\-file\&. It can also be disruptive in some situations, as it deletes stale data\&. See
\fBgit-gc\fR(1)
for more details on garbage collection in Git\&.
.RE
.PP
loose\-objects
.RS 4
The
\fBloose\-objects\fR
job cleans up loose objects and places them into pack\-files\&. In order to prevent race conditions with concurrent Git commands, it follows a two\-step process\&. First, it deletes any loose objects that already exist in a pack\-file; concurrent Git processes will examine the pack\-file for the object data instead of the loose object\&. Second, it creates a new pack\-file (starting with "loose\-") containing a batch of loose objects\&. The batch size is limited to 50 thousand objects to prevent the job from taking too long on a repository with many loose objects\&. The
\fBgc\fR
task writes unreachable objects as loose objects to be cleaned up by a later step only if they are not re\-added to a pack\-file; for this reason it is not advisable to enable both the
\fBloose\-objects\fR
and
\fBgc\fR
tasks at the same time\&.
.RE
.PP
incremental\-repack
.RS 4
The
\fBincremental\-repack\fR
job repacks the object directory using the
\fBmulti\-pack\-index\fR
feature\&. In order to prevent race conditions with concurrent Git commands, it follows a two\-step process\&. First, it calls
\fBgit multi\-pack\-index expire\fR
to delete pack\-files unreferenced by the
\fBmulti\-pack\-index\fR
file\&. Second, it calls
\fBgit multi\-pack\-index repack\fR
to select several small pack\-files and repack them into a bigger one, and then update the
\fBmulti\-pack\-index\fR
entries that refer to the small pack\-files to refer to the new pack\-file\&. This prepares those small pack\-files for deletion upon the next run of
\fBgit multi\-pack\-index expire\fR\&. The selection of the small pack\-files is such that the expected size of the big pack\-file is at least the batch size; see the
\fB\-\-batch\-size\fR
option for the
\fBrepack\fR
subcommand in
\fBgit-multi-pack-index\fR(1)\&. The default batch\-size is zero, which is a special case that attempts to repack all pack\-files into a single pack\-file\&.
.RE
.SH "OPTIONS"
.PP
\-\-auto
.RS 4
When combined with the
\fBrun\fR
subcommand, run maintenance tasks only if certain thresholds are met\&. For example, the
\fBgc\fR
task runs when the number of loose objects exceeds the number stored in the
\fBgc\&.auto\fR
config setting, or when the number of pack\-files exceeds the
\fBgc\&.autoPackLimit\fR
config setting\&. Not compatible with the
\fB\-\-schedule\fR
option\&.
.RE
.PP
\-\-schedule
.RS 4
When combined with the
\fBrun\fR
subcommand, run maintenance tasks only if certain time conditions are met, as specified by the
\fBmaintenance\&.\&.schedule\fR
config value for each
\fB\fR\&. This config value specifies a number of seconds since the last time that task ran, according to the
\fBmaintenance\&.\&.lastRun\fR
config value\&. The tasks that are tested are those provided by the
\fB\-\-task=\fR
option(s) or those with
\fBmaintenance\&.\&.enabled\fR
set to true\&.
.RE
.PP
\-\-quiet
.RS 4
Do not report progress or other information over
\fBstderr\fR\&.
.RE
.PP
\-\-task=
.RS 4
If this option is specified one or more times, then only run the specified tasks in the specified order\&. If no
\fB\-\-task=\fR
arguments are specified, then only the tasks with
\fBmaintenance\&.\&.enabled\fR
configured as
\fBtrue\fR
are considered\&. See the
\fITASKS\fR
section for the list of accepted
\fB\fR
values\&.
.RE
.SH "TROUBLESHOOTING"
.sp
The \fBgit maintenance\fR command is designed to simplify the repository maintenance patterns while minimizing user wait time during Git commands\&. A variety of configuration options are available to allow customizing this process\&. The default maintenance options focus on operations that complete quickly, even on large repositories\&.
.sp
Users may find some cases where scheduled maintenance tasks do not run as frequently as intended\&. Each \fBgit maintenance run\fR command takes a lock on the repository\(cqs object database, and this prevents other concurrent \fBgit maintenance run\fR commands from running on the same repository\&. Without this safeguard, competing processes could leave the repository in an unpredictable state\&.
.sp
The background maintenance schedule runs \fBgit maintenance run\fR processes on an hourly basis\&. Each run executes the "hourly" tasks\&. At midnight, that process also executes the "daily" tasks\&. At midnight on the first day of the week, that process also executes the "weekly" tasks\&. A single process iterates over each registered repository, performing the scheduled tasks for that frequency\&. Depending on the number of registered repositories and their sizes, this process may take longer than an hour\&. In this case, multiple \fBgit maintenance run\fR commands may run on the same repository at the same time, colliding on the object database lock\&. This results in one of the two tasks not running\&.
.sp
If you find that some maintenance windows are taking longer than one hour to complete, then consider reducing the complexity of your maintenance tasks\&. For example, the \fBgc\fR task is much slower than the \fBincremental\-repack\fR task\&. However, this comes at a cost of a slightly larger object database\&. Consider moving more expensive tasks to be run less frequently\&.
.sp
Expert users may consider scheduling their own maintenance tasks using a different schedule than is available through \fBgit maintenance start\fR and Git configuration options\&. These users should be aware of the object database lock and how concurrent \fBgit maintenance run\fR commands behave\&. Further, the \fBgit gc\fR command should not be combined with \fBgit maintenance run\fR commands\&. \fBgit gc\fR modifies the object database but does not take the lock in the same way as \fBgit maintenance run\fR\&. If possible, use \fBgit maintenance run \-\-task=gc\fR instead of \fBgit gc\fR\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite