Re: [PATCH v5 4/6] git-fast-export.txt: clarify why 'verbatim' may not be a good idea

From: Elijah Newren <newren@gmail.com>
Date: Feb 24, 2025, 19:26 UTC
Message-ID: <CABPp-BFG=g_tCz5HjjsLXNc41aYiGvLi_8oq3d5o9cBLKmd1og@mail.gmail.com>
In-Reply-To: <20250224142744.279643-5-christian.couder@gmail.com>

On Mon, Feb 24, 2025 at 6:28 AM Christian Couder <christian.couder@gmail.com> wrote:

Show 32 quoted lines

>
> From: Luke Shumaker <lukeshu@datawire.io>
>
> Signed-off-by: Luke Shumaker <lukeshu@datawire.io>
> Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> ---
>  Documentation/git-fast-export.adoc | 10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc
> index ab9a315fa9..1b19f17b78 100644
> --- a/Documentation/git-fast-export.adoc
> +++ b/Documentation/git-fast-export.adoc
> @@ -29,15 +29,19 @@ OPTIONS
>
>  --signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)::
>         Specify how to handle signed tags.  Since any transformation
> -       after the export can change the tag names (which can also happen
> -       when excluding revisions) the signatures will not match.
> +       after the export (or during the export, such as excluding
> +       revisions) can change the hashes being signed, the signatures
> +       may become invalid.
>  +
>  When asking to 'abort' (which is the default), this program will die
>  when encountering a signed tag.  With 'strip', the tags will silently
>  be made unsigned, with 'warn-strip' they will be made unsigned but a
>  warning will be displayed, with 'verbatim', they will be silently
>  exported and with 'warn-verbatim' (or 'warn', a deprecated synonym),
> -they will be exported, but you will see a warning.
> +they will be exported, but you will see a warning.  'verbatim' and
> +'warn-verbatim' should only be used if you know that no
> +transformation affecting tags will be performed, or if you do not

perhaps it'd be worth clarifying this slightly to

"...transformation affecting tags or any commit in their history will be performed..."

Although, I'm not sure if that's strong enough either. Even if users don't transform the fast-export output, the fast-export output will have already possibly undergone transformations and fast-import might send it through more. For example, if someone had a permission recorded as 644 or 100640 it'd be canonicalized to 100644. If they had a duplicate tree entry or an improperly sorted tree in their history, that would be corrected by fast-export + fast-import. If they had extended headers other than a commit signature, those would be dropped. So, maybe it needs to be something more like

"..transformation affecting tags or any commit in their history will be performed by you or by fast-export or fast-import, or if you do not....

Show 6 quoted lines

> +care that the resulting tag will have an invalid signature.
>
>  --tag-of-filtered-object=(abort|drop|rewrite)::
>         Specify how to handle tags whose tagged object is filtered out.
> --
> 2.48.1.401.g48e0d4203c