I've been annoyed by the "gc" docs for a while. This fixes most of the issues I've noticed, and also removes the duplication between the "gc" variables in git-config(1) and in git-gc(1), which was made possible by Duy's Documentation/config/* series. This should make the "gc" docs more awesome, and due to removing the de-duplication results in a net deletion of lines. Yay. The only thing I was on the fence about was removing the 'gc "refs/remotes/*' config example, but I think the remaining docs explain it well enough. It can be added back if someone insists... Now, I was originally going to have 5 patches in this series by modernizing the "NOTES" section, but that didn't make it in. This series is unrelated (and does not conflict with) my in-flight gc contention series (https://public-inbox.org/git/20190315155959.12390-1-avarab@xxxxxxxxx/), but the "git-gc" docs should be updated to discuss the core.filesRefLockTimeout option and how it impacts contention, see 8/8 in that series for context. I.e. "you may have contention, but core.filesRefLockTimeout can mitigate blah blah". I was going to do that, but then thought that we should also mention that on the server-side we mitigate most/all of the contention via the quarantine, see "QUARANTINE ENVIRONMENT" in git-receive-pack(1). I.e. we: 1. Get the temp pack 2. OK it (fsck, hooks etc.) 3. Move *complete* previously temp packs over 4. Update the refs I.e. we are immune from the "concurrently with another process" race, but of course something concurrently updating the "server" repo without a quarantine environment may be subject to that race. The only problem is that the last couple of paragraphs may be wrong. That's just my understanding from a brief reading of 722ff7f876c ("receive-pack: quarantine objects until pre-receive accepts", 2016-10-03) so I didn't want to include that in this series. Peff (or others), any comments? Ævar Arnfjörð Bjarmason (4): gc docs: modernize the advice for manually running "gc" gc docs: include the "gc.*" section from "config" in "gc" gc docs: de-duplicate "OPTIONS" and "CONFIGURATION" gc docs: downplay the usefulness of --aggressive Documentation/config/gc.txt | 39 ++++++++++-- Documentation/git-gc.txt | 120 +++++++++--------------------------- 2 files changed, 65 insertions(+), 94 deletions(-) -- 2.21.0.360.g471c308f928
