Error message for git acquisition

docs/err/git-url-ref-mutual-req.rst

@@ -0,0 +1,15 @@
+Error: Git requires both a URL and a ref to clone
+#################################################
+
+This error occurs when attempting to add an entry to the package catalog that
+uses the ``Git`` acquisition method.
+
+When ``dds`` obtains a package from the catalog using the ``Git`` method, it
+needs a URL to clone from, and a Git ref to clone. ``dds`` uses a technique
+known as "shallow cloning," which requires a known Git reference to clone from
+the reference may be a tag, branch, or an individual commit (Using a Git commit
+as the ``ref`` requires support from the remote Git server, and it is often
+unavailable in most setups). Using a Git tag is strongly recommended.
+
+.. seealso::
+    Refer to the documentation on :doc:`/guide/catalog`.

src/dds.main.cpp

@@ -248,14 +248,15 @@ struct cli_catalog {
 
             if (git_url) {
                 if (!git_ref) {
-                    throw std::runtime_error(
-                        "`--git-ref` must be specified when using `--git-url`");
+                    dds::throw_user_error<dds::errc::git_url_ref_mutual_req>();
                 }
                 auto git = dds::git_remote_listing{git_url.Get(), git_ref.Get(), std::nullopt};
                 if (auto_lib) {
                     git.auto_lib = lm::split_usage_string(auto_lib.Get());
                 }
                 info.remote = std::move(git);
+            } else if (git_ref) {
+                dds::throw_user_error<dds::errc::git_url_ref_mutual_req>();
             }
 
             cat_path.open().store(info);

src/dds/error/errors.cpp

@@ -15,6 +15,8 @@ std::string error_url_suffix(dds::errc ec) noexcept {
         return "invalid-builtin-toolchain.html";
     case errc::no_such_catalog_package:
         return "no-such-catalog-package.html";
+    case errc::git_url_ref_mutual_req:
+        return "git-url-ref-mutual-req.html";
     case errc::none:
         break;
     }
@@ -43,6 +45,11 @@ modified.
         return R"(
 The installation of a package was requested, but the given package ID was not
 able to be found in the package catalog. Check the spelling and version number.
+)";
+    case errc::git_url_ref_mutual_req:
+        return R"(
+Creating a Git-based catalog entry requires both a URL to clone from and a Git
+reference (tag, branch, commit) to clone.
 )";
     case errc::none:
         break;
@@ -50,3 +57,18 @@ able to be found in the package catalog. Check the spelling and version number.
     assert(false && "Unexpected execution path during error explanation. This is a DDS bug");
     std::terminate();
 }
+
+std::string_view dds::default_error_string(dds::errc ec) noexcept {
+    switch (ec) {
+    case errc::invalid_builtin_toolchain:
+        return "The built-in toolchain name is invalid";
+    case errc::no_such_catalog_package:
+        return "The catalog has no entry for the given package ID";
+    case errc::git_url_ref_mutual_req:
+        return "Git requires both a URL and a ref to clone";
+    case errc::none:
+        break;
+    }
+    assert(false && "Unexpected execution path during error message creation. This is a DDS bug");
+    std::terminate();
+}

src/dds/error/errors.hpp

@@ -22,10 +22,12 @@ enum class errc {
     none = 0,
     invalid_builtin_toolchain,
     no_such_catalog_package,
+    git_url_ref_mutual_req,
 };
 
 std::string      error_reference_of(errc) noexcept;
 std::string_view explanation_of(errc) noexcept;
+std::string_view default_error_string(errc) noexcept;
 
 template <errc ErrorCode>
 struct user_error : user_error_base {
@@ -42,4 +44,9 @@ template <errc ErrorCode, typename... Args>
     throw user_error<ErrorCode>(fmt::format(fmt_str, std::forward<Args>(args)...));
 }
 
+template <errc ErrorCode>
+[[noreturn]] void throw_user_error() {
+    throw user_error<ErrorCode>(std::string(default_error_string(ErrorCode)));
+}
+
 }  // namespace dds