git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: "Martin Ågren" <martin.agren@gmail.com>
To: git@vger.kernel.org
Cc: "brian m. carlson" <sandals@crustytoothpaste.net>,
	Derrick Stolee <stolee@gmail.com>,
	Junio C Hamano <gitster@pobox.com>
Subject: [PATCH v2 0/4] more SHA-256 documentation
Date: Sat, 15 Aug 2020 18:05:58 +0200	[thread overview]
Message-ID: <cover.1597506837.git.martin.agren@gmail.com> (raw)
In-Reply-To: <cover.1597406877.git.martin.agren@gmail.com>

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 <martin.agren@gmail.com>
     
    @@ 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 <martin.agren@gmail.com>
     
    @@ 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 <martin.agren@gmail.com>
     
    @@ 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 <martin.agren@gmail.com>
     
5:  f95e3f65e7 < -:  ---------- commit-graph-format.txt: fix "Hash Version" description
-- 
2.28.0.297.g1956fa8f8d


  parent reply	other threads:[~2020-08-15 21:52 UTC|newest]

Thread overview: 35+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-13 22:48 [PATCH 0/2] Documentation updates for SHA-256 brian m. carlson
2020-08-13 22:49 ` [PATCH 1/2] docs: document SHA-256 pack and indices brian m. carlson
2020-08-14  2:26   ` Derrick Stolee
2020-08-13 22:49 ` [PATCH 2/2] docs: fix step in transition plan brian m. carlson
2020-08-14 12:21   ` Martin Ågren
2020-08-14  2:33 ` [PATCH 0/2] Documentation updates for SHA-256 Derrick Stolee
2020-08-14  4:47   ` Junio C Hamano
2020-08-14 20:20     ` brian m. carlson
2020-08-14 20:25       ` Junio C Hamano
2020-08-14 12:21 ` [PATCH 0/5] more SHA-256 documentation Martin Ågren
2020-08-14 12:21   ` [PATCH 1/5] http-protocol.txt: document SHA-256 "want"/"have" format Martin Ågren
2020-08-14 17:28     ` Junio C Hamano
2020-08-14 20:23       ` brian m. carlson
2020-08-14 20:32         ` Martin Ågren
2020-08-14 20:39         ` Junio C Hamano
2020-08-14 20:47           ` Junio C Hamano
2020-08-14 12:21   ` [PATCH 2/5] index-format.txt: document SHA-256 index format Martin Ågren
2020-08-14 12:28     ` Derrick Stolee
2020-08-14 14:05       ` Martin Ågren
2020-08-14 12:21   ` [PATCH 3/5] protocol-capabilities.txt: clarify "allow-x-sha1-in-want" re SHA-256 Martin Ågren
2020-08-14 12:31     ` Derrick Stolee
2020-08-14 14:05       ` Martin Ågren
2020-08-14 17:33     ` Junio C Hamano
2020-08-14 20:35       ` Martin Ågren
2020-08-14 20:43         ` Junio C Hamano
2020-08-14 12:21   ` [PATCH 4/5] shallow.txt: document SHA-256 shallow format Martin Ågren
2020-08-14 12:21   ` [PATCH 5/5] commit-graph-format.txt: fix "Hash Version" description Martin Ågren
2020-08-14 12:37     ` Derrick Stolee
2020-08-14 14:10       ` Martin Ågren
2020-08-14 20:28   ` [PATCH 0/5] more SHA-256 documentation brian m. carlson
2020-08-15 16:05   ` Martin Ågren [this message]
2020-08-15 16:05     ` [PATCH v2 1/4] http-protocol.txt: document SHA-256 "want"/"have" format Martin Ågren
2020-08-15 16:06     ` [PATCH v2 2/4] index-format.txt: document SHA-256 index format Martin Ågren
2020-08-15 16:06     ` [PATCH v2 3/4] protocol-capabilities.txt: clarify "allow-x-sha1-in-want" re SHA-256 Martin Ågren
2020-08-15 16:06     ` [PATCH v2 4/4] shallow.txt: document SHA-256 shallow format Martin Ågren

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=cover.1597506837.git.martin.agren@gmail.com \
    --to=martin.agren@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=sandals@crustytoothpaste.net \
    --cc=stolee@gmail.com \
    --subject='Re: [PATCH v2 0/4] more SHA-256 documentation' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).