From b11e8560cc1be17268136504cb80b00fbf4182dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Fri, 22 Mar 2019 10:32:32 +0100 Subject: [PATCH 01/11] gc docs: modernize the advice for manually running "gc" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs have been recommending that users need to run this manually, but that hasn't been needed in practice for a long time except in exceptional circumstances. Let's instead have this reflect reality and say that most users don't need to run this manually at all, while briefly describing the sorts sort of cases where "gc" does need to be run manually. Since we're recommending that users run this most of the and usually don't need to tweak it, let's tone down the very prominent example of the gc.auto=0 command. It's sufficient to point to the gc.auto documentation below. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-gc.txt | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index a7c1b0f60e..dd22eecc79 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -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 ------- From cf9cd771e1314ad5cd8eaf1d92b7a5fd5e6b734f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Fri, 22 Mar 2019 10:32:33 +0100 Subject: [PATCH 02/11] gc docs: stop noting "repack" flags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove the mention of specific flags from the "gc" documentation, and leave it at describing what we'll do instead. As seen in builtin/gc.c we'll use various repack flags depending on what we detect we need to do, so this isn't always accurate. More importantly, a subsequent change is about to remove all this documentation and replace it with an include of the gc.* docs in git-config(1). By first changing this it's easier to reason about that subsequent change. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-gc.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index dd22eecc79..c56f4f7cde 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -52,14 +52,13 @@ OPTIONS + 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` +single pack. 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'. +are consolidated into a single pack. 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` From fc559fbb54e5852be7d9cbd854a375333409aa2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Fri, 22 Mar 2019 10:32:34 +0100 Subject: [PATCH 03/11] gc docs: clean grammar for "gc.bigPackThreshold" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clean up the grammar in the documentation for "gc.bigPackThreshold". This documentation was added in 9806f5a7bf ("gc --auto: exclude base pack if not enough mem to "repack -ad"", 2018-04-15). Saying "the amount of memory estimated for" flows more smoothly than the previous "the amount of memory is estimated not enough". Suggested-by: Jeff King Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-gc.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index c56f4f7cde..66386439b7 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -59,8 +59,8 @@ 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. -If the amount of memory is estimated not enough for `git repack` to -run smoothly and `gc.bigPackThreshold` is not set, the largest +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`). Setting `gc.autoPackLimit` to 0 disables automatic consolidation of From b6a8d09f6d85693dad19bbcfd2b18f9e6fc81ee4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Sun, 7 Apr 2019 21:52:10 +0200 Subject: [PATCH 04/11] gc docs: include the "gc.*" section from "config" in "gc" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rather than duplicating the documentation for the various "gc" options let's include the "gc" docs from git-config. They were mostly better already, and now we don't have the same docs in two places with subtly different wording. In the cases where the git-gc(1) docs were saying something the "gc" docs in git-config(1) didn't cover move the relevant section over to the git-config(1) docs. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config/gc.txt | 29 ++++++++++++- Documentation/git-gc.txt | 86 +++---------------------------------- 2 files changed, 35 insertions(+), 80 deletions(-) diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index c6fbb8a96f..a255ae67b0 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -2,24 +2,39 @@ gc.aggressiveDepth:: The depth parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults to 50. ++ +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. ++ +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,6 +51,11 @@ 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 @@ -94,6 +114,13 @@ gc..reflogExpireUnreachable:: With "" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the . ++ +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 diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 66386439b7..37c4d26a76 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -45,28 +45,12 @@ OPTIONS --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. 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. -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`). -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. @@ -97,66 +81,10 @@ be performed as well. 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 ----- From d257e0fb0adc1eefa8e237391cd0e3aaa9d69e9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Sun, 7 Apr 2019 21:52:11 +0200 Subject: [PATCH 05/11] gc docs: re-flow the "gc.*" section in "config" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-flow the "gc.*" section in "config". A previous commit moved this over from the "gc" docs, but tried to keep as many of the lines identical to benefit from diff's move detection. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config/gc.txt | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index a255ae67b0..3e7fc052d9 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -53,9 +53,9 @@ 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`). +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 @@ -115,12 +115,11 @@ gc..reflogExpireUnreachable:: in the middle, the setting applies only to the refs that match the . + -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`. +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 From 54d56f52bdf477b6167cc8f97f8afb5b78eb39fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Sun, 7 Apr 2019 21:52:12 +0200 Subject: [PATCH 06/11] gc docs: fix formatting for "gc.writeCommitGraph" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change the AsciiDoc formatting so that an example of "gc --auto" isn't rendered as "git-gc(1) --auto", but as "git gc --auto". This is consistent with the rest of the links and command examples in this documentation. The formatting I'm changing was initially introduced in d5d5d7b641 ("gc: automatically write commit-graph files", 2018-06-27). Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config/gc.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 3e7fc052d9..56918a5008 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -59,8 +59,8 @@ will also be excluded (this is the equivalent of running `git gc` with 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. From 080a4480a07ae9831bf2685564641f6e5530cf87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Sun, 7 Apr 2019 21:52:13 +0200 Subject: [PATCH 07/11] gc docs: note how --aggressive impacts --window & --depth MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since 07e7dbf0db (gc: default aggressive depth to 50, 2016-08-11) we somewhat confusingly use the same depth under --aggressive as we do by default. As noted in that commit that makes sense, it was wrong to make more depth the default for "aggressive", and thus save disk space at the expense of runtime performance, which is usually the opposite of someone who'd like "aggressive gc" wants. But that's left us with a mostly-redundant configuration variable, so let's clearly note in its documentation that it doesn't change the default. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config/gc.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 56918a5008..f732fe5bfd 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -1,7 +1,8 @@ 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. @@ -9,7 +10,8 @@ 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. From 22d4e3bd19bc81b3db6f372d850ad681333a7fb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Sun, 7 Apr 2019 21:52:14 +0200 Subject: [PATCH 08/11] gc docs: downplay the usefulness of --aggressive MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The existing "gc --aggressive" docs come just short of recommending to users that they run it regularly. I've personally talked to many users who've taken these docs as an advice to use this option, and have, usually it's (mostly) a waste of time. So let's clarify what it really does, and let the user draw their own conclusions. Let's also clarify the "The effects [...] are persistent" to paraphrase a brief version of Jeff King's explanation at [1]. 1. https://public-inbox.org/git/20190318235356.GK29661@sigill.intra.peff.net/ Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-gc.txt | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 37c4d26a76..5e80f306e7 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -39,8 +39,7 @@ 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 @@ -78,6 +77,32 @@ 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 ------------- From 73845048815bace98588df03ab76fa3e85fc0927 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Sun, 7 Apr 2019 21:52:15 +0200 Subject: [PATCH 09/11] gc docs: note "gc --aggressive" in "fast-import" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Amend the "PACKFILE OPTIMIZATION" section in "fast-import" to explain that simply running "git gc --aggressive" after a "fast-import" should properly optimize the repository. This is simpler and more effective than the existing "repack" advice (which I'm keeping as it helps explain things) because it e.g. also packs the newly imported refs. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-fast-import.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 43ab3b1637..2248755cb7 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -1396,6 +1396,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 ------------------ From daecbf2261f595935c999a00a1f9bc433df80e2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Sun, 7 Apr 2019 21:52:16 +0200 Subject: [PATCH 10/11] gc docs: clarify that "gc" doesn't throw away referenced objects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Amend the "NOTES" section to fix up wording that's been with us since 3ffb58be0a ("doc/git-gc: add a note about what is collected", 2008-04-23). I can't remember when/where anymore (I think Freenode #Git), but at some point I was having a conversation with someone who was convinced that "gc" would prune things only referenced by e.g. refs/pull/*, and pointed to this section as proof. It turned out that they'd read the "branches and tags" wording here and thought just refs/{heads,tags}/* and refs/remotes/* etc. would be kept, which is what we enumerate explicitly. So let's say "other refs", even though just above we say "objects that are referenced anywhere in your repository". Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-gc.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 5e80f306e7..9cdae588fb 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -119,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. From 0044f7700fdbfdb04b8f88c385ca6fd545e1e1bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Sun, 7 Apr 2019 21:52:17 +0200 Subject: [PATCH 11/11] gc docs: remove incorrect reference to gc.auto=0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The chance of a repository being corrupted due to a "gc" has nothing to do with whether or not that "gc" was invoked via "gc --auto", but whether there's other concurrent operations happening. This is already noted earlier in the paragraph, so there's no reason to suggest this here. The user can infer from the rest of the documentation that "gc" will run automatically unless gc.auto=0 is set, and we shouldn't confuse the issue by implying that "gc --auto" is somehow more prone to produce corruption than a normal "gc". Well, it is in the sense that a blocking "gc" would stop you from doing anything else in *that* particular terminal window, but users are likely to have another window, or to be worried about how concurrent "gc" on a server might cause corruption. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-gc.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 9cdae588fb..247f765604 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -141,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 -----