Re: [PATCH 4/4] docs: note that archives are not stable

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Feb 28, 2021, 18:19 UTC
Message-ID: <YDvexO2NFM0KZ1Jo@camp.crustytoothpaste.net>
In-Reply-To: <87h7lwl5mv.fsf@evledraar.gmail.com>

On 2021-02-28 at 12:48:56, Ævar Arnfjörð Bjarmason wrote:

Show 17 quoted lines

> Perhaps something like this instead:
> 
>     The output of 'git archive' is guaranteed to be the same across
>     versions of git, but the archive itself is not guaranteed to be
>     bit-for-bit identical.
> 
>     In practice the output of 'git archive' is relatively stable across
>     git versions, but has changed in the past, and most likely will in
>     the future.
> 
>     Since the tar format provides multiple ways to encode the same
>     output (ordering, headers, padding etc.) you should not rely on
>     output being bit-for-bit identical across versions of git for
>     e.g. GPG signing a SHA-256 hash of an archive generated with one
>     version of git, and then expecting to be able to validate that GPG
>     signature with a freshly generated archive made with same arguments
>     on another version of git.

I think something like this is good. I'm a bit nervous about telling people that the output is relatively stable because that will likely push people in the direction that we don't want to encourage. I might rephrase the first two paragraphs as so:

  The output of 'git archive' is guaranteed to be the same across
  versions of git, but the archive itself is not guaranteed to be
  bit-for-bit identical.  The output of 'git archive' has changed
  in the past, and most likely will in the future.

I'm not very familiar with the zip format, but I assume that it also has features that allow equivalent but not bit-for-bit equal archives. Looking at Wikipedia leads me to believe that one could indeed create different archives just by either writing a Zip64 record or not, and if we store the SHA-1 revision ID in a comment, then we would also produce a different archive when using an equivalent SHA-256 repo. And of course there's compression, which allows many different but equivalent serializations. So we'd probably need to say the same thing about zip files as well.

-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US