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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Sun, Feb 28 2021, brian m. carlson wrote:

> On 2021-02-28 at 12:48:56, Ævar Arnfjörð Bjarmason wrote:
>> 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.

Yes, I think your version is better, and we should have some wording so
it generalizes to the various output formats we support, perhaps further
noting that the "relatively stable" (if you want to keep a note of that)
only refers to our own output, not when we invoke gzip or zip.

I thought that "relatively stable" and "[when you extract it you get the
same thing]" were good to note, to say that e.g. GPG signing across
versions = bad, but if you e.g. offer downloadable archives with the
contents of tags, there's no reason to make your git version a part of a
cache key for the purposes of saving yourself CPU time when
(re-)generating them.