diff options
Diffstat (limited to 'Documentation/git-gc.txt')
| -rw-r--r-- | Documentation/git-gc.txt | 93 |
1 files changed, 68 insertions, 25 deletions
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index bed60f471c..f5bc98ccb3 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -9,14 +9,15 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- [verse] -'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] +'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) and removing unreachable objects which may have been -created from prior invocations of 'git add'. +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. Users are encouraged to run this task on a regular basis within each repository to maintain good disk space utilization and good @@ -45,29 +46,39 @@ OPTIONS 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. + operations that could create many loose objects. Housekeeping + is required if there are too many loose objects or too many + packs in the repository. + -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 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) +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'. Setting `gc.autoPackLimit` to 0 disables -automatic consolidation of packs. +'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 +other housekeeping tasks (e.g. rerere, working trees, reflog...) will +be performed as well. + --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, overridable by the config variable `gc.pruneExpire`). - --prune=all prunes loose objects regardless of their age (do - not use --prune=all unless you know exactly what you are doing. - Unless the repository is quiescent, you will lose newly created - objects that haven't been anchored with the refs and end up - corrupting your repository). --prune is on by default. + --prune=all 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. @@ -79,7 +90,12 @@ automatic consolidation of packs. Force `git gc` to run even if there may be another `git gc` instance running on this repository. -Configuration +--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. + +CONFIGURATION ------------- The optional configuration variable `gc.reflogExpire` can be @@ -120,35 +136,62 @@ The optional configuration variable `gc.packRefs` determines if it within all non-bare repos or it can be set to a boolean value. This defaults to true. +The optional configuration variable `gc.commitGraph` 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 +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 250. +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". + -Notes +NOTES ----- -'git gc' tries very hard to be safe about the garbage it collects. In +'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, refs saved by 'git filter-branch' in refs/original/, or reflogs (which may reference commits in branches that were later amended or rewound). - -If you are expecting some objects to be collected and they aren't, check +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) unless they turn off automatic garbage +collection with 'git config gc.auto 0'. + HOOKS ----- |