|
NAME | SYNOPSIS | DESCRIPTION | SUBCOMMANDS | TASKS | OPTIONS | TROUBLESHOOTING | GIT | COLOPHON |
|
|
|
GIT-MAINTENANCE(1) Git Manual GIT-MAINTENANCE(1)
git-maintenance - Run tasks to optimize Git repository data
git maintenance run [<options>]
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.
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 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 subcomand 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.
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.
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.
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 refmap is custom to avoid
updating local or remote branches (those in refs/heads or
refs/remotes). Instead, the remote refs are stored in
refs/prefetch/<remote>/. 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. 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 bunch of
remote-tracking branches without any object transfer.
gc
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 git-gc(1) for more details on
garbage collection in Git.
loose-objects
The loose-objects 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 gc 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
loose-objects and gc tasks at the same time.
incremental-repack
The incremental-repack job repacks the object directory using
the multi-pack-index feature. In order to prevent race
conditions with concurrent Git commands, it follows a
two-step process. First, it calls git multi-pack-index expire
to delete pack-files unreferenced by the multi-pack-index
file. Second, it calls git multi-pack-index repack to select
several small pack-files and repack them into a bigger one,
and then update the multi-pack-index 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 git multi-pack-index expire. 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 --batch-size
option for the repack subcommand in git-multi-pack-index(1).
The default batch-size is zero, which is a special case that
attempts to repack all pack-files into a single pack-file.
--auto
When combined with the run subcommand, run maintenance tasks
only if certain thresholds are met. For example, the gc task
runs when the number of loose objects exceeds the number
stored in the gc.auto config setting, or when the number of
pack-files exceeds the gc.autoPackLimit config setting. Not
compatible with the --schedule option.
--schedule
When combined with the run subcommand, run maintenance tasks
only if certain time conditions are met, as specified by the
maintenance.<task>.schedule config value for each <task>.
This config value specifies a number of seconds since the
last time that task ran, according to the
maintenance.<task>.lastRun config value. The tasks that are
tested are those provided by the --task=<task> option(s) or
those with maintenance.<task>.enabled set to true.
--quiet
Do not report progress or other information over stderr.
--task=<task>
If this option is specified one or more times, then only run
the specified tasks in the specified order. If no
--task=<task> arguments are specified, then only the tasks
with maintenance.<task>.enabled configured as true are
considered. See the TASKS section for the list of accepted
<task> values.
The git maintenance 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.
Users may find some cases where scheduled maintenance tasks do
not run as frequently as intended. Each git maintenance run
command takes a lock on the repository’s object database, and
this prevents other concurrent git maintenance run commands from
running on the same repository. Without this safeguard, competing
processes could leave the repository in an unpredictable state.
The background maintenance schedule runs git maintenance run
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 git maintenance run 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.
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 gc task is much slower
than the incremental-repack task. However, this comes at a cost
of a slightly larger object database. Consider moving more
expensive tasks to be run less frequently.
Expert users may consider scheduling their own maintenance tasks
using a different schedule than is available through git
maintenance start and Git configuration options. These users
should be aware of the object database lock and how concurrent
git maintenance run commands behave. Further, the git gc command
should not be combined with git maintenance run commands. git gc
modifies the object database but does not take the lock in the
same way as git maintenance run. If possible, use git maintenance
run --task=gc instead of git gc.
Part of the git(1) suite
This page is part of the git (Git distributed version control
system) project. Information about the project can be found at
⟨http://git-scm.com/⟩. If you have a bug report for this manual
page, see ⟨http://git-scm.com/community⟩. This page was obtained
from the project's upstream Git repository
⟨https://github.com/git/git.git⟩ on 2020-12-18. (At that time,
the date of the most recent commit that was found in the
repository was 2020-12-17.) If you discover any rendering
problems in this HTML version of the page, or you believe there
is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
Git 2.30.0.rc0.82.gb 12/18/2020 GIT-MAINTENANCE(1)
Pages that refer to this page: git(1), git-clone(1)
|
HTML rendering created 2020-12-21 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|