Skip to content

more SHA-256 documentation

Martin Ågren git 2 versions – New

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v2 Latest4 patches 0 repliesNew
  2. v15 patches 15 repliesSuperseded

Patches in v2 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/4http-protocol.txt: document SHA-256 "want"/"have" formatDocumentation/technical/http-protocol.txt+3 -20 replies
2/4index-format.txt: document SHA-256 index formatDocumentation/technical/index-format.txt+18 -160 replies
3/4protocol-capabilities.txt: clarify "allow-x-sha1-in-want" re SHA-256Documentation/technical/protocol-capabilities.txt+8 -40 replies
4/4shallow.txt: document SHA-256 shallow formatDocumentation/technical/shallow.txt+1 -10 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v2 yet.

Read the v2 thread

Cover letter [PATCH v2 0/4] more SHA-256 documentation

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.

@@ 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.

@@ 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.

@@ 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.

5: f95e3f65e7 < -: ---------- commit-graph-format.txt: fix "Hash Version" description

Signature · 1 line
2.28.0.297.g1956fa8f8d