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

[Christian Couder <christian.couder@gmail.com>]

On Mon, Feb 24, 2025 at 8:26 PM Elijah Newren <newren@gmail.com> wrote:
>
> On Mon, Feb 24, 2025 at 6:28 AM Christian Couder
> <christian.couder@gmail.com> wrote:
> >
> > 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....

I agree it's better like this, so this is used in the next version.

> > +care that the resulting tag will have an invalid signature.

Thanks!