spack uninstall: improve help message (#16886)

fixes #12527

Mention that specs  can be uninstalled by hash also in
the help message. Reference `spack gc` in case people
are looking for ways to clean the store from build time
dependencies.

Use "spec" instead of "package" to avoid ambiguity in
the error message.

lib/spack/spack/cmd/uninstall.py

@@ -26,7 +26,7 @@
 
 error_message = """You can either:
     a) use a more specific spec, or
-    b) specify the package by its hash (e.g. `spack uninstall /hash`), or
+    b) specify the spec by its hash (e.g. `spack uninstall /hash`), or
     c) use `spack uninstall --all` to uninstall ALL matching specs.
 """
 
@@ -40,6 +40,18 @@
 
 
 def setup_parser(subparser):
+    epilog_msg = ("Specs to be uninstalled are specified using the spec syntax"
+                  " (`spack help --spec`) and can be identified by their "
+                  "hashes. To remove packages that are needed only at build "
+                  "time and were not explicitly installed see `spack gc -h`."
+                  "\n\nWhen using the --all option ALL packages matching the "
+                  "supplied specs will be uninstalled. For instance, "
+                  "`spack uninstall --all libelf` uninstalls all the versions "
+                  "of `libelf` currently present in Spack's store. If no spec "
+                  "is supplied, all installed packages will be uninstalled. "
+                  "If used in an environment, all packages in the environment "
+                  "will be uninstalled.")
+    subparser.epilog = epilog_msg
     subparser.add_argument(
         '-f', '--force', action='store_true', dest='force',
         help="remove regardless of whether other packages or environments "
@@ -48,12 +60,8 @@ def setup_parser(subparser):
         subparser, ['recurse_dependents', 'yes_to_all', 'installed_specs'])
     subparser.add_argument(
         '-a', '--all', action='store_true', dest='all',
-        help="USE CAREFULLY. Remove ALL installed packages that match each "
-        "supplied spec. i.e., if you `uninstall --all libelf`,"
-        " ALL versions of `libelf` are uninstalled. If no spec is "
-        "supplied, all installed packages will be uninstalled. "
-        "If used in an environment, all packages in the environment "
-        "will be uninstalled.")
+        help="remove ALL installed packages that match each supplied spec"
+    )
 
 
 def find_matching_specs(env, specs, allow_multiple_matches=False, force=False):