Re: [PATCH v13 06/13] reftable: define version 2 of the spec to accomodate SHA256

From: Junio C Hamano <gitster@pobox.com>
Date: May 19, 2020, 22:32 UTC
Message-ID: <xmqq5zcrzhc7.fsf@gitster.c.googlers.com>
In-Reply-To: <1e3c8f2d3e8c6c6db8460f29115d2fe898f85012.1589226388.git.gitgitgadget@gmail.com>

"Han-Wen Nienhuys via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 22 quoted lines

> From: Han-Wen Nienhuys <hanwen@google.com>
>
> Version appends a hash ID to the file header, making it slightly larger.
>
> This commit also changes "SHA-1" into "object ID" in many places.
>
> Signed-off-by: Han-Wen Nienhuys <hanwen@google.com>
> ---
>  Documentation/technical/reftable.txt | 79 ++++++++++++++++------------
>  1 file changed, 44 insertions(+), 35 deletions(-)
>
> diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt
> index 6223538d64e..1464c4e7437 100644
> --- a/Documentation/technical/reftable.txt
> +++ b/Documentation/technical/reftable.txt
> @@ -29,7 +29,7 @@ Objectives
>  
>  * Near constant time lookup for any single reference, even when the
>  repository is cold and not in process or kernel cache.
> -* Near constant time verification if a SHA-1 is referred to by at least
> +* Near constant time verification if an object ID is referred to by at least
>  one reference (for allow-tip-sha1-in-want).

Good.  These are called "object names", though.

Show 47 quoted lines

> @@ -193,8 +193,8 @@ and non-aligned files.
>  Very small files (e.g. a single ref block) may omit `padding` and the ref
>  index to reduce total file size.
>  
> -Header
> -^^^^^^
> +Header (version 1)
> +^^^^^^^^^^^^^^^^^^
>  
>  A 24-byte header appears at the beginning of the file:
>  
> @@ -215,6 +215,27 @@ used in a stack for link:#Update-transactions[transactions], these
>  fields can order the files such that the prior file’s
>  `max_update_index + 1` is the next file’s `min_update_index`.
>  
> +Header (version 2)
> +^^^^^^^^^^^^^^^^^^
> +
> +A 28-byte header appears at the beginning of the file:
> +
> +....
> +'REFT'
> +uint8( version_number = 2 )
> +uint24( block_size )
> +uint64( min_update_index )
> +uint64( max_update_index )
> +uint32( hash_id )
> +....
> +
> +The header is identical to `version_number=1`, with the 4-byte hash ID
> +("sha1" for SHA1 and "s256" for SHA-256) append to the header.
> +
> +For maximum backward compatibility, it is recommended to use version 1 when
> +writing SHA1 reftables.
> +
> +
>  First ref block
>  ^^^^^^^^^^^^^^^
>  
> @@ -302,8 +323,8 @@ The `value` follows. Its format is determined by `value_type`, one of
>  the following:
>  
>  * `0x0`: deletion; no value data (see transactions, below)
> -* `0x1`: one 20-byte object id; value of the ref
> -* `0x2`: two 20-byte object ids; value of the ref, peeled target
> +* `0x1`: one object id; value of the ref
> +* `0x2`: two object ids; value of the ref, peeled target

Ah, OK, I pointed out these future-proofing for the previous step, but as long as the end result is written in a hash-algorithm agnostic way, it is OK. Again these are called "object names", though.

>  * `0x3`: symbolic reference: `varint( target_len ) target`

Show 6 quoted lines

> @@ -434,7 +455,7 @@ works the same as in reference blocks.
>  
>  Because object identifiers are abbreviated by writers to the shortest
>  unique abbreviation within the reftable, obj key lengths are variable
> -between 2 and 20 bytes. Readers must compare only for common prefix
> +between 2 and 32 bytes. Readers must compare only for common prefix

Is it allowed for a reftable file whose hash_id field says "sha1" to use more than 20 bytes of obj key? Phrasing it like "unique prefix of object name, no shorter than 2 bytes" would avoid the problem, I would think.

This version also adds more

’

apostrophes, where we would prefer to place vanilla single quotes, which may need to be corrected in the conversion toolchain.

I did not see any new typo introduced in this step.

Thanks.