Subject: Re: [RFC PATCH] fast-export, fast-import: Let tags specify an internal name

From: Junio C Hamano <[email-masked]>
Date: Tue, 20 Apr 2021 14:40:37 -0700

Luke Shumaker <[email-masked]> writes:

> That'd work fine if they're lightweight tags, but if they're annotated
> tags, then after the rename the internal name in the tag object
> (`v0.0.1`) is now different than the refname (`gitk/v0.0.1`).  Which
> is still mostly fine, since not too many tools care if the internal
> name and the refname disagree.
>
> But, fast-export/fast-import are tools that do care: it's currently
> impossible to represent these tags in a fast-import stream.
>
> This patch adds an optional "name" sub-command to fast-import's "tag"
> top-level-command, the stream
>
>     tag foo
>     name bar
>     ...
>
> will create a tag at "refs/tags/foo" that says "tag bar" internally.
>
> These tags are things that "shouldn't" happen, so perhaps adding
> support for them to fast-export/fast-import is unwelcome, which is why
> I've marked this as an "RFC".  If this addition is welcome, then it
> still needs tests and documentation.

I actually think this is a good direction to go in, and it might be
even an acceptable change to fsck to require only the tail match of
tagname and refname so that it becomes perfectly OK for Gitk's
"v0.0.1" tag to be stored at say "refs/tags/gitk/v0.0.1".

> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
> index 39cfa05b28..6514b42d28 100644
> --- a/Documentation/git-fast-import.txt
> +++ b/Documentation/git-fast-import.txt
> @@ -824,6 +824,7 @@ lightweight (non-annotated) tags see the `reset` command below.
>  ....
>  	'tag' SP <name> LF
>  	mark?
> +	('name' SP <name> LF)?
>  	'from' SP <commit-ish> LF
>  	original-oid?
>  	'tagger' (SP <name>)? SP LT <email> GT SP <when> LF

The documentation after this part must be updated, too.  Here is my
attempt.

 Documentation/git-fast-import.txt | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git c/Documentation/git-fast-import.txt w/Documentation/git-fast-import.txt
index 39cfa05b28..c3c5a7ed16 100644
--- c/Documentation/git-fast-import.txt
+++ w/Documentation/git-fast-import.txt
@@ -822,22 +822,28 @@ Creates an annotated tag referring to a specific commit.  To create
 lightweight (non-annotated) tags see the `reset` command below.
 
 ....
-	'tag' SP <name> LF
+	'tag' SP <refname> LF
 	mark?
+	('name' SP <tagname> LF)?
 	'from' SP <commit-ish> LF
 	original-oid?
 	'tagger' (SP <name>)? SP LT <email> GT SP <when> LF
 	data
 ....
 
-where `<name>` is the name of the tag to create.
+where `<refname>` is also used as `<tagname>` if `name` option is
+not given.
 
-Tag names are automatically prefixed with `refs/tags/` when stored
+The `<tagname>` is used as the name of the tag that is stored in the
+tag object, while the `<refname>` determines where in the ref hierarchy
+the tag reference that points at the resulting tag object goes.
+
+The `<refname>` is prefixed with `refs/tags/` when stored
 in Git, so importing the CVS branch symbol `RELENG-1_0-FINAL` would
-use just `RELENG-1_0-FINAL` for `<name>`, and fast-import will write the
+use just `RELENG-1_0-FINAL` for `<refname>`, and fast-import will write the
 corresponding ref as `refs/tags/RELENG-1_0-FINAL`.
 
-The value of `<name>` must be a valid refname in Git and therefore
+The `<refname>` must be a valid refname in Git and therefore
 may contain forward slashes.  As `LF` is not valid in a Git refname,
 no quoting or escaping syntax is supported here.