[PATCH v3 0/9] Makefile & docs: document SHA-{1,256} behavior, fix bug

This v3 is a rewrite of the larger-in-scope v2[2] to only fix the current Makefile & INSTALL documentation do to do with our SHA-1 and SHA-256 knobs.

The only behavior change here is in 1/8, where I fix what's obviously a bug in the current behavior (so that we don't need to document that edge case). I'll submit a patch to change the behavior on OSX to use sha1collisiondetection by default on top of this series.

1. https://lore.kernel.org/git/cover-v2-0.4-00000000000-20221019T010222Z-avarab@gmail.com/

Ævar Arnfjörð Bjarmason (9):
  Makefile: always (re)set DC_SHA1 on fallback
  INSTALL: remove discussion of SHA-1 backends
  Makefile: correct DC_SHA1 documentation
  Makefile: create and use sections for "define" flag listing
  Makefile: rephrase the discussion of *_SHA1 knobs
  Makefile: document default SHA-256 backend
  Makefile: document SHA-1 and SHA-256 default and selection order
  Makefile: document default SHA-1 backend on OSX
  Makefile: discuss SHAttered in *_SHA{1,256} discussion

 INSTALL  |   4 -
 Makefile | 260 +++++++++++++++++++++++++++++++++++--------------------
 2 files changed, 166 insertions(+), 98 deletions(-)

Range-diff against v2:
 1:  392fabdb456 <  -:  ----------- fsmonitor OSX: compile with DC_SHA1=YesPlease
 -:  ----------- >  1:  ef3c5be11e0 Makefile: always (re)set DC_SHA1 on fallback
 -:  ----------- >  2:  017a0a9791c INSTALL: remove discussion of SHA-1 backends
 -:  ----------- >  3:  62dd2d5708d Makefile: correct DC_SHA1 documentation
 2:  7ae22276aa7 !  4:  933bef576b3 Makefile: create and use sections for "define" flag listing
    @@ Makefile: include shared.mak
     -# Define BLK_SHA1 environment variable to make use of the bundled
     -# optimized C SHA1 routine.
     -#
    --# Define DC_SHA1 to unconditionally enable the collision-detecting sha1
    +-# Define DC_SHA1 to enable the collision-detecting sha1
     -# algorithm. This is slower, but may detect attempted collision attacks.
    --# Takes priority over other *_SHA1 knobs.
     -#
     -# Define DC_SHA1_EXTERNAL in addition to DC_SHA1 if you want to build / link
     -# git with the external SHA1 collision-detect library.
    @@ Makefile: include shared.mak
     +#
     +# == SHA-1 and SHA-256 defines ==
     +#
    -+# Define BLK_SHA1 environment variable to make use of the bundled
    -+# optimized C SHA1 routine.
    ++# === SHA-1 backend ===
    ++#
    ++# ==== Options common to all SHA-1 implementations ====
    ++#
    ++# Define SHA1_MAX_BLOCK_SIZE to limit the amount of data that will be hashed
    ++# in one call to the platform's SHA1_Update(). e.g. APPLE_COMMON_CRYPTO
    ++# wants 'SHA1_MAX_BLOCK_SIZE=1024L*1024L*1024L' defined.
    ++#
    ++# ==== Options for the sha1collisiondetection implementation ====
     +#
    -+# Define DC_SHA1 to unconditionally enable the collision-detecting sha1
    ++# Define DC_SHA1 to enable the collision-detecting sha1
     +# algorithm. This is slower, but may detect attempted collision attacks.
    -+# Takes priority over other *_SHA1 knobs.
     +#
     +# Define DC_SHA1_EXTERNAL in addition to DC_SHA1 if you want to build / link
     +# git with the external SHA1 collision-detect library.
    @@ Makefile: include shared.mak
     +# by the git project to migrate to using sha1collisiondetection as a
     +# submodule.
     +#
    ++# ==== Other SHA-1 implementations ====
    ++#
    ++# Define BLK_SHA1 environment variable to make use of the bundled
    ++# optimized C SHA1 routine.
    ++#
     +# Define OPENSSL_SHA1 environment variable when running make to link
     +# with the SHA1 routine from openssl library.
     +#
    -+# Define SHA1_MAX_BLOCK_SIZE to limit the amount of data that will be hashed
    -+# in one call to the platform's SHA1_Update(). e.g. APPLE_COMMON_CRYPTO
    -+# wants 'SHA1_MAX_BLOCK_SIZE=1024L*1024L*1024L' defined.
    ++# === SHA-256 backend ===
     +#
     +# Define BLK_SHA256 to use the built-in SHA-256 routines.
     +#
 3:  78ef8636c57 <  -:  ----------- Makefile: really use and document sha1collisiondetection by default
 4:  f1fb9775b33 <  -:  ----------- Makefile: rephrase the discussion of *_SHA1 knobs
 -:  ----------- >  5:  5b18198c477 Makefile: rephrase the discussion of *_SHA1 knobs
 -:  ----------- >  6:  73685592aba Makefile: document default SHA-256 backend
 -:  ----------- >  7:  05edcfb9cd9 Makefile: document SHA-1 and SHA-256 default and selection order
 -:  ----------- >  8:  859e69fbe9f Makefile: document default SHA-1 backend on OSX
 -:  ----------- >  9:  c1f27255d3e Makefile: discuss SHAttered in *_SHA{1,256} discussion