| 1 | git-gc(1) |
| 2 | ========= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-gc - Cleanup unnecessary files and optimize the local repository |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git gc' [--aggressive] [--auto] [--[no-]detach] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack] |
| 13 | |
| 14 | DESCRIPTION |
| 15 | ----------- |
| 16 | Runs a number of housekeeping tasks within the current repository, |
| 17 | such as compressing file revisions (to reduce disk space and increase |
| 18 | performance), removing unreachable objects which may have been |
| 19 | created from prior invocations of 'git add', packing refs, pruning |
| 20 | reflog, rerere metadata or stale working trees. May also update ancillary |
| 21 | indexes such as the commit-graph. |
| 22 | |
| 23 | When common porcelain operations that create objects are run, they |
| 24 | will check whether the repository has grown substantially since the |
| 25 | last maintenance, and if so run `git gc` automatically. See `gc.auto` |
| 26 | below for how to disable this behavior. |
| 27 | |
| 28 | Running `git gc` manually should only be needed when adding objects to |
| 29 | a repository without regularly running such porcelain commands, to do |
| 30 | a one-off repository optimization, or e.g. to clean up a suboptimal |
| 31 | mass-import. See the "PACKFILE OPTIMIZATION" section in |
| 32 | linkgit:git-fast-import[1] for more details on the import case. |
| 33 | |
| 34 | OPTIONS |
| 35 | ------- |
| 36 | |
| 37 | --aggressive:: |
| 38 | Usually 'git gc' runs very quickly while providing good disk |
| 39 | space utilization and performance. This option will cause |
| 40 | 'git gc' to more aggressively optimize the repository at the expense |
| 41 | of taking much more time. The effects of this optimization are |
| 42 | mostly persistent. See the "AGGRESSIVE" section below for details. |
| 43 | |
| 44 | --auto:: |
| 45 | With this option, 'git gc' checks whether any housekeeping is |
| 46 | required; if not, it exits without performing any work. |
| 47 | + |
| 48 | See the `gc.auto` option in the "CONFIGURATION" section below for how |
| 49 | this heuristic works. |
| 50 | + |
| 51 | Once housekeeping is triggered by exceeding the limits of |
| 52 | configuration options such as `gc.auto` and `gc.autoPackLimit`, all |
| 53 | other housekeeping tasks (e.g. rerere, working trees, reflog...) will |
| 54 | be performed as well. |
| 55 | |
| 56 | --detach:: |
| 57 | --no-detach:: |
| 58 | Run in the background if the system supports it. This option overrides |
| 59 | the `gc.autoDetach` config. |
| 60 | |
| 61 | --cruft:: |
| 62 | --no-cruft:: |
| 63 | When expiring unreachable objects, pack them separately into a |
| 64 | cruft pack instead of storing them as loose objects. `--cruft` |
| 65 | is on by default. |
| 66 | |
| 67 | --max-cruft-size=<n>:: |
| 68 | When packing unreachable objects into a cruft pack, limit the |
| 69 | size of new cruft packs to be at most `<n>` bytes. Overrides any |
| 70 | value specified via the `gc.maxCruftSize` configuration. See |
| 71 | the `--max-cruft-size` option of linkgit:git-repack[1] for |
| 72 | more. |
| 73 | |
| 74 | --expire-to=<dir>:: |
| 75 | When packing unreachable objects into a cruft pack, write a cruft |
| 76 | pack containing pruned objects (if any) to the directory `<dir>`. |
| 77 | This option only has an effect when used together with `--cruft`. |
| 78 | See the `--expire-to` option of linkgit:git-repack[1] for |
| 79 | more information. |
| 80 | |
| 81 | --prune=<date>:: |
| 82 | Prune loose objects older than date (default is 2 weeks ago, |
| 83 | overridable by the config variable `gc.pruneExpire`). |
| 84 | --prune=now prunes loose objects regardless of their age and |
| 85 | increases the risk of corruption if another process is writing to |
| 86 | the repository concurrently; see "NOTES" below. --prune is on by |
| 87 | default. |
| 88 | |
| 89 | --no-prune:: |
| 90 | Do not prune any loose objects. |
| 91 | |
| 92 | --quiet:: |
| 93 | Suppress all progress reports. |
| 94 | |
| 95 | --force:: |
| 96 | Force `git gc` to run even if there may be another `git gc` |
| 97 | instance running on this repository. |
| 98 | |
| 99 | --keep-largest-pack:: |
| 100 | All packs except the largest non-cruft pack, any packs marked |
| 101 | with a `.keep` file, and any cruft pack(s) are consolidated into |
| 102 | a single pack. When this option is used, `gc.bigPackThreshold` |
| 103 | is ignored. |
| 104 | |
| 105 | AGGRESSIVE |
| 106 | ---------- |
| 107 | |
| 108 | When the `--aggressive` option is supplied, linkgit:git-repack[1] will |
| 109 | be invoked with the `-f` flag, which in turn will pass |
| 110 | `--no-reuse-delta` to linkgit:git-pack-objects[1]. This will throw |
| 111 | away any existing deltas and re-compute them, at the expense of |
| 112 | spending much more time on the repacking. |
| 113 | |
| 114 | The effects of this are mostly persistent, e.g. when packs and loose |
| 115 | objects are coalesced into one another pack the existing deltas in |
| 116 | that pack might get re-used, but there are also various cases where we |
| 117 | might pick a sub-optimal delta from a newer pack instead. |
| 118 | |
| 119 | Furthermore, supplying `--aggressive` will tweak the `--depth` and |
| 120 | `--window` options passed to linkgit:git-repack[1]. See the |
| 121 | `gc.aggressiveDepth` and `gc.aggressiveWindow` settings below. By |
| 122 | using a larger window size we're more likely to find more optimal |
| 123 | deltas. |
| 124 | |
| 125 | It's probably not worth it to use this option on a given repository |
| 126 | without running tailored performance benchmarks on it. It takes a lot |
| 127 | more time, and the resulting space/delta optimization may or may not |
| 128 | be worth it. Not using this at all is the right trade-off for most |
| 129 | users and their repositories. |
| 130 | |
| 131 | CONFIGURATION |
| 132 | ------------- |
| 133 | |
| 134 | include::includes/cmd-config-section-all.adoc[] |
| 135 | |
| 136 | include::config/gc.adoc[] |
| 137 | |
| 138 | NOTES |
| 139 | ----- |
| 140 | |
| 141 | 'git gc' tries very hard not to delete objects that are referenced |
| 142 | anywhere in your repository. In particular, it will keep not only |
| 143 | objects referenced by your current set of branches and tags, but also |
| 144 | objects referenced by the index, remote-tracking branches, reflogs |
| 145 | (which may reference commits in branches that were later amended or |
| 146 | rewound), and anything else in the refs/* namespace. Note that a note |
| 147 | (of the kind created by 'git notes') attached to an object does not |
| 148 | contribute in keeping the object alive. If you are expecting some |
| 149 | objects to be deleted and they aren't, check all of those locations |
| 150 | and decide whether it makes sense in your case to remove those |
| 151 | references. |
| 152 | |
| 153 | On the other hand, when 'git gc' runs concurrently with another process, |
| 154 | there is a risk of it deleting an object that the other process is using |
| 155 | but hasn't created a reference to. This may just cause the other process |
| 156 | to fail or may corrupt the repository if the other process later adds a |
| 157 | reference to the deleted object. Git has two features that significantly |
| 158 | mitigate this problem: |
| 159 | |
| 160 | . Any object with modification time newer than the `--prune` date is kept, |
| 161 | along with everything reachable from it. |
| 162 | |
| 163 | . Most operations that add an object to the database update the |
| 164 | modification time of the object if it is already present so that #1 |
| 165 | applies. |
| 166 | |
| 167 | However, these features fall short of a complete solution, so users who |
| 168 | run commands concurrently have to live with some risk of corruption (which |
| 169 | seems to be low in practice). |
| 170 | |
| 171 | HOOKS |
| 172 | ----- |
| 173 | |
| 174 | The 'git gc --auto' command will run the 'pre-auto-gc' hook. See |
| 175 | linkgit:githooks[5] for more information. |
| 176 | |
| 177 | |
| 178 | SEE ALSO |
| 179 | -------- |
| 180 | linkgit:git-prune[1] |
| 181 | linkgit:git-reflog[1] |
| 182 | linkgit:git-repack[1] |
| 183 | linkgit:git-rerere[1] |
| 184 | |
| 185 | GIT |
| 186 | --- |
| 187 | Part of the linkgit:git[1] suite |