Clarify to localizers git tree SHA vs git commit SHA.

include/vcpkg/base/checks.h

@@ -83,12 +83,12 @@ namespace vcpkg::Checks
 
     [[noreturn]] inline void msg_exit_with_error(const LineInfo& line_info, const LocalizedString& message)
     {
-        msg_exit_with_message(line_info, msg::format(msgErrorMessage).append(message));
+        msg_exit_with_message(line_info, LocalizedString::from_raw(ErrorPrefix).append(message));
     }
     template<VCPKG_DECL_MSG_TEMPLATE>
     [[noreturn]] void msg_exit_with_error(const LineInfo& line_info, VCPKG_DECL_MSG_ARGS)
     {
-        msg_exit_with_message(line_info, msg::format(msgErrorMessage).append(VCPKG_EXPAND_MSG_ARGS));
+        msg_exit_with_message(line_info, LocalizedString::from_raw(ErrorPrefix).append(VCPKG_EXPAND_MSG_ARGS));
     }
 
 }

include/vcpkg/base/message-args.inc.h

@@ -29,6 +29,10 @@ DECLARE_MSG_ARG(exit_code, "127")
 DECLARE_MSG_ARG(expected_version, "1.3.8")
 DECLARE_MSG_ARG(extension, ".exe")
 DECLARE_MSG_ARG(feature, "avisynthplus")
+DECLARE_MSG_ARG(
+    git_tree_sha,
+    "7cfad47ae9f68b183983090afd6337cd60fd4949 (see "
+    "https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish )")
 DECLARE_MSG_ARG(json_field, "identifer")
 DECLARE_MSG_ARG(json_type, "an array of identifiers")
 DECLARE_MSG_ARG(lower, "42")

include/vcpkg/base/message-data.inc.h

@@ -482,7 +482,7 @@ DECLARE_MESSAGE(CISwitchOptSkipFailures,
                 "Skips ports marked `=fail` in ci.baseline.txt")
 DECLARE_MESSAGE(CISwitchOptXUnitAll, (), "", "Reports unchanged ports in the XUnit output")
 DECLARE_MESSAGE(ClearingContents, (msg::path), "", "Clearing contents of {path}")
-DECLARE_MESSAGE(CmakeTargetsExcluded, (msg::count), "", "note: {count} additional targets are not displayed.")
+DECLARE_MESSAGE(CmakeTargetsExcluded, (msg::count), "", "{count} additional targets are not displayed.")
 DECLARE_MESSAGE(CMakeTargetsUsage,
                 (msg::package_name),
                 "'targets' are a CMake and Makefile concept",
@@ -1099,12 +1099,6 @@ DECLARE_MESSAGE(ErrorInvalidManifestModeOption,
                 (msg::option),
                 "",
                 "The option --{option} is not supported in manifest mode.")
-DECLARE_MESSAGE(ErrorMessage, (), "", "error: ")
-DECLARE_MESSAGE(
-    ErrorMessageMustUsePrintError,
-    (msg::value),
-    "{value} is is a localized message name like ErrorMessageMustUsePrintError",
-    "The message named {value} starts with error:, it must be changed to prepend ErrorMessage in code instead.")
 DECLARE_MESSAGE(
     ErrorMissingVcpkgRoot,
     (),
@@ -1360,22 +1354,6 @@ DECLARE_MESSAGE(ForMoreHelp,
                 "For More Help")
 DECLARE_MESSAGE(GeneratedConfiguration, (msg::path), "", "Generated configuration {path}.")
 DECLARE_MESSAGE(GeneratedInstaller, (msg::path), "", "{path} installer generated.")
-DECLARE_MESSAGE(GenerateMsgErrorParsingFormatArgs,
-                (msg::value),
-                "example of {value} 'GenerateMsgNoComment'",
-                "parsing format string for {value}:")
-DECLARE_MESSAGE(GenerateMsgIncorrectComment,
-                (msg::value),
-                "example of {value} is 'GenerateMsgNoComment'",
-                R"(message {value} has an incorrect comment:)")
-DECLARE_MESSAGE(GenerateMsgNoArgumentValue,
-                (msg::value),
-                "example of {value} is 'arch'",
-                R"({{{value}}} was specified in a comment, but was not used in the message.)")
-DECLARE_MESSAGE(GenerateMsgNoCommentValue,
-                (msg::value),
-                "example of {value} is 'arch'",
-                R"({{{value}}} was used in the message, but not commented.)")
 DECLARE_MESSAGE(GeneratingConfiguration, (msg::path), "", "Generating configuration {path}...")
 DECLARE_MESSAGE(GeneratingInstaller, (msg::path), "", "Generating installer {path}...")
 DECLARE_MESSAGE(GeneratingRepo, (msg::path), "", "Generating repository {path}...")
@@ -1812,7 +1790,6 @@ DECLARE_MESSAGE(InternalCICommand,
                 (),
                 "",
                 "vcpkg ci is an internal command which will change incompatibly or be removed at any time.")
-DECLARE_MESSAGE(InternalErrorMessage, (), "", "internal error: ")
 DECLARE_MESSAGE(
     InternalErrorMessageContact,
     (),
@@ -2059,17 +2036,6 @@ DECLARE_MESSAGE(LoadingOverlayTriplet,
                 (msg::path),
                 "'-- [OVERLAY]' at the beginning must be preserved",
                 "-- [OVERLAY] Loading triplet configuration from: {path}")
-DECLARE_MESSAGE(LocalizedMessageMustNotContainIndents,
-                (msg::value),
-                "{value} is is a localized message name like LocalizedMessageMustNotContainIndents. "
-                "The 'LocalizedString::append_indent' part is locale-invariant.",
-                "The message named {value} contains what appears to be indenting which must be "
-                "changed to use LocalizedString::append_indent instead.")
-DECLARE_MESSAGE(LocalizedMessageMustNotEndWithNewline,
-                (msg::value),
-                "{value} is a localized message name like LocalizedMessageMustNotEndWithNewline",
-                "The message named {value} ends with a newline which should be added by formatting "
-                "rather than by localization.")
 DECLARE_MESSAGE(LocalPortfileVersion,
                 (),
                 "",
@@ -2198,7 +2164,6 @@ DECLARE_MESSAGE(NonZeroRemainingArgs,
                 "the command '{command_name}' does not accept any additional arguments")
 DECLARE_MESSAGE(NoOutdatedPackages, (), "", "There are no outdated packages.")
 DECLARE_MESSAGE(NoRegistryForPort, (msg::package_name), "", "no registry configured for port {package_name}")
-DECLARE_MESSAGE(NoteMessage, (), "", "note: ")
 DECLARE_MESSAGE(NoUrlsAndHashSpecified, (msg::sha), "", "No urls specified to download SHA: {sha}")
 DECLARE_MESSAGE(NoUrlsAndNoHashSpecified, (), "", "No urls specified and no hash specified.")
 DECLARE_MESSAGE(NugetOutputNotCapturedBecauseInteractiveSpecified,
@@ -3122,25 +3087,22 @@ DECLARE_MESSAGE(VersionSpecMismatch,
                 "Failed to load port because versions are inconsistent. The file \"{path}\" contains the version "
                 "{actual_version}, but the version database indicates that it should be {expected_version}.")
 DECLARE_MESSAGE(VersionTableHeader, (), "", "Version")
-DECLARE_MESSAGE(VersionVerifiedOK, (msg::version_spec, msg::commit_sha), "", "OK: {version_spec} -> {commit_sha}")
+DECLARE_MESSAGE(VersionVerifiedOK,
+                (msg::version_spec, msg::git_tree_sha),
+                "",
+                "{version_spec} is correctly in the version database ({git_tree_sha})")
 DECLARE_MESSAGE(VSExaminedInstances, (), "", "The following Visual Studio instances were considered:")
 DECLARE_MESSAGE(VSExaminedPaths, (), "", "The following paths were examined for Visual Studio instances:")
 DECLARE_MESSAGE(VSNoInstances, (), "", "Could not locate a complete Visual Studio instance")
 DECLARE_MESSAGE(WaitingForChildrenToExit, (), "", "Waiting for child processes to exit...")
 DECLARE_MESSAGE(WaitingToTakeFilesystemLock, (msg::path), "", "waiting to take filesystem lock on {path}...")
-DECLARE_MESSAGE(WarningMessage, (), "", "warning: ")
-DECLARE_MESSAGE(WarningMessageMustUsePrintWarning,
-                (msg::value),
-                "{value} is is a localized message name like WarningMessageMustUsePrintWarning",
-                "The message named {value} starts with warning:, it must be changed to prepend "
-                "WarningMessage in code instead.")
 DECLARE_MESSAGE(WarningsTreatedAsErrors, (), "", "previous warnings being interpreted as errors")
 DECLARE_MESSAGE(WarnOnParseConfig, (msg::path), "", "Found the following warnings in configuration {path}:")
 DECLARE_MESSAGE(WhileCheckingOutBaseline, (msg::commit_sha), "", "while checking out baseline {commit_sha}")
 DECLARE_MESSAGE(WhileCheckingOutPortTreeIsh,
-                (msg::package_name, msg::commit_sha),
+                (msg::package_name, msg::git_tree_sha),
                 "",
-                "while checking out port {package_name} with git tree {commit_sha}")
+                "while checking out port {package_name} with git tree {git_tree_sha}")
 DECLARE_MESSAGE(WhileGettingLocalTreeIshObjectsForPorts, (), "", "while getting local treeish objects for ports")
 DECLARE_MESSAGE(WhileLoadingLocalPort, (msg::package_name), "", "while attempting to load local port {package_name}")
 DECLARE_MESSAGE(WhileLoadingPortFromGitTree, (msg::commit_sha), "", "while trying to load port from: {commit_sha}")

include/vcpkg/base/messages.h

@@ -72,6 +72,15 @@ namespace vcpkg::msg
 
 namespace vcpkg
 {
+    // constants for the
+    // <file>:line:col: <prefix>: <content>
+    // error message format
+    inline constexpr StringLiteral ErrorPrefix = "error: ";
+    inline constexpr StringLiteral InternalErrorPrefix = "internal error: ";
+    inline constexpr StringLiteral MessagePrefix = "message: ";
+    inline constexpr StringLiteral NotePrefix = "note: ";
+    inline constexpr StringLiteral WarningPrefix = "warning: ";
+
     struct LocalizedString
     {
         LocalizedString() = default;
@@ -187,38 +196,36 @@ namespace vcpkg::msg
         msg::write_unlocalized_text_to_stdout(Color::none, "\n");
     }
 
-    [[nodiscard]] LocalizedString format_error();
     [[nodiscard]] LocalizedString format_error(const LocalizedString& s);
     template<VCPKG_DECL_MSG_TEMPLATE>
     [[nodiscard]] LocalizedString format_error(VCPKG_DECL_MSG_ARGS)
     {
-        auto s = format_error();
+        auto s = LocalizedString::from_raw(ErrorPrefix);
         msg::format_to(s, VCPKG_EXPAND_MSG_ARGS);
         return s;
     }
     void println_error(const LocalizedString& s);
     template<VCPKG_DECL_MSG_TEMPLATE>
     void println_error(VCPKG_DECL_MSG_ARGS)
     {
-        auto s = format_error();
+        auto s = LocalizedString::from_raw(ErrorPrefix);
         msg::format_to(s, VCPKG_EXPAND_MSG_ARGS);
         println(Color::error, s);
     }
 
-    [[nodiscard]] LocalizedString format_warning();
     [[nodiscard]] LocalizedString format_warning(const LocalizedString& s);
     template<VCPKG_DECL_MSG_TEMPLATE>
     [[nodiscard]] LocalizedString format_warning(VCPKG_DECL_MSG_ARGS)
     {
-        auto s = format_warning();
+        auto s = LocalizedString::from_raw(WarningPrefix);
         msg::format_to(s, VCPKG_EXPAND_MSG_ARGS);
         return s;
     }
     void println_warning(const LocalizedString& s);
     template<VCPKG_DECL_MSG_TEMPLATE>
     void println_warning(VCPKG_DECL_MSG_ARGS)
     {
-        auto s = format_warning();
+        auto s = LocalizedString::from_raw(WarningPrefix);
         msg::format_to(s, VCPKG_EXPAND_MSG_ARGS);
         println(Color::warning, s);
     }

locales/messages.json

@@ -296,7 +296,7 @@
   "_CiBaselineUnexpectedPass.comment": "An example of {spec} is zlib:x64-windows. An example of {path} is /foo/bar.",
   "ClearingContents": "Clearing contents of {path}",
   "_ClearingContents.comment": "An example of {path} is /foo/bar.",
-  "CmakeTargetsExcluded": "note: {count} additional targets are not displayed.",
+  "CmakeTargetsExcluded": "{count} additional targets are not displayed.",
   "_CmakeTargetsExcluded.comment": "An example of {count} is 42.",
   "CmdAcquireExample1": "vcpkg acquire <artifact>",
   "_CmdAcquireExample1.comment": "This is a command line, only the <>s part should be localized",
@@ -655,9 +655,6 @@
   "_ErrorInvalidExtractOption.comment": "The keyword 'AUTO' should not be localized An example of {option} is editable.",
   "ErrorInvalidManifestModeOption": "The option --{option} is not supported in manifest mode.",
   "_ErrorInvalidManifestModeOption.comment": "An example of {option} is editable.",
-  "ErrorMessage": "error: ",
-  "ErrorMessageMustUsePrintError": "The message named {value} starts with error:, it must be changed to prepend ErrorMessage in code instead.",
-  "_ErrorMessageMustUsePrintError.comment": "{value} is is a localized message name like ErrorMessageMustUsePrintError",
   "ErrorMissingVcpkgRoot": "Could not detect vcpkg-root. If you are trying to use a copy of vcpkg that you've built, you must define the VCPKG_ROOT environment variable to point to a cloned copy of https://github.com/Microsoft/vcpkg.",
   "ErrorNoVSInstance": "in triplet {triplet}: Unable to find a valid Visual Studio instance",
   "_ErrorNoVSInstance.comment": "An example of {triplet} is x64-windows.",
@@ -839,14 +836,6 @@
   "_FormattedParseMessageExpression.comment": "Example of {value} is 'x64 & windows'",
   "GHAParametersMissing": "The GHA binary source requires the ACTIONS_RUNTIME_TOKEN and ACTIONS_CACHE_URL environment variables to be set. See {url} for details.",
   "_GHAParametersMissing.comment": "An example of {url} is https://github.com/microsoft/vcpkg.",
-  "GenerateMsgErrorParsingFormatArgs": "parsing format string for {value}:",
-  "_GenerateMsgErrorParsingFormatArgs.comment": "example of {value} 'GenerateMsgNoComment'",
-  "GenerateMsgIncorrectComment": "message {value} has an incorrect comment:",
-  "_GenerateMsgIncorrectComment.comment": "example of {value} is 'GenerateMsgNoComment'",
-  "GenerateMsgNoArgumentValue": "{{{value}}} was specified in a comment, but was not used in the message.",
-  "_GenerateMsgNoArgumentValue.comment": "example of {value} is 'arch'",
-  "GenerateMsgNoCommentValue": "{{{value}}} was used in the message, but not commented.",
-  "_GenerateMsgNoCommentValue.comment": "example of {value} is 'arch'",
   "GeneratedConfiguration": "Generated configuration {path}.",
   "_GeneratedConfiguration.comment": "An example of {path} is /foo/bar.",
   "GeneratedInstaller": "{path} installer generated.",
@@ -1033,7 +1022,6 @@
   "_IntegrateZshHelp.comment": "'zsh' is a terminal program which should be unlocalized.",
   "IntegrationFailedVS2015": "Integration was not applied for Visual Studio 2015.",
   "InternalCICommand": "vcpkg ci is an internal command which will change incompatibly or be removed at any time.",
-  "InternalErrorMessage": "internal error: ",
   "InternalErrorMessageContact": "Please open an issue at https://github.com/microsoft/vcpkg/issues/new?template=other-type-of-bug-report.md&labels=category:vcpkg-bug with detailed steps to reproduce the problem.",
   "InvalidArchitecture": "invalid architecture: {value}",
   "_InvalidArchitecture.comment": "{value} is what the user entered that we did not understand",
@@ -1169,10 +1157,6 @@
   "LoadingOverlayTriplet": "-- [OVERLAY] Loading triplet configuration from: {path}",
   "_LoadingOverlayTriplet.comment": "'-- [OVERLAY]' at the beginning must be preserved An example of {path} is /foo/bar.",
   "LocalPortfileVersion": "Using local portfile versions. To update the local portfiles, use `git pull`.",
-  "LocalizedMessageMustNotContainIndents": "The message named {value} contains what appears to be indenting which must be changed to use LocalizedString::append_indent instead.",
-  "_LocalizedMessageMustNotContainIndents.comment": "{value} is is a localized message name like LocalizedMessageMustNotContainIndents. The 'LocalizedString::append_indent' part is locale-invariant.",
-  "LocalizedMessageMustNotEndWithNewline": "The message named {value} ends with a newline which should be added by formatting rather than by localization.",
-  "_LocalizedMessageMustNotEndWithNewline.comment": "{value} is a localized message name like LocalizedMessageMustNotEndWithNewline",
   "ManifestConflict": "Found both a manifest and CONTROL files in port \"{path}\"; please rename one or the other",
   "_ManifestConflict.comment": "An example of {path} is /foo/bar.",
   "ManifestFormatCompleted": "Succeeded in formatting the manifest files.",
@@ -1242,7 +1226,6 @@
   "_NonZeroOrOneRemainingArgs.comment": "An example of {command_name} is install.",
   "NonZeroRemainingArgs": "the command '{command_name}' does not accept any additional arguments",
   "_NonZeroRemainingArgs.comment": "An example of {command_name} is install.",
-  "NoteMessage": "note: ",
   "NugetOutputNotCapturedBecauseInteractiveSpecified": "NuGet command failed and output was not captured because --interactive was specified",
   "NugetPackageFileSucceededButCreationFailed": "NuGet package creation succeeded, but no .nupkg was produced. Expected: \"{path}\"",
   "_NugetPackageFileSucceededButCreationFailed.comment": "An example of {path} is /foo/bar.",
@@ -1716,21 +1699,18 @@
   "VersionSpecMismatch": "Failed to load port because versions are inconsistent. The file \"{path}\" contains the version {actual_version}, but the version database indicates that it should be {expected_version}.",
   "_VersionSpecMismatch.comment": "An example of {path} is /foo/bar. An example of {expected_version} is 1.3.8. An example of {actual_version} is 1.3.8.",
   "VersionTableHeader": "Version",
-  "VersionVerifiedOK": "OK: {version_spec} -> {commit_sha}",
-  "_VersionVerifiedOK.comment": "An example of {version_spec} is zlib:x64-windows@1.0.0. An example of {commit_sha} is 7cfad47ae9f68b183983090afd6337cd60fd4949.",
+  "VersionVerifiedOK": "{version_spec} is correctly in the version database ({git_tree_sha})",
+  "_VersionVerifiedOK.comment": "An example of {version_spec} is zlib:x64-windows@1.0.0. An example of {git_tree_sha} is 7cfad47ae9f68b183983090afd6337cd60fd4949 (see https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish ).",
   "WaitingForChildrenToExit": "Waiting for child processes to exit...",
   "WaitingToTakeFilesystemLock": "waiting to take filesystem lock on {path}...",
   "_WaitingToTakeFilesystemLock.comment": "An example of {path} is /foo/bar.",
   "WarnOnParseConfig": "Found the following warnings in configuration {path}:",
   "_WarnOnParseConfig.comment": "An example of {path} is /foo/bar.",
-  "WarningMessage": "warning: ",
-  "WarningMessageMustUsePrintWarning": "The message named {value} starts with warning:, it must be changed to prepend WarningMessage in code instead.",
-  "_WarningMessageMustUsePrintWarning.comment": "{value} is is a localized message name like WarningMessageMustUsePrintWarning",
   "WarningsTreatedAsErrors": "previous warnings being interpreted as errors",
   "WhileCheckingOutBaseline": "while checking out baseline {commit_sha}",
   "_WhileCheckingOutBaseline.comment": "An example of {commit_sha} is 7cfad47ae9f68b183983090afd6337cd60fd4949.",
-  "WhileCheckingOutPortTreeIsh": "while checking out port {package_name} with git tree {commit_sha}",
-  "_WhileCheckingOutPortTreeIsh.comment": "An example of {package_name} is zlib. An example of {commit_sha} is 7cfad47ae9f68b183983090afd6337cd60fd4949.",
+  "WhileCheckingOutPortTreeIsh": "while checking out port {package_name} with git tree {git_tree_sha}",
+  "_WhileCheckingOutPortTreeIsh.comment": "An example of {package_name} is zlib. An example of {git_tree_sha} is 7cfad47ae9f68b183983090afd6337cd60fd4949 (see https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish ).",
   "WhileGettingLocalTreeIshObjectsForPorts": "while getting local treeish objects for ports",
   "WhileLoadingLocalPort": "while attempting to load local port {package_name}",
   "_WhileLoadingLocalPort.comment": "An example of {package_name} is zlib.",

src/vcpkg/base/checks.cpp

@@ -89,7 +89,7 @@ namespace vcpkg
         if (!expression)
         {
             msg::println(Color::error,
-                         msg::format(msgInternalErrorMessage)
+                         LocalizedString::from_raw(InternalErrorPrefix)
                              .append(locale_invariant_lineinfo(line_info))
                              .append(msgChecksFailedCheck)
                              .append_raw('\n')
@@ -103,7 +103,7 @@ namespace vcpkg
         if (!expression)
         {
             msg::println(Color::error,
-                         msg::format(msgInternalErrorMessage)
+                         LocalizedString::from_raw(InternalErrorPrefix)
                              .append(locale_invariant_lineinfo(line_info))
                              .append_raw(error_message)
                              .append_raw('\n')
@@ -122,7 +122,7 @@ namespace vcpkg
 
     static void display_upgrade_message()
     {
-        msg::println(Color::error, msg::format(msgNoteMessage).append(msgChecksUpdateVcpkg));
+        msg::println(Color::error, LocalizedString::from_raw(NotePrefix).append(msgChecksUpdateVcpkg));
     }
 
     [[noreturn]] void Checks::exit_maybe_upgrade(const LineInfo& line_info)