Add tagName option to customize generated tag name

src/NerdBank.GitVersioning/VersionOptions.cs

@@ -46,6 +46,11 @@ public class VersionOptions : IEquatable<VersionOptions>
     /// </summary>
     private const int DefaultSemVer1NumericIdentifierPadding = 4;
 
+    /// <summary>
+    /// The default value for the <see cref="TagName"/> property.
+    /// </summary>
+    private const string DefaultTagName = "v{version}";
+
     /// <summary>
     /// A value indicating whether mutations of this instance are not allowed.
     /// </summary>
@@ -109,6 +114,12 @@ public class VersionOptions : IEquatable<VersionOptions>
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private CloudBuildOptions? cloudBuild;
 
+    /// <summary>
+    /// Backing field for the <see cref="TagName"/> property.
+    /// </summary>
+    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
+    private string? tagName;
+
     /// <summary>
     /// Backing field for the <see cref="Release"/> property.
     /// </summary>
@@ -153,6 +164,7 @@ public VersionOptions(VersionOptions copyFrom)
         this.publicReleaseRefSpec = copyFrom.publicReleaseRefSpec?.ToList();
         this.cloudBuild = copyFrom.cloudBuild is object ? new CloudBuildOptions(copyFrom.cloudBuild) : null;
         this.release = copyFrom.release is object ? new ReleaseOptions(copyFrom.release) : null;
+        this.tagName = copyFrom.tagName;
         this.pathFilters = copyFrom.pathFilters?.ToList();
     }
 
@@ -472,6 +484,22 @@ public ReleaseOptions? Release
     [JsonIgnore]
     public ReleaseOptions ReleaseOrDefault => this.Release ?? ReleaseOptions.DefaultInstance;
 
+    /// <summary>
+    /// Gets or sets the tag name template for tagging.
+    /// </summary>
+    [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
+    public string? TagName
+    {
+        get => this.tagName;
+        set => this.SetIfNotReadOnly(ref this.tagName, value);
+    }
+
+    /// <summary>
+    /// Gets the tag name template for tagging.
+    /// </summary>
+    [JsonIgnore]
+    public string? TagNameOrDefault => this.TagName ?? DefaultTagName;
+
     /// <summary>
     /// Gets or sets a list of paths to use to filter commits when calculating version height.
     /// If a given commit does not affect any paths in this filter, it is ignored for version height calculations.

src/NerdBank.GitVersioning/version.schema.json

@@ -176,7 +176,7 @@
           "type": "object",
           "properties": {
             "branchName": {
-              "description": "Defines the format of release branch names. Format must include a placeholder '{version}' for the version",
+              "description": "Defines the format of release branch names. Format must include a placeholder '{version}' for the version.",
               "type": "string",
               "pattern": ".*\\{version\\}.*",
               "default": "v{version}"
@@ -188,13 +188,19 @@
               "default": "minor"
             },
             "firstUnstableTag": {
-              "description": "Specifies the first/default prerelease tag for new versions",
+              "description": "Specifies the first/default prerelease tag for new versions.",
               "type": "string",
               "default": "alpha"
             }
           },
           "additionalProperties": false
         },
+        "tagName": {
+          "description": "Defines the format of tag names. Format must include a placeholder '{version}' for the version.",
+          "type": "string",
+          "pattern": ".*\\{version\\}.*",
+          "default": "v{version}"
+        },
         "pathFilters": {
           "type": "array",
           "description": "An array of pathspec-like strings that are used to filter commits when calculating the version height. A commit will not increment the version height if its changed files are not included by these filters.\nPaths are relative to this file. Paths relative to the root of the repository can be specified with the `:/` prefix.\nExclusions can be specified with a `:^` prefix for relative paths, or a `:^/` prefix for paths relative to the root of the repository.\nAfter a path matches any non-exclude filter, it will be run through all exclude filters. If it matches, the path is ignored.",

src/nbgv/Program.cs

@@ -68,6 +68,7 @@ private enum ExitCodes
             PackageIdNotFound,
             ShallowClone,
             InternalError,
+            InvalidTagNameSetting,
         }
 
         private static bool AlwaysUseLibGit2 => string.Equals(Environment.GetEnvironmentVariable("NBGV_GitEngine"), "LibGit2", StringComparison.Ordinal);
@@ -545,6 +546,24 @@ private static Task<int> OnTagCommand(string project, string versionOrRef)
                 return Task.FromResult((int)ExitCodes.NoGitRepo);
             }
 
+            // get tag name format
+            VersionOptions versionOptions = context.VersionFile.GetVersion();
+            if (versionOptions is null)
+            {
+                Console.Error.WriteLine($"Failed to load version file for directory '{searchPath}'.");
+                return Task.FromResult((int)ExitCodes.NoVersionJsonFound);
+            }
+
+            string tagNameFormat = versionOptions.TagNameOrDefault;
+
+            // ensure there is a '{version}' placeholder in the tag name
+            if (string.IsNullOrEmpty(tagNameFormat) || !tagNameFormat.Contains("{version}"))
+            {
+                Console.Error.WriteLine($"Invalid 'tagName' setting '{tagNameFormat}'. Missing version placeholder '{{version}}'.");
+                return Task.FromResult((int)ExitCodes.InvalidTagNameSetting);
+            }
+
+            // get commit to tag
             LibGit2Sharp.Repository repository = context.Repository;
             if (!context.TrySelectCommit(versionOrRef))
             {
@@ -585,8 +604,12 @@ private static Task<int> OnTagCommand(string project, string versionOrRef)
                 return Task.FromResult((int)ExitCodes.NoVersionJsonFound);
             }
 
-            oracle.PublicRelease = true; // assume a public release so we don't get a redundant -gCOMMITID in the tag name
-            string tagName = $"v{oracle.SemVer2}";
+            // assume a public release so we don't get a redundant -gCOMMITID in the tag name
+            oracle.PublicRelease = true;
+
+            // replace the "{version}" placeholder with the actual version
+            string tagName = tagNameFormat.Replace("{version}", oracle.SemVer2);
+
             try
             {
                 context.ApplyTag(tagName);