Commit ac70c531 authored by Junio C Hamano's avatar Junio C Hamano

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"
parents 01f8d788 0044f770
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.
+
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.
See the `gc.auto` option in the "CONFIGURATION" section below for how
this heuristic works.
+
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
-----
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment