Merge branch 'ab/gc-docs'
Update docs around "gc". * ab/gc-docs: gc docs: remove incorrect reference to gc.auto=0 gc docs: clarify that "gc" doesn't throw away referenced objects gc docs: note "gc --aggressive" in "fast-import" gc docs: downplay the usefulness of --aggressive gc docs: note how --aggressive impacts --window & --depth gc docs: fix formatting for "gc.writeCommitGraph" gc docs: re-flow the "gc.*" section in "config" gc docs: include the "gc.*" section from "config" in "gc" gc docs: clean grammar for "gc.bigPackThreshold" gc docs: stop noting "repack" flags gc docs: modernize the advice for manually running "gc"maint
Junio C Hamano
commit
ac70c53133
|
|
@ -1,25 +1,42 @@
|
|||
gc.aggressiveDepth::
|
||||
The depth parameter used in the delta compression
|
||||
algorithm used by 'git gc --aggressive'. This defaults
|
||||
to 50.
|
||||
to 50, which is the default for the `--depth` option when
|
||||
`--aggressive` isn't in use.
|
||||
+
|
||||
See the documentation for the `--depth` option in
|
||||
linkgit:git-repack[1] for more details.
|
||||
|
||||
gc.aggressiveWindow::
|
||||
The window size parameter used in the delta compression
|
||||
algorithm used by 'git gc --aggressive'. This defaults
|
||||
to 250.
|
||||
to 250, which is a much more aggressive window size than
|
||||
the default `--window` of 10.
|
||||
+
|
||||
See the documentation for the `--window` option in
|
||||
linkgit:git-repack[1] for more details.
|
||||
|
||||
gc.auto::
|
||||
When there are approximately more than this many loose
|
||||
objects in the repository, `git gc --auto` will pack them.
|
||||
Some Porcelain commands use this command to perform a
|
||||
light-weight garbage collection from time to time. The
|
||||
default value is 6700. Setting this to 0 disables it.
|
||||
default value is 6700.
|
||||
+
|
||||
Setting this to 0 disables not only automatic packing based on the
|
||||
number of loose objects, but any other heuristic `git gc --auto` will
|
||||
otherwise use to determine if there's work to do, such as
|
||||
`gc.autoPackLimit`.
|
||||
|
||||
gc.autoPackLimit::
|
||||
When there are more than this many packs that are not
|
||||
marked with `*.keep` file in the repository, `git gc
|
||||
--auto` consolidates them into one larger pack. The
|
||||
default value is 50. Setting this to 0 disables it.
|
||||
Setting `gc.auto` to 0 will also disable this.
|
||||
+
|
||||
See the `gc.bigPackThreshold` configuration variable below. When in
|
||||
use, it'll affect how the auto pack limit works.
|
||||
|
||||
gc.autoDetach::
|
||||
Make `git gc --auto` return immediately and run in background
|
||||
|
|
@ -36,11 +53,16 @@ Note that if the number of kept packs is more than gc.autoPackLimit,
|
|||
this configuration variable is ignored, all packs except the base pack
|
||||
will be repacked. After this the number of packs should go below
|
||||
gc.autoPackLimit and gc.bigPackThreshold should be respected again.
|
||||
+
|
||||
If the amount of memory estimated for `git repack` to run smoothly is
|
||||
not available and `gc.bigPackThreshold` is not set, the largest pack
|
||||
will also be excluded (this is the equivalent of running `git gc` with
|
||||
`--keep-base-pack`).
|
||||
|
||||
gc.writeCommitGraph::
|
||||
If true, then gc will rewrite the commit-graph file when
|
||||
linkgit:git-gc[1] is run. When using linkgit:git-gc[1]
|
||||
'--auto' the commit-graph will be updated if housekeeping is
|
||||
linkgit:git-gc[1] is run. When using `git gc --auto`
|
||||
the commit-graph will be updated if housekeeping is
|
||||
required. Default is false. See linkgit:git-commit-graph[1]
|
||||
for details.
|
||||
|
||||
|
|
@ -94,6 +116,12 @@ gc.<pattern>.reflogExpireUnreachable::
|
|||
With "<pattern>" (e.g. "refs/stash")
|
||||
in the middle, the setting applies only to the refs that
|
||||
match the <pattern>.
|
||||
+
|
||||
These types of entries are generally created as a result of using `git
|
||||
commit --amend` or `git rebase` and are the commits prior to the amend
|
||||
or rebase occurring. Since these changes are not part of the current
|
||||
project most users will want to expire them sooner, which is why the
|
||||
default is more aggressive than `gc.reflogExpire`.
|
||||
|
||||
gc.rerereResolved::
|
||||
Records of conflicted merge you resolved earlier are
|
||||
|
|
|
|||
|
|
@ -1398,6 +1398,13 @@ deltas are suboptimal (see above) then also adding the `-f` option
|
|||
to force recomputation of all deltas can significantly reduce the
|
||||
final packfile size (30-50% smaller can be quite typical).
|
||||
|
||||
Instead of running `git repack` you can also run `git gc
|
||||
--aggressive`, which will also optimize other things after an import
|
||||
(e.g. pack loose refs). As noted in the "AGGRESSIVE" section in
|
||||
linkgit:git-gc[1] the `--aggressive` option will find new deltas with
|
||||
the `-f` option to linkgit:git-repack[1]. For the reasons elaborated
|
||||
on above using `--aggressive` after a fast-import is one of the few
|
||||
cases where it's known to be worthwhile.
|
||||
|
||||
MEMORY UTILIZATION
|
||||
------------------
|
||||
|
|
|
|||
|
|
@ -20,17 +20,16 @@ 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.
|
||||
|
||||
Users are encouraged to run this task on a regular basis within
|
||||
each repository to maintain good disk space utilization and good
|
||||
operating performance.
|
||||
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.
|
||||
|
||||
Some git commands may automatically run 'git gc'; see the `--auto` flag
|
||||
below for details. If you know what you're doing and all you want is to
|
||||
disable this behavior permanently without further considerations, just do:
|
||||
|
||||
----------------------
|
||||
$ git config --global gc.auto 0
|
||||
----------------------
|
||||
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
|
||||
-------
|
||||
|
|
@ -40,35 +39,17 @@ OPTIONS
|
|||
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
|
||||
persistent, so this option only needs to be used occasionally; every
|
||||
few hundred changesets or so.
|
||||
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.
|
||||
Some git commands run `git gc --auto` after performing
|
||||
operations that could create many loose objects. Housekeeping
|
||||
is required if there are too many loose objects or too many
|
||||
packs in the repository.
|
||||
+
|
||||
If the number of loose objects exceeds the value of the `gc.auto`
|
||||
configuration variable, then all loose objects are combined into a
|
||||
single pack using `git repack -d -l`. Setting the value of `gc.auto`
|
||||
to 0 disables automatic packing of loose objects.
|
||||
See the `gc.auto` option in the "CONFIGURATION" section below for how
|
||||
this heuristic works.
|
||||
+
|
||||
If the number of packs exceeds the value of `gc.autoPackLimit`,
|
||||
then existing packs (except those marked with a `.keep` file
|
||||
or over `gc.bigPackThreshold` limit)
|
||||
are consolidated into a single pack by using the `-A` option of
|
||||
'git repack'.
|
||||
If the amount of memory is estimated not enough for `git repack` to
|
||||
run smoothly and `gc.bigPackThreshold` is not set, the largest
|
||||
pack will also be excluded (this is the equivalent of running `git gc`
|
||||
with `--keep-base-pack`).
|
||||
Setting `gc.autoPackLimit` to 0 disables automatic consolidation of
|
||||
packs.
|
||||
+
|
||||
If houskeeping is required due to many loose objects or packs, all
|
||||
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.
|
||||
|
||||
|
|
@ -96,69 +77,39 @@ be performed as well.
|
|||
`.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
|
||||
-------------
|
||||
|
||||
The optional configuration variable `gc.reflogExpire` can be
|
||||
set to indicate how long historical entries within each branch's
|
||||
reflog should remain available in this repository. The setting is
|
||||
expressed as a length of time, for example '90 days' or '3 months'.
|
||||
It defaults to '90 days'.
|
||||
|
||||
The optional configuration variable `gc.reflogExpireUnreachable`
|
||||
can be set to indicate how long historical reflog entries which
|
||||
are not part of the current branch should remain available in
|
||||
this repository. These types of entries are generally created as
|
||||
a result of using `git commit --amend` or `git rebase` and are the
|
||||
commits prior to the amend or rebase occurring. Since these changes
|
||||
are not part of the current project most users will want to expire
|
||||
them sooner. This option defaults to '30 days'.
|
||||
|
||||
The above two configuration variables can be given to a pattern. For
|
||||
example, this sets non-default expiry values only to remote-tracking
|
||||
branches:
|
||||
|
||||
------------
|
||||
[gc "refs/remotes/*"]
|
||||
reflogExpire = never
|
||||
reflogExpireUnreachable = 3 days
|
||||
------------
|
||||
|
||||
The optional configuration variable `gc.rerereResolved` indicates
|
||||
how long records of conflicted merge you resolved earlier are
|
||||
kept. This defaults to 60 days.
|
||||
|
||||
The optional configuration variable `gc.rerereUnresolved` indicates
|
||||
how long records of conflicted merge you have not resolved are
|
||||
kept. This defaults to 15 days.
|
||||
|
||||
The optional configuration variable `gc.packRefs` determines if
|
||||
'git gc' runs 'git pack-refs'. This can be set to "notbare" to enable
|
||||
it within all non-bare repos or it can be set to a boolean value.
|
||||
This defaults to true.
|
||||
|
||||
The optional configuration variable `gc.writeCommitGraph` determines if
|
||||
'git gc' should run 'git commit-graph write'. This can be set to a
|
||||
boolean value. This defaults to false.
|
||||
|
||||
The optional configuration variable `gc.aggressiveWindow` controls how
|
||||
much time is spent optimizing the delta compression of the objects in
|
||||
the repository when the --aggressive option is specified. The larger
|
||||
the value, the more time is spent optimizing the delta compression. See
|
||||
the documentation for the --window option in linkgit:git-repack[1] for
|
||||
more details. This defaults to 250.
|
||||
|
||||
Similarly, the optional configuration variable `gc.aggressiveDepth`
|
||||
controls --depth option in linkgit:git-repack[1]. This defaults to 50.
|
||||
|
||||
The optional configuration variable `gc.pruneExpire` controls how old
|
||||
the unreferenced loose objects have to be before they are pruned. The
|
||||
default is "2 weeks ago".
|
||||
|
||||
Optional configuration variable `gc.worktreePruneExpire` controls how
|
||||
old a stale working tree should be before `git worktree prune` deletes
|
||||
it. Default is "3 months ago".
|
||||
The below documentation is the same as what's found in
|
||||
linkgit:git-config[1]:
|
||||
|
||||
include::config/gc.txt[]
|
||||
|
||||
NOTES
|
||||
-----
|
||||
|
|
@ -168,8 +119,8 @@ 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, refs saved by 'git filter-branch' in
|
||||
refs/original/, or reflogs (which may reference commits in branches
|
||||
that were later amended or rewound).
|
||||
refs/original/, reflogs (which may reference commits in branches
|
||||
that were later amended or rewound), and anything else in the refs/* namespace.
|
||||
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.
|
||||
|
|
@ -190,8 +141,7 @@ mitigate this problem:
|
|||
|
||||
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) unless they turn off automatic garbage
|
||||
collection with 'git config gc.auto 0'.
|
||||
seems to be low in practice).
|
||||
|
||||
HOOKS
|
||||
-----
|
||||
|
|
|
|||
Loading…
Reference in New Issue