Touch-up on usage of new switch

Author: AArnott

doc/nbgv-cli.md

@@ -167,9 +167,10 @@ In that case, the `NewBranch` property will be `null`.
 
 ### Customizing the `prepare-release` commit message
 
-By default, the `prepare-release` command generates a commit message with the format "Set version to {version}". So with this new option, You can add a prefix or suffix to the default commit message (which will replace just the version).
+By default, the `prepare-release` command generates a commit message with the format "Set version to {version}".
+A switch allows you to customize the commit message, using `{0}` as a placeholder for the version.
 
-For example, running the following command on `master`
+For example, running the following command:
 
 ```
 nbgv prepare-release --commit-message-pattern "Custom commit message pattern - {0} custom message"
@@ -178,9 +179,8 @@ nbgv prepare-release --commit-message-pattern "Custom commit message pattern - {
 So your commit message is going to be this:
 
 ```
-Custom commit message pattern '1.0' custom message
+Custom commit message pattern - 1.0 custom message
 ```
-**Note:** Must include {0} in the pattern to represent the version.
 
 ## Creating a version tag
 

src/NerdBank.GitVersioning/ReleaseManager.cs

@@ -1,6 +1,7 @@
 // Copyright (c) .NET Foundation and Contributors. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+using System.Globalization;
 using LibGit2Sharp;
 using Nerdbank.GitVersioning.LibGit2;
 using Newtonsoft.Json;
@@ -127,10 +128,10 @@ public enum ReleaseManagerOutputMode
     /// <param name="outputMode">
     /// The output format to use for writing to stdout.
     /// </param>
-    /// <param name="commitMessagePattern">
-    /// Custom pattern to add a prefix or suffix to the default commit message.
+    /// <param name="unformattedCommitMessage">
+    /// An optional, custom message to use for the commit that sets the new version number. May use <c>{0}</c> to substitute the new version number.
     /// </param>
-    public void PrepareRelease(string projectDirectory, string releaseUnstableTag = null, Version nextVersion = null, VersionOptions.ReleaseVersionIncrement? versionIncrement = null, ReleaseManagerOutputMode outputMode = default, string commitMessagePattern = "{0}")
+    public void PrepareRelease(string projectDirectory, string releaseUnstableTag = null, Version nextVersion = null, VersionOptions.ReleaseVersionIncrement? versionIncrement = null, ReleaseManagerOutputMode outputMode = default, string unformattedCommitMessage = null)
     {
         Requires.NotNull(projectDirectory, nameof(projectDirectory));
 
@@ -171,7 +172,7 @@ public void PrepareRelease(string projectDirectory, string releaseUnstableTag =
                 this.WriteToOutput(releaseInfo);
             }
 
-            this.UpdateVersion(context, versionOptions.Version, releaseVersion, commitMessagePattern);
+            this.UpdateVersion(context, versionOptions.Version, releaseVersion, unformattedCommitMessage);
             return;
         }
 
@@ -195,7 +196,7 @@ public void PrepareRelease(string projectDirectory, string releaseUnstableTag =
         // create release branch and update version
         Branch releaseBranch = repository.CreateBranch(releaseBranchName);
         global::LibGit2Sharp.Commands.Checkout(repository, releaseBranch);
-        this.UpdateVersion(context, versionOptions.Version, releaseVersion, commitMessagePattern);
+        this.UpdateVersion(context, versionOptions.Version, releaseVersion, unformattedCommitMessage);
 
         if (outputMode == ReleaseManagerOutputMode.Text)
         {
@@ -204,7 +205,7 @@ public void PrepareRelease(string projectDirectory, string releaseUnstableTag =
 
         // update version on main branch
         global::LibGit2Sharp.Commands.Checkout(repository, originalBranchName);
-        this.UpdateVersion(context, versionOptions.Version, nextDevVersion, commitMessagePattern);
+        this.UpdateVersion(context, versionOptions.Version, nextDevVersion, unformattedCommitMessage);
 
         if (outputMode == ReleaseManagerOutputMode.Text)
         {
@@ -264,7 +265,7 @@ private string GetReleaseBranchName(VersionOptions versionOptions)
         return branchNameFormat.Replace("{version}", versionOptions.Version.Version.ToString());
     }
 
-    private void UpdateVersion(LibGit2Context context, SemanticVersion oldVersion, SemanticVersion newVersion, string commitMessagePattern)
+    private void UpdateVersion(LibGit2Context context, SemanticVersion oldVersion, SemanticVersion newVersion, string unformattedCommitMessage)
     {
         Requires.NotNull(context, nameof(context));
 
@@ -293,17 +294,17 @@ private void UpdateVersion(LibGit2Context context, SemanticVersion oldVersion, S
             // Author a commit only if we effectively changed something.
             if (!context.Repository.Head.Tip.Tree.Equals(context.Repository.Index.WriteToTree()))
             {
-                string commitMessage = this.GetCommitMessage(commitMessagePattern, versionOptions.Version);
+                if (string.IsNullOrEmpty(unformattedCommitMessage))
+                {
+                    unformattedCommitMessage = "Set version to '{0}'";
+                }
+
+                string commitMessage = string.Format(CultureInfo.CurrentCulture, unformattedCommitMessage, versionOptions.Version);
                 context.Repository.Commit(commitMessage, signature, signature, new CommitOptions() { AllowEmptyCommit = false });
             }
         }
     }
 
-    private string GetCommitMessage(string commitMessagePattern, SemanticVersion version)
-    {
-        return commitMessagePattern == "{0}" ? $"Set version to '{version}'" : string.Format(commitMessagePattern, $"'{version}'");
-    }
-
     private Signature GetSignature(Repository repository)
     {
         Signature signature = repository.Config.BuildSignature(DateTimeOffset.Now);

src/nbgv/Program.cs

@@ -70,7 +70,7 @@ private enum ExitCodes
             ShallowClone,
             InternalError,
             InvalidTagNameSetting,
-            InvalidCommitMessagePattern,
+            InvalidunformattedCommitMessage,
         }
 
         private static bool AlwaysUseLibGit2 => string.Equals(Environment.GetEnvironmentVariable("NBGV_GitEngine"), "LibGit2", StringComparison.Ordinal);
@@ -219,7 +219,7 @@ private static Parser BuildCommandLine()
                 var nextVersion = new Option<string>("--nextVersion", "The version to set for the current branch. If omitted, the next version is determined automatically by incrementing the current version.");
                 var versionIncrement = new Option<string>("--versionIncrement", "Overrides the 'versionIncrement' setting set in version.json for determining the next version of the current branch.");
                 var format = new Option<string>(new[] { "--format", "-f" }, $"The format to write information about the release. Allowed values are: {string.Join(", ", SupportedFormats)}. The default is {DefaultOutputFormat}.").FromAmong(SupportedFormats);
-                var commitMessagePattern = new Option<string>("--commit-message-pattern", "Custom pattern to add a prefix or suffix to the default commit message. Must include '{0}' in the pattern to represent the version.");
+                var unformattedCommitMessage = new Option<string>("--commit-message-pattern", "A custom message to use for the commit that changes the version number. May include {0} for the version number. If not specified, the default is \"Set version to '{0}'\".");
                 var tagArgument = new Argument<string>("tag", "The prerelease tag to apply on the release branch (if any). If not specified, any existing prerelease tag will be removed. The preceding hyphen may be omitted.")
                 {
                     Arity = ArgumentArity.ZeroOrOne,
@@ -230,11 +230,11 @@ private static Parser BuildCommandLine()
                     nextVersion,
                     versionIncrement,
                     format,
-                    commitMessagePattern,
+                    unformattedCommitMessage,
                     tagArgument,
                 };
 
-                prepareRelease.SetHandler(OnPrepareReleaseCommand, project, nextVersion, versionIncrement, format, tagArgument, commitMessagePattern);
+                prepareRelease.SetHandler(OnPrepareReleaseCommand, project, nextVersion, versionIncrement, format, tagArgument, unformattedCommitMessage);
             }
 
             var root = new RootCommand($"{ThisAssembly.AssemblyTitle} v{ThisAssembly.AssemblyInformationalVersion}")
@@ -714,7 +714,7 @@ private static Task<int> OnCloudCommand(string project, string[] metadata, strin
             return Task.FromResult((int)ExitCodes.OK);
         }
 
-        private static Task<int> OnPrepareReleaseCommand(string project, string nextVersion, string versionIncrement, string format, string tag, string commitMessagePattern)
+        private static Task<int> OnPrepareReleaseCommand(string project, string nextVersion, string versionIncrement, string format, string tag, string unformattedCommitMessage)
         {
             // validate project path property
             string searchPath = GetSpecifiedOrCurrentDirectoryPath(project);
@@ -767,26 +767,24 @@ private static Task<int> OnPrepareReleaseCommand(string project, string nextVers
                 return Task.FromResult((int)ExitCodes.UnsupportedFormat);
             }
 
-            if (string.IsNullOrEmpty(commitMessagePattern))
+            if (!string.IsNullOrEmpty(unformattedCommitMessage))
             {
-                commitMessagePattern = "{0}";
-            }
-
-            try
-            {
-                string.Format(commitMessagePattern, "FormatValidator");
-            }
-            catch (FormatException ex)
-            {
-                Console.Error.WriteLine($"InvalidCommitMessagePattern: {ex.Message}");
-                return Task.FromResult((int)ExitCodes.InvalidCommitMessagePattern);
+                try
+                {
+                    string.Format(unformattedCommitMessage, "FormatValidator");
+                }
+                catch (FormatException ex)
+                {
+                    Console.Error.WriteLine($"Invalid commit message pattern: {ex.Message}");
+                    return Task.FromResult((int)ExitCodes.InvalidunformattedCommitMessage);
+                }
             }
 
             // run prepare-release
             try
             {
                 var releaseManager = new ReleaseManager(Console.Out, Console.Error);
-                releaseManager.PrepareRelease(searchPath, tag, nextVersionParsed, versionIncrementParsed, outputMode, commitMessagePattern);
+                releaseManager.PrepareRelease(searchPath, tag, nextVersionParsed, versionIncrementParsed, outputMode, unformattedCommitMessage);
                 return Task.FromResult((int)ExitCodes.OK);
             }
             catch (ReleaseManager.ReleasePreparationException ex)

test/Nerdbank.GitVersioning.Tests/ReleaseManagerTests.cs

@@ -639,10 +639,10 @@ public void PrepareRelease_ResetsVersionHeightOffset()
     }
 
     [Theory]
-    [InlineData("1.0-beta", "{0} Custom commit message pattern", "'1.0' Custom commit message pattern")]
-    [InlineData("1.0-beta", "Custom commit message pattern - {0} custom message", "Custom commit message pattern - '1.0' custom message")]
-    [InlineData("1.0-beta", "Custom commit message pattern - {0}", "Custom commit message pattern - '1.0'")]
-    [InlineData("1.0-beta", "{0}", "Set version to '1.0'")]
+    [InlineData("1.0-beta", "{0} Custom commit message pattern", "1.0 Custom commit message pattern")]
+    [InlineData("1.0-beta", "Custom commit message pattern - {0} custom message", "Custom commit message pattern - 1.0 custom message")]
+    [InlineData("1.0-beta", "Custom commit message pattern - {0}", "Custom commit message pattern - 1.0")]
+    [InlineData("1.0-beta", "{0}", "1.0")]
     public void PrepareRelease_WithCustomCommitMessagePattern(string initialVersion, string commitMessagePattern, string expectedCommitMessage)
     {
         // Create and configure the repository
@@ -657,7 +657,7 @@ public void PrepareRelease_WithCustomCommitMessagePattern(string initialVersion,
 
         // Run PrepareRelease with the custom commit message pattern
         var releaseManager = new ReleaseManager();
-        releaseManager.PrepareRelease(this.RepoPath, commitMessagePattern: commitMessagePattern);
+        releaseManager.PrepareRelease(this.RepoPath, unformattedCommitMessage: commitMessagePattern);
 
         // Verify that the commit message on the release branch matches the expected pattern
         string releaseBranchName = "v1.0";