[PATCH 0/4] gc docs: modernize and fix the documentation

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@gmail.com/), 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(-)