patch, 2 partsDocumentation updates for SHA-256

> Now that we have SHA-256 support for packs and indices, let's document
> that in SHA-256 repositories, we use SHA-256 instead of SHA-1 for object
> names and checksums.  Instead of duplicating this information throughout
> the document, let's just document that in SHA-1 repositories, we use
> SHA-1 for these purposes, and in SHA-256 repositories, we use SHA-256.
> 
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/technical/pack-format.txt | 36 ++++++++++++++-----------
>  1 file changed, 21 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt
> index d3a142c652..f4c8d94f73 100644
> --- a/Documentation/technical/pack-format.txt
> +++ b/Documentation/technical/pack-format.txt
> @@ -1,6 +1,12 @@
>  Git pack format
>  ===============
>  
> +== Checksums and object IDs
> +
> +In a repository using the traditional SHA-1, pack checksums, index checksums,
> +and object IDs (object names) mentioned below are all computed using SHA-1.
> +Similarly, in SHA-256 repositories, these values are computed using SHA-256.
> +
>  == pack-*.pack files have the following format:
>  
>     - A header appears at the beginning and consists of the following:
> @@ -26,7 +32,7 @@ Git pack format
>  
>       (deltified representation)
>       n-byte type and length (3-bit type, (n-1)*7+4-bit length)
> -     20-byte base object name if OBJ_REF_DELTA or a negative relative
> +     base object name if OBJ_REF_DELTA or a negative relative
>  	 offset from the delta object's position in the pack if this
>  	 is an OBJ_OFS_DELTA object
>       compressed delta data
> @@ -34,7 +40,7 @@ Git pack format
>       Observation: length of each object is encoded in a variable
>       length format and is not constrained to 32-bit or anything.
>  
> -  - The trailer records 20-byte SHA-1 checksum of all of the above.
> +  - The trailer records a pack checksum of all of the above.
>  
>  === Object types
>  
> @@ -58,8 +64,8 @@ ofs-delta and ref-delta, which is only valid in a pack file.
>  
>  Both ofs-delta and ref-delta store the "delta" to be applied to
>  another object (called 'base object') to reconstruct the object. The
> -difference between them is, ref-delta directly encodes 20-byte base
> -object name. If the base object is in the same pack, ofs-delta encodes
> +difference between them is, ref-delta directly encodes base object
> +name. If the base object is in the same pack, ofs-delta encodes
>  the offset of the base object in the pack instead.
>  
>  The base object could also be deltified if it's in the same pack.
> @@ -143,14 +149,14 @@ This is the instruction reserved for future expansion.
>      object is stored in the packfile as the offset from the
>      beginning.
>  
> -    20-byte object name.
> +    one object name of the appropriate size.
>  
>    - The file is concluded with a trailer:
>  
> -    A copy of the 20-byte SHA-1 checksum at the end of
> -    corresponding packfile.
> +    A copy of the pack checksum at the end of the corresponding
> +    packfile.
>  
> -    20-byte SHA-1-checksum of all of the above.
> +    Index checksum of all of the above.
>  
>  Pack Idx file:
>  
> @@ -198,7 +204,7 @@ Pack file entry: <+
>          If it is not DELTA, then deflated bytes (the size above
>  		is the size before compression).
>  	If it is REF_DELTA, then
> -	  20-byte base object name SHA-1 (the size above is the
> +	  base object name (the size above is the
>  		size of the delta data that follows).
>            delta data, deflated.
>  	If it is OFS_DELTA, then
> @@ -227,9 +233,9 @@ Pack file entry: <+
>  
>    - A 256-entry fan-out table just like v1.
>  
> -  - A table of sorted 20-byte SHA-1 object names.  These are
> -    packed together without offset values to reduce the cache
> -    footprint of the binary search for a specific object name.
> +  - A table of sorted object names.  These are packed together
> +    without offset values to reduce the cache footprint of the
> +    binary search for a specific object name.
>  
>    - A table of 4-byte CRC32 values of the packed object data.
>      This is new in v2 so compressed data can be copied directly
> @@ -248,10 +254,10 @@ Pack file entry: <+
>  
>    - The same trailer as a v1 pack file:
>  
> -    A copy of the 20-byte SHA-1 checksum at the end of
> +    A copy of the pack checksum at the end of
>      corresponding packfile.
>  
> -    20-byte SHA-1-checksum of all of the above.
> +    Index checksum of all of the above.
>  
>  == multi-pack-index (MIDX) files have the following format:
>  
> @@ -329,4 +335,4 @@ CHUNK DATA:
>  
>  TRAILER:
>  
> -	20-byte SHA1-checksum of the above contents.
> +	Index checksum of the above contents.

>
> One of the required steps for the objectFormat extension is to implement
> the loose object index.  However, without support for
> compatObjectFormat, we don't even know if the loose object index is
> needed, so it makes sense to move that step to the compatObjectFormat
> section.  Do so.

> The main thing is to focus on compatibility of the .git directory
> as a whole (and the protocol, as we move into inter-operability mode).
>
> [1] https://lore.kernel.org/git/CAN0heSptiJL9d86ZeNPMUaZeTA68juwTyf3K-uWR=K-vt=1Hrg@mail.gmail.com/
>
>>  This series updates the pack and
>> index documentation to reflect that these formats can handle SHA-256,
>> and updates the transition plan to reflect what we've implemented and
>> what the next steps are.
>
> These patches are good to help clarify these formats in the new world.

> Derrick Stolee <stolee@gmail.com> writes:
> 
> > Is that really a concern? Maybe, but also Git will never move data like
> > that.
> 
> I would say that we can safely say that this year ;-) as dumb HTTP
> would be mostly dead.

> On 2020-08-14 at 04:47:19, Junio C Hamano wrote:
>> Derrick Stolee <stolee@gmail.com> writes:
>> 
>> > Is that really a concern? Maybe, but also Git will never move data like
>> > that.
>> 
>> I would say that we can safely say that this year ;-) as dumb HTTP
>> would be mostly dead.
>
> We do fetch the refs first for dumb HTTP so last I checked, we correctly
> detected this case and failed.  I'd personally be happy to let the
> DAV-based protocol die, but there are folks who like it.

>
> As was pointed out recently, some of our documentation doesn't properly
> reflect the new support for SHA-256.  This series updates the pack and
> index documentation to reflect that these formats can handle SHA-256,
> and updates the transition plan to reflect what we've implemented and
> what the next steps are.

> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  Documentation/technical/http-protocol.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
> index 51a79e63de..507f28f9b3 100644
> --- a/Documentation/technical/http-protocol.txt
> +++ b/Documentation/technical/http-protocol.txt
> @@ -401,8 +401,9 @@ at all in the request stream:
>  The stream is terminated by a pkt-line flush (`0000`).
>  
>  A single "want" or "have" command MUST have one hex formatted
> -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.)
>  
>  The `have` list is created by popping the first 32 commits
>  from `c_pending`.  Less can be supplied if `c_pending` empties.

> Martin Ågren <martin.agren@gmail.com> writes:
> 
> > 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.
> 
> Ehh, doesn't this directly contradict the transition plan of "on the
> wire everything will use SHA-1 version for now?"

>
> On 2020-08-14 at 17:28:27, Junio C Hamano wrote:
> > Martin Ågren <martin.agren@gmail.com> writes:
> >
> > > 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.
> >
> > Ehh, doesn't this directly contradict the transition plan of "on the
> > wire everything will use SHA-1 version for now?"

> SHA-256 repositories interoperate currently using SHA-256 object IDs.
> It was originally intended that we wouldn't update the protocol, but
> that leads to much of the testsuite failing since it's impossible to
> move objects from one place to another.
>
> If we wanted to be more pedantically correct and optimize for the
> future, we could say that the values use the format negotiated by the
> "object-format" protocol extension and SHA-1 otherwise.

> On 2020-08-14 at 17:28:27, Junio C Hamano wrote:
>> Martin Ågren <martin.agren@gmail.com> writes:
>> 
>> > 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.
>> 
>> Ehh, doesn't this directly contradict the transition plan of "on the
>> wire everything will use SHA-1 version for now?"
>
> SHA-256 repositories interoperate currently using SHA-256 object IDs.
> It was originally intended that we wouldn't update the protocol, but
> that leads to much of the testsuite failing since it's impossible to
> move objects from one place to another.
>
> If we wanted to be more pedantically correct and optimize for the
> future, we could say that the values use the format negotiated by the
> "object-format" protocol extension and SHA-1 otherwise.

> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>
>> On 2020-08-14 at 17:28:27, Junio C Hamano wrote:
>>> Martin Ågren <martin.agren@gmail.com> writes:
>>> 
>>> > 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.
>>> 
>>> Ehh, doesn't this directly contradict the transition plan of "on the
>>> wire everything will use SHA-1 version for now?"
>>
>> SHA-256 repositories interoperate currently using SHA-256 object IDs.
>> It was originally intended that we wouldn't update the protocol, but
>> that leads to much of the testsuite failing since it's impossible to
>> move objects from one place to another.
>>
>> If we wanted to be more pedantically correct and optimize for the
>> future, we could say that the values use the format negotiated by the
>> "object-format" protocol extension and SHA-1 otherwise.

> 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.
> 
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  Documentation/technical/protocol-capabilities.txt | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
> index 36ccd14f97..47f1b30090 100644
> --- a/Documentation/technical/protocol-capabilities.txt
> +++ b/Documentation/technical/protocol-capabilities.txt
> @@ -324,15 +324,18 @@ allow-tip-sha1-in-want
>  ----------------------
>  
>  If the upload-pack server advertises this capability, fetch-pack may
> -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.)
>  
>  allow-reachable-sha1-in-want
>  ----------------------------
>  
>  If the upload-pack server advertises this capability, fetch-pack may
> -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.)

>
> On 8/14/2020 8:21 AM, Martin Ågren wrote:
> >
> >  If the upload-pack server advertises this capability, fetch-pack may
> > -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.)
> >
> >  allow-reachable-sha1-in-want
> >  ----------------------------
> >
> >  If the upload-pack server advertises this capability, fetch-pack may
> > -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.)
>
> This "as above" is brittle to future changes.

> I think it
> could be improved with
>
>         (As in "allow-tip-sha1-in-want", the "sha1" in this capability
>         refers to object names, not the hash algorithm chosen for the
>         repository.)
>
> Or, just repeat the same note again.

> 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.
>
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  Documentation/technical/protocol-capabilities.txt | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
> index 36ccd14f97..47f1b30090 100644
> --- a/Documentation/technical/protocol-capabilities.txt
> +++ b/Documentation/technical/protocol-capabilities.txt
> @@ -324,15 +324,18 @@ allow-tip-sha1-in-want
>  ----------------------
>  
>  If the upload-pack server advertises this capability, fetch-pack may
> -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.)

>
> Martin Ågren <martin.agren@gmail.com> writes:
>
> > 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.
> >
> > Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> > ---
> >  Documentation/technical/protocol-capabilities.txt | 11 +++++++----
> >  1 file changed, 7 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
> > index 36ccd14f97..47f1b30090 100644
> > --- a/Documentation/technical/protocol-capabilities.txt
> > +++ b/Documentation/technical/protocol-capabilities.txt
> > @@ -324,15 +324,18 @@ allow-tip-sha1-in-want
> >  ----------------------
> >
> >  If the upload-pack server advertises this capability, fetch-pack may
> > -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.)
>
> I think we should have either a new sha256 capability or a more
> generic hash-algo capability whose value can be set to sha256.
> Neither the connection initiators or the acceptors should talk
> in sha256 until both ends agreed to do so.

>> I think we should have either a new sha256 capability or a more
>> generic hash-algo capability whose value can be set to sha256.
>> Neither the connection initiators or the acceptors should talk
>> in sha256 until both ends agreed to do so.
>
> I think we should, and I think we do. I haven't dug into the details,
> but "object-format" looks like it's just that.

> We say that value 1 means "SHA-1", but in fact, it means "whatever
> the_hash_algo is", see commit c166599862 ("commit-graph: convert to
> using the_hash_algo", 2018-11-14).
> 
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  If we want to be more fine-grained in the future, we'll need to say,
>  e.g., "2 means SHA-1, 3 means SHA-256" or, perhaps preferrably, bump the
>  version number.
> 
>  I wonder: Should we instead say "1 means SHA-1, 2 means SHA-256"? It
>  could be implemented as "easily" as "if (value_from_header !=
>  value_from_the_hash_algo) die(...);" for now. Might that pay off in the
>  long run?
> 
>  This relates to Stolee's "in a vacuum" comment [1] ... so maybe we're
>  fine.

>  [1] https://lore.kernel.org/git/da077fb0-14bb-b84f-c526-d759ebc9f5eb@gmail.com/
> 
>  Documentation/technical/commit-graph-format.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt
> index 440541045d..3535426d32 100644
> --- a/Documentation/technical/commit-graph-format.txt
> +++ b/Documentation/technical/commit-graph-format.txt
> @@ -42,8 +42,8 @@ HEADER:
>    1-byte version number:
>        Currently, the only valid version is 1.
>  
> -  1-byte Hash Version (1 = SHA-1)
> -      We infer the hash length (H) from this value.
> +  1-byte Hash Version (1 = SHA-1 in SHA-1 repo, SHA-256 in SHA-256 repo)
> +      We infer the hash length (H) from the hash algo derived from this value.

>
> On 8/14/2020 8:21 AM, Martin Ågren wrote:
> > We say that value 1 means "SHA-1", but in fact, it means "whatever
> > the_hash_algo is", see commit c166599862 ("commit-graph: convert to
> > using the_hash_algo", 2018-11-14).
> >
> > Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> > ---
> >  If we want to be more fine-grained in the future, we'll need to say,
> >  e.g., "2 means SHA-1, 3 means SHA-256" or, perhaps preferrably, bump the
> >  version number.
> >
> >  I wonder: Should we instead say "1 means SHA-1, 2 means SHA-256"? It
> >  could be implemented as "easily" as "if (value_from_header !=
> >  value_from_the_hash_algo) die(...);" for now. Might that pay off in the
> >  long run?
> >
> >  This relates to Stolee's "in a vacuum" comment [1] ... so maybe we're
> >  fine.
>
> I think that was the intention of the byte, but that is not what ended
> up happening.

> [1] https://lore.kernel.org/git/pull.676.v2.git.1596941624.gitgitgadget@gmail.com/
>
> [2] https://lore.kernel.org/git/cover.1597178914.git.me@ttaylorr.com/
>
> >
> > -  1-byte Hash Version (1 = SHA-1)
> > -      We infer the hash length (H) from this value.
> > +  1-byte Hash Version (1 = SHA-1 in SHA-1 repo, SHA-256 in SHA-256 repo)
> > +      We infer the hash length (H) from the hash algo derived from this value.
>
> If we are _not_ changing the format to have a meaningful value in
> this byte, then this documentation should be updated to state that
> this byte must always have value 1, as it does not provide any
> information.

> 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.
> 
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  Documentation/technical/index-format.txt | 27 +++++++++++++-----------
>  1 file changed, 15 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
> index faa25c5c52..827ece2ed1 100644
> --- a/Documentation/technical/index-format.txt
> +++ b/Documentation/technical/index-format.txt
> @@ -3,8 +3,11 @@ Git index format
>  
>  == The Git index file has the following format
>  
> -  All binary numbers are in network byte order. Version 2 is described
> -  here unless stated otherwise.
> +  All binary numbers are in network byte order.
> +  In a repository using the traditional SHA-1, checksums and object IDs
> +  (object names) mentioned below are all computed using SHA-1.  Similarly,
> +  in SHA-256 repositories, these values are computed using SHA-256.
> +  Version 2 is described here unless stated otherwise.
>  
>     - A 12-byte header consisting of
>  
> @@ -32,7 +35,7 @@ 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.

>  == Index entry
> @@ -80,7 +83,7 @@ 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

>    A 16-bit 'flags' field split into (high to low bits)
>  
> @@ -211,8 +214,8 @@ Git index format
>  
>    The extension consists of:
>  
> -  - 160-bit SHA-1 of the shared index file. The shared index file path
> -    is $GIT_DIR/sharedindex.<SHA-1>. If all 160 bits are zero, the
> +  - Hash of the shared index file. The shared index file path
> +    is $GIT_DIR/sharedindex.<hash>. If all bits are zero, the
>      index does not require a shared index file.
>  
>    - An ewah-encoded delete bitmap, each bit represents an entry in the
> @@ -253,10 +256,10 @@ Git index format
>  
>    - 32-bit dir_flags (see struct dir_struct)
>  
> -  - 160-bit SHA-1 of $GIT_DIR/info/exclude. Null SHA-1 means the file
> +  - Hash of $GIT_DIR/info/exclude. A null hash means the file
>      does not exist.
>  
> -  - 160-bit SHA-1 of core.excludesfile. Null SHA-1 means the file does
> +  - Hash of core.excludesfile. A null hash means the file does
>      not exist.
>  
>    - NUL-terminated string of per-dir exclude file name. This usually
> @@ -285,13 +288,13 @@ The remaining data of each directory block is grouped by type:
>    - An ewah bitmap, the n-th bit records "check-only" bit of
>      read_directory_recursive() for the n-th directory.
>  
> -  - An ewah bitmap, the n-th bit indicates whether SHA-1 and stat data
> +  - An ewah bitmap, the n-th bit indicates whether hash and stat data
>      is valid for the n-th directory and exists in the next data.
>  
>    - An array of stat data. The n-th data corresponds with the n-th
>      "one" bit in the previous ewah bitmap.
>  
> -  - An array of SHA-1. The n-th SHA-1 corresponds with the n-th "one" bit
> +  - An array of hashes. The n-th hash corresponds with the n-th "one" bit
>      in the previous ewah bitmap.
>  
>    - One NUL.
> @@ -330,12 +333,12 @@ The remaining data of each directory block is grouped by type:
>  
>    - 32-bit offset to the end of the index entries
>  
> -  - 160-bit SHA-1 over the extension types and their sizes (but not
> +  - Hash over the extension types and their sizes (but not
>  	their contents).  E.g. if we have "TREE" extension that is N-bytes
>  	long, "REUC" extension that is M-bytes long, followed by "EOIE",
>  	then the hash would be:
>  
> -	SHA-1("TREE" + <binary representation of N> +
> +	Hash("TREE" + <binary representation of N> +
>  		"REUC" + <binary representation of M>)
>  
>  == Index Entry Offset Table
> 

>
> On 8/14/2020 8:21 AM, Martin Ågren wrote:
> > -   - 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.
>
> If this hash is flexible, then "160-bit" is not correct anymore, right?
>
> > -  160-bit SHA-1 for the represented object
> > +  160-bit object name for the represented object
>
> Same here. The later instances of "160-bit" were dropped.

> Hi brian,
> 
> On Fri, 14 Aug 2020 at 00:49, brian m. carlson <sandals@crustytoothpaste.net> wrote:
> >
> > As was pointed out recently, some of our documentation doesn't properly
> > reflect the new support for SHA-256.  This series updates the pack and
> > index documentation to reflect that these formats can handle SHA-256,
> > and updates the transition plan to reflect what we've implemented and
> > what the next steps are.
> 
> Thanks, this looks great. Now we're making clear what it is we intend to
> be doing.
> 
> What about these additional patches on top? These are based on my
> understanding, but hopefully they're not *too* wrong. I'm a bit hesitant
> about the final patch and it would be interesting to know what you
> think.