[v2,0/4] more SHA-256 documentation

Message

Martin Ågren Aug. 15, 2020, 4:05 p.m. UTC

Thanks brian, Stolee and Junio for your comments on the initial
submission. Changes since v1:

 * Dropped some "160-bit" I had missed.

 * Refer to the 'object-format' capability in a few spots rather than
   discussing SHA-1 vs SHA-256 repos.

 * Dropped the final patch, since Stolee has submitted a patch (series)
   for changing the implementation instead.

These could be part of bc/sha-256-doc-updates, since they are quite
similar in spirit, or go in separately, so these series don't need to
hold each other hostage. Whatever Junio and brian prefer will be fine
by me.

Martin

Martin Ågren (4):
  http-protocol.txt: document SHA-256 "want"/"have" format
  index-format.txt: document SHA-256 index format
  protocol-capabilities.txt: clarify "allow-x-sha1-in-want" re SHA-256
  shallow.txt: document SHA-256 shallow format

 Documentation/technical/http-protocol.txt     |  5 +--
 Documentation/technical/index-format.txt      | 34 ++++++++++---------
 .../technical/protocol-capabilities.txt       | 12 ++++---
 Documentation/technical/shallow.txt           |  2 +-
 4 files changed, 30 insertions(+), 23 deletions(-)

Range-diff against v1:
1:  fcb26c81be ! 1:  2e9f6b9294 http-protocol.txt: document SHA-256 "want"/"have" format
    @@ Metadata
      ## Commit message ##
         http-protocol.txt: document SHA-256 "want"/"have" format
     
    -    Document that in SHA-1 repositories, we use SHA-1 for "want"s and
    -    "have"s, and in SHA-256 repositories, we use SHA-256.
    +    Document that rather than always naming objects using SHA-1, we should
    +    use whatever has been negotiated using the object-format capability.
     
         Signed-off-by: Martin Ågren <[e-mail]>
     
    @@ Documentation/technical/http-protocol.txt: at all in the request stream:
     -SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending
     -multiple commands.
     +object name as its value.  Multiple object names MUST be sent by sending
    -+multiple commands. (An object name is a SHA-1 hash in a SHA-1 repo
    -+and a SHA-256 hash in a SHA-256 repo.)
    ++multiple commands. Object names MUST be given using the object format
    ++negotiated through the `object-format` capability (default SHA-1).
      
      The `have` list is created by popping the first 32 commits
      from `c_pending`.  Less can be supplied if `c_pending` empties.
2:  5c13a9478a ! 2:  14bd0d9362 index-format.txt: document SHA-256 index format
    @@ Metadata
      ## Commit message ##
         index-format.txt: document SHA-256 index format
     
    -    Similar to a recent commit, document that in SHA-1 repositories, we use
    -    SHA-1 and in SHA-256 repositories, we use SHA-256, then replace all
    -    other uses of "SHA-1" with something more neutral.
    +    Document that in SHA-1 repositories, we use SHA-1 and in SHA-256
    +    repositories, we use SHA-256, then replace all other uses of "SHA-1"
    +    with something more neutral. Avoid referring to "160-bit" hash values.
     
         Signed-off-by: Martin Ågren <[e-mail]>
     
    @@ Documentation/technical/index-format.txt: Git index format
           Extension data
      
     -   - 160-bit SHA-1 over the content of the index file before this
    -+   - 160-bit hash checksum over the content of the index file before this
    -      checksum.
    +-     checksum.
    ++   - Hash checksum over the content of the index file before this checksum.
      
      == Index entry
    + 
     @@ Documentation/technical/index-format.txt: Git index format
        32-bit file size
          This is the on-disk size from stat(2), truncated to 32-bit.
      
     -  160-bit SHA-1 for the represented object
    -+  160-bit object name for the represented object
    ++  Object name for the represented object
      
        A 16-bit 'flags' field split into (high to low bits)
      
    +@@ Documentation/technical/index-format.txt: Git index format
    + 
    +   - A newline (ASCII 10); and
    + 
    +-  - 160-bit object name for the object that would result from writing
    +-    this span of index as a tree.
    ++  - Object name for the object that would result from writing this span
    ++    of index as a tree.
    + 
    +   An entry can be in an invalidated state and is represented by having
    +   a negative number in the entry_count field. In this case, there is no
    +@@ Documentation/technical/index-format.txt: Git index format
    +     stage 1 to 3 (a missing stage is represented by "0" in this field);
    +     and
    + 
    +-  - At most three 160-bit object names of the entry in stages from 1 to 3
    ++  - At most three object names of the entry in stages from 1 to 3
    +     (nothing is written for a missing stage).
    + 
    + === Split index
     @@ Documentation/technical/index-format.txt: Git index format
      
        The extension consists of:
3:  82e5c67b7c ! 3:  2e82be9e36 protocol-capabilities.txt: clarify "allow-x-sha1-in-want" re SHA-256
    @@ Metadata
      ## Commit message ##
         protocol-capabilities.txt: clarify "allow-x-sha1-in-want" re SHA-256
     
    -    Two of our extensions contain "sha1" in their names, but that's
    -    historical. The "want"s will take object names that are not necessarily
    -    SHA-1s. Make this clear, but also make it clear how there's still just
    -    one correct hash algo: These extensions don't somehow make the "want"s
    -    take object names derived using *any* hash algorithm.
    +    Two of our capabilities contain "sha1" in their names, but that's
    +    historical. Clarify that object names are still to be given using
    +    whatever object format has been negotiated using the "object-format"
    +    capability.
     
         Signed-off-by: Martin Ågren <[e-mail]>
     
    @@ Documentation/technical/protocol-capabilities.txt: allow-tip-sha1-in-want
     -send "want" lines with SHA-1s that exist at the server but are not
     -advertised by upload-pack.
     +send "want" lines with object names that exist at the server but are not
    -+advertised by upload-pack. (Note that the name of the capability
    -+contains "sha1", but that it's more general than that: in SHA-1
    -+repositories, the "want" lines provide SHA-1 values, but in SHA-256
    -+repositories, they provide SHA-256 values.)
    ++advertised by upload-pack. For historical reasons, the name of this
    ++capability contains "sha1". Object names are always given using the
    ++object format negotiated through the 'object-format' capability.
      
      allow-reachable-sha1-in-want
      ----------------------------
    @@ Documentation/technical/protocol-capabilities.txt: allow-tip-sha1-in-want
     -send "want" lines with SHA-1s that exist at the server but are not
     -advertised by upload-pack.
     +send "want" lines with object names that exist at the server but are not
    -+advertised by upload-pack. (Same remark about "sha1" as above.)
    ++advertised by upload-pack. For historical reasons, the name of this
    ++capability contains "sha1". Object names are always given using the
    ++object format negotiated through the 'object-format' capability.
      
      push-cert=<nonce>
      -----------------
4:  bcfbdd25e5 ! 4:  8680fc1af6 shallow.txt: document SHA-256 shallow format
    @@ Metadata
      ## Commit message ##
         shallow.txt: document SHA-256 shallow format
     
    -    Similar to recent commits, document that in SHA-1 repositories, we use
    -    SHA-1 for these purposes, and in SHA-256 repositories, we use SHA-256.
    +    Similar to recent commits, document that we list object names rather
    +    than SHA-1s.
     
         Signed-off-by: Martin Ågren <[e-mail]>
     
5:  f95e3f65e7 < -:  ---------- commit-graph-format.txt: fix "Hash Version" description