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

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

On Sat, Feb 27 2021, brian m. carlson wrote:

> We have in the past told users on the list that git archive does not
> necessarily produce stable archives, but we've never explicitly
> documented this.  Unfortunately, we've had people in the past who have
> relied on the relative stability of our archives to their detriment and
> then had breakage occur.
>
> Let's tell people that we don't guarantee stable archives so that they
> can make good choices about how they structure their tooling and don't
> end up with problems if we need to change archives later.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/git-archive.txt | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
> index 9f8172828d..1f126cbdcc 100644
> --- a/Documentation/git-archive.txt
> +++ b/Documentation/git-archive.txt
> @@ -30,6 +30,9 @@ extended pax header if the tar format is used; it can be extracted
>  using 'git get-tar-commit-id'. In ZIP files it is stored as a file
>  comment.
>  
> +The output of 'git archive' is not guaranteed to be stable and may change
> +between versions.

Is "stable archive" a well-known term people would understand, or is
someone going to read this thinking they might extract different content
today than tomorrow ? :) I wonder how much if anything this means to
someone not privy to the recent thread[1] that prompted this patch.

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.

1. https://lore.kernel.org/git/20210122213954.7dlnnpngjoay3oia@chatter.i7.local/