18d89fe25c
In b6a8d09f6d (gc docs: include the "gc.*" section from "config" in
"gc", 2019-04-07) the "git gc" documentation was made to include the
config/gc.txt in its "CONFIGURATION" section. We do that in several
other places, but "git gc" was the only one with a blurb above the
include to orient the reader.
We don't want readers to carefully scrutinize "git-config(1)" and
"git-gc(1)" looking for discrepancies, instead we should tell them
that the latter includes a part of the former.
This change formalizes that wording in two new templates to be
included, one for the "git gc" case where the entire section is
included from "git-config(1)", and another for when the inclusion of
"git-config(1)" follows discussion unique to that documentation. In
order to use that re-arrange the order of those being discussed in the
"git-merge(1)" documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Reviewed-by: Matheus Tavares <matheus.bernardino@usp.br>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
167 lines
5.8 KiB
Plaintext
167 lines
5.8 KiB
Plaintext
git-gc(1)
|
|
=========
|
|
|
|
NAME
|
|
----
|
|
git-gc - Cleanup unnecessary files and optimize the local repository
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
Runs a number of housekeeping tasks within the current repository,
|
|
such as compressing file revisions (to reduce disk space and increase
|
|
performance), removing unreachable objects which may have been
|
|
created from prior invocations of 'git add', packing refs, pruning
|
|
reflog, rerere metadata or stale working trees. May also update ancillary
|
|
indexes such as the commit-graph.
|
|
|
|
When common porcelain operations that create objects are run, they
|
|
will check whether the repository has grown substantially since the
|
|
last maintenance, and if so run `git gc` automatically. See `gc.auto`
|
|
below for how to disable this behavior.
|
|
|
|
Running `git gc` manually should only be needed when adding objects to
|
|
a repository without regularly running such porcelain commands, to do
|
|
a one-off repository optimization, or e.g. to clean up a suboptimal
|
|
mass-import. See the "PACKFILE OPTIMIZATION" section in
|
|
linkgit:git-fast-import[1] for more details on the import case.
|
|
|
|
OPTIONS
|
|
-------
|
|
|
|
--aggressive::
|
|
Usually 'git gc' runs very quickly while providing good disk
|
|
space utilization and performance. This option will cause
|
|
'git gc' to more aggressively optimize the repository at the expense
|
|
of taking much more time. The effects of this optimization are
|
|
mostly persistent. See the "AGGRESSIVE" section below for details.
|
|
|
|
--auto::
|
|
With this option, 'git gc' checks whether any housekeeping is
|
|
required; if not, it exits without performing any work.
|
|
+
|
|
See the `gc.auto` option in the "CONFIGURATION" section below for how
|
|
this heuristic works.
|
|
+
|
|
Once housekeeping is triggered by exceeding the limits of
|
|
configuration options such as `gc.auto` and `gc.autoPackLimit`, all
|
|
other housekeeping tasks (e.g. rerere, working trees, reflog...) will
|
|
be performed as well.
|
|
|
|
|
|
--cruft::
|
|
When expiring unreachable objects, pack them separately into a
|
|
cruft pack instead of storing them as loose objects.
|
|
|
|
--prune=<date>::
|
|
Prune loose objects older than date (default is 2 weeks ago,
|
|
overridable by the config variable `gc.pruneExpire`).
|
|
--prune=now prunes loose objects regardless of their age and
|
|
increases the risk of corruption if another process is writing to
|
|
the repository concurrently; see "NOTES" below. --prune is on by
|
|
default.
|
|
|
|
--no-prune::
|
|
Do not prune any loose objects.
|
|
|
|
--quiet::
|
|
Suppress all progress reports.
|
|
|
|
--force::
|
|
Force `git gc` to run even if there may be another `git gc`
|
|
instance running on this repository.
|
|
|
|
--keep-largest-pack::
|
|
All packs except the largest pack and those marked with a
|
|
`.keep` files are consolidated into a single pack. When this
|
|
option is used, `gc.bigPackThreshold` is ignored.
|
|
|
|
AGGRESSIVE
|
|
----------
|
|
|
|
When the `--aggressive` option is supplied, linkgit:git-repack[1] will
|
|
be invoked with the `-f` flag, which in turn will pass
|
|
`--no-reuse-delta` to linkgit:git-pack-objects[1]. This will throw
|
|
away any existing deltas and re-compute them, at the expense of
|
|
spending much more time on the repacking.
|
|
|
|
The effects of this are mostly persistent, e.g. when packs and loose
|
|
objects are coalesced into one another pack the existing deltas in
|
|
that pack might get re-used, but there are also various cases where we
|
|
might pick a sub-optimal delta from a newer pack instead.
|
|
|
|
Furthermore, supplying `--aggressive` will tweak the `--depth` and
|
|
`--window` options passed to linkgit:git-repack[1]. See the
|
|
`gc.aggressiveDepth` and `gc.aggressiveWindow` settings below. By
|
|
using a larger window size we're more likely to find more optimal
|
|
deltas.
|
|
|
|
It's probably not worth it to use this option on a given repository
|
|
without running tailored performance benchmarks on it. It takes a lot
|
|
more time, and the resulting space/delta optimization may or may not
|
|
be worth it. Not using this at all is the right trade-off for most
|
|
users and their repositories.
|
|
|
|
CONFIGURATION
|
|
-------------
|
|
|
|
include::includes/cmd-config-section-all.txt[]
|
|
|
|
include::config/gc.txt[]
|
|
|
|
NOTES
|
|
-----
|
|
|
|
'git gc' tries very hard not to delete objects that are referenced
|
|
anywhere in your repository. In particular, it will keep not only
|
|
objects referenced by your current set of branches and tags, but also
|
|
objects referenced by the index, remote-tracking branches, reflogs
|
|
(which may reference commits in branches that were later amended or
|
|
rewound), and anything else in the refs/* namespace. Note that a note
|
|
(of the kind created by 'git notes') attached to an object does not
|
|
contribute in keeping the object alive. If you are expecting some
|
|
objects to be deleted and they aren't, check all of those locations
|
|
and decide whether it makes sense in your case to remove those
|
|
references.
|
|
|
|
On the other hand, when 'git gc' runs concurrently with another process,
|
|
there is a risk of it deleting an object that the other process is using
|
|
but hasn't created a reference to. This may just cause the other process
|
|
to fail or may corrupt the repository if the other process later adds a
|
|
reference to the deleted object. Git has two features that significantly
|
|
mitigate this problem:
|
|
|
|
. Any object with modification time newer than the `--prune` date is kept,
|
|
along with everything reachable from it.
|
|
|
|
. Most operations that add an object to the database update the
|
|
modification time of the object if it is already present so that #1
|
|
applies.
|
|
|
|
However, these features fall short of a complete solution, so users who
|
|
run commands concurrently have to live with some risk of corruption (which
|
|
seems to be low in practice).
|
|
|
|
HOOKS
|
|
-----
|
|
|
|
The 'git gc --auto' command will run the 'pre-auto-gc' hook. See
|
|
linkgit:githooks[5] for more information.
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-prune[1]
|
|
linkgit:git-reflog[1]
|
|
linkgit:git-repack[1]
|
|
linkgit:git-rerere[1]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|