Env help: expand and refine subcommand help and descriptions (#47089)

This PR is in response to a question in the `environments` slack channel (https://spackpm.slack.com/archives/CMHK7MF51/p1729200068557219) about inadequate CLI help/documentation for one specific subcommand.

This PR uses the approach I took for the descriptions and help for `spack test` subcommands.  Namely, I use the first line of the relevant docstring as the description, which is shown per subcommand in `spack env -h`, and the entire docstring as the help.  I then added, where it seemed appropriate, help.  I also tweaked argument docstrings to tighten them up, make consistent with similar arguments elsewhere in the command, and elaborate when it seemed important.  (The only subcommand I didn't touch is `loads`.)

For example, before:
```
$ spack env update -h
usage: spack env update [-hy] env

positional arguments:
  env               name or directory of the environment to activate

optional arguments:
  -h, --help        show this help message and exit
  -y, --yes-to-all  assume "yes" is the answer to every confirmation request
```

After the changes in this PR:
```
$ spack env update -h
usage: spack env update [-hy] env

update the environment manifest to the latest schema format

    update the environment to the latest schema format, which may not be
    readable by older versions of spack

    a backup copy of the manifest is retained in case there is a need to revert
    this operation
    

positional arguments:
  env               name or directory of the environment

optional arguments:
  -h, --help        show this help message and exit
  -y, --yes-to-all  assume "yes" is the answer to every confirmation request
```

---------

Co-authored-by: Todd Gamblin <tgamblin@llnl.gov>

3 files changed, 130 insertions, 95 deletions

diff --git a/lib/spack/spack/cmd/env.py b/lib/spack/spack/cmd/env.py
index c4596af469..2136bb1305 100644
--- a/lib/spack/spack/cmd/env.py
+++ b/lib/spack/spack/cmd/env.py
@@ -57,35 +57,41 @@ subcommands = [
 # env create
 #
 def env_create_setup_parser(subparser):
-    """create a new environment"""
-    subparser.add_argument("env_name", metavar="env", help="name or directory of environment")
+    """create a new environment
+
+    create a new environment or, optionally, copy an existing environment
+
+    a manifest file results in a new abstract environment while a lock file
+    creates a new concrete environment
+    """
+    subparser.add_argument(
+        "env_name", metavar="env", help="name or directory of the new environment"
+    )
     subparser.add_argument(
         "-d", "--dir", action="store_true", help="create an environment in a specific directory"
     )
     subparser.add_argument(
         "--keep-relative",
         action="store_true",
-        help="copy relative develop paths verbatim into the new environment"
-        " when initializing from envfile",
+        help="copy envfile's relative develop paths verbatim",
     )
     view_opts = subparser.add_mutually_exclusive_group()
     view_opts.add_argument(
         "--without-view", action="store_true", help="do not maintain a view for this environment"
     )
     view_opts.add_argument(
-        "--with-view",
-        help="specify that this environment should maintain a view at the"
-        " specified path (by default the view is maintained in the"
-        " environment directory)",
+        "--with-view", help="maintain view at WITH_VIEW (vs. environment's directory)"
     )
     subparser.add_argument(
         "envfile",
         nargs="?",
         default=None,
-        help="either a lockfile (must end with '.json' or '.lock') or a manifest file",
+        help="manifest or lock file (ends with '.json' or '.lock')",
     )
     subparser.add_argument(
-        "--include-concrete", action="append", help="name of old environment to copy specs from"
+        "--include-concrete",
+        action="append",
+        help="copy concrete specs from INCLUDE_CONCRETE's environment",
     )
 
 
@@ -173,7 +179,7 @@ def _env_create(
 # env activate
 #
 def env_activate_setup_parser(subparser):
-    """set the current environment"""
+    """set the active environment"""
     shells = subparser.add_mutually_exclusive_group()
     shells.add_argument(
         "--sh",
@@ -213,14 +219,14 @@ def env_activate_setup_parser(subparser):
 
     view_options = subparser.add_mutually_exclusive_group()
     view_options.add_argument(
-        "--with-view",
         "-v",
+        "--with-view",
         metavar="name",
-        help="set runtime environment variables for specific view",
+        help="set runtime environment variables for the named view",
     )
     view_options.add_argument(
-        "--without-view",
         "-V",
+        "--without-view",
         action="store_true",
         help="do not set runtime environment variables for any view",
     )
@@ -230,14 +236,14 @@ def env_activate_setup_parser(subparser):
         "--prompt",
         action="store_true",
         default=False,
-        help="decorate the command line prompt when activating",
+        help="add the active environment to the command line prompt",
     )
 
     subparser.add_argument(
         "--temp",
         action="store_true",
         default=False,
-        help="create and activate an environment in a temporary directory",
+        help="create and activate in a temporary directory",
     )
     subparser.add_argument(
         "--create",
@@ -249,13 +255,12 @@ def env_activate_setup_parser(subparser):
         "--envfile",
         nargs="?",
         default=None,
-        help="either a lockfile (must end with '.json' or '.lock') or a manifest file",
+        help="manifest or lock file (ends with '.json' or '.lock')",
     )
     subparser.add_argument(
         "--keep-relative",
         action="store_true",
-        help="copy relative develop paths verbatim into the new environment"
-        " when initializing from envfile",
+        help="copy envfile's relative develop paths verbatim when create",
     )
     subparser.add_argument(
         "-d",
@@ -269,10 +274,7 @@ def env_activate_setup_parser(subparser):
         dest="env_name",
         nargs="?",
         default=None,
-        help=(
-            "name of managed environment or directory of the independent env"
-            " (when using --dir/-d) to activate"
-        ),
+        help=("name or directory of the environment being activated"),
     )
 
 
@@ -385,7 +387,7 @@ def env_activate(args):
 # env deactivate
 #
 def env_deactivate_setup_parser(subparser):
-    """deactivate any active environment in the shell"""
+    """deactivate the active environment"""
     shells = subparser.add_mutually_exclusive_group()
     shells.add_argument(
         "--sh",
@@ -448,23 +450,27 @@ def env_deactivate(args):
 # env remove
 #
 def env_remove_setup_parser(subparser):
-    """remove an existing environment"""
-    subparser.add_argument("rm_env", metavar="env", nargs="+", help="environment(s) to remove")
+    """remove managed environment(s)
+
+    remove existing environment(s) managed by Spack
+
+    directory environments and manifests embedded in repositories must be
+    removed manually
+    """
+    subparser.add_argument(
+        "rm_env", metavar="env", nargs="+", help="name(s) of the environment(s) being removed"
+    )
     arguments.add_common_arguments(subparser, ["yes_to_all"])
     subparser.add_argument(
         "-f",
         "--force",
         action="store_true",
-        help="remove the environment even if it is included in another environment",
+        help="force removal even when included in other environment(s)",
     )
 
 
 def env_remove(args):
-    """Remove a *named* environment.
-
-    This removes an environment managed by Spack. Directory environments
-    and manifests embedded in repositories should be removed manually.
-    """
+    """remove existing environment(s)"""
     remove_envs = []
     valid_envs = []
     bad_envs = []
@@ -519,29 +525,32 @@ def env_remove(args):
 # env rename
 #
 def env_rename_setup_parser(subparser):
-    """rename an existing environment"""
-    subparser.add_argument(
-        "mv_from", metavar="from", help="name (or path) of existing environment"
-    )
+    """rename an existing environment
+
+    rename a managed environment or move an independent/directory environment
+
+    operation cannot be performed to or from an active environment
+    """
     subparser.add_argument(
-        "mv_to", metavar="to", help="new name (or path) for existing environment"
+        "mv_from", metavar="from", help="current name or directory of the environment"
     )
+    subparser.add_argument("mv_to", metavar="to", help="new name or directory for the environment")
     subparser.add_argument(
         "-d",
         "--dir",
         action="store_true",
-        help="the specified arguments correspond to directory paths",
+        help="positional arguments are environment directory paths",
     )
     subparser.add_argument(
-        "-f", "--force", action="store_true", help="allow overwriting of an existing environment"
+        "-f",
+        "--force",
+        action="store_true",
+        help="force renaming even if overwriting an existing environment",
     )
 
 
 def env_rename(args):
-    """Rename an environment.
-
-    This renames a managed environment or moves an independent environment.
-    """
+    """rename or move an existing environment"""
 
     # Directory option has been specified
     if args.dir:
@@ -590,7 +599,7 @@ def env_rename(args):
 # env list
 #
 def env_list_setup_parser(subparser):
-    """list managed environments"""
+    """list all managed environments"""
 
 
 def env_list(args):
@@ -626,13 +635,14 @@ class ViewAction:
 # env view
 #
 def env_view_setup_parser(subparser):
-    """manage a view associated with the environment"""
+    """manage the environment's view
+
+    provide the path when enabling a view with a non-default path
+    """
     subparser.add_argument(
         "action", choices=ViewAction.actions(), help="action to take for the environment's view"
     )
-    subparser.add_argument(
-        "view_path", nargs="?", help="when enabling a view, optionally set the path manually"
-    )
+    subparser.add_argument("view_path", nargs="?", help="view's non-default path when enabling it")
 
 
 def env_view(args):
@@ -660,7 +670,7 @@ def env_view(args):
 # env status
 #
 def env_status_setup_parser(subparser):
-    """print whether there is an active environment"""
+    """print active environment status"""
 
 
 def env_status(args):
@@ -720,14 +730,22 @@ def env_loads(args):
 
 
 def env_update_setup_parser(subparser):
-    """update environments to the latest format"""
+    """update the environment manifest to the latest schema format
+
+    update the environment to the latest schema format, which may not be
+    readable by older versions of spack
+
+    a backup copy of the manifest is retained in case there is a need to revert
+    this operation
+    """
     subparser.add_argument(
-        metavar="env", dest="update_env", help="name or directory of the environment to activate"
+        metavar="env", dest="update_env", help="name or directory of the environment"
     )
     spack.cmd.common.arguments.add_common_arguments(subparser, ["yes_to_all"])
 
 
 def env_update(args):
+    """update the manifest to the latest format"""
     manifest_file = ev.manifest_file(args.update_env)
     backup_file = manifest_file + ".bkp"
 
@@ -757,14 +775,22 @@ def env_update(args):
 
 
 def env_revert_setup_parser(subparser):
-    """restore environments to their state before update"""
+    """restore the environment manifest to its previous format
+
+    revert the environment's manifest to the schema format from its last
+    'spack env update'
+
+    the current manifest will be overwritten by the backup copy and the backup
+    copy will be removed
+    """
     subparser.add_argument(
-        metavar="env", dest="revert_env", help="name or directory of the environment to activate"
+        metavar="env", dest="revert_env", help="name or directory of the environment"
     )
     spack.cmd.common.arguments.add_common_arguments(subparser, ["yes_to_all"])
 
 
 def env_revert(args):
+    """restore the environment manifest to its previous format"""
     manifest_file = ev.manifest_file(args.revert_env)
     backup_file = manifest_file + ".bkp"
 
@@ -796,15 +822,19 @@ def env_revert(args):
 
 
 def env_depfile_setup_parser(subparser):
-    """generate a depfile from the concrete environment specs"""
+    """generate a depfile to exploit parallel builds across specs
+
+    requires the active environment to be concrete
+    """
     subparser.add_argument(
         "--make-prefix",
         "--make-target-prefix",
         default=None,
         metavar="TARGET",
-        help="prefix Makefile targets (and variables) with <TARGET>/<name>\n\nby default "
-        "the absolute path to the directory makedeps under the environment metadata dir is "
-        "used. can be set to an empty string --make-prefix ''",
+        help="prefix Makefile targets/variables with <TARGET>/<name>,\n"
+        "which can be an empty string (--make-prefix '')\n"
+        "defaults to the absolute path of the environment's makedeps\n"
+        "environment metadata dir\n",
     )
     subparser.add_argument(
         "--make-disable-jobserver",
@@ -819,8 +849,8 @@ def env_depfile_setup_parser(subparser):
         type=arguments.use_buildcache,
         default="package:auto,dependencies:auto",
         metavar="[{auto,only,never},][package:{auto,only,never},][dependencies:{auto,only,never}]",
-        help="when using `only`, redundant build dependencies are pruned from the DAG\n\n"
-        "this flag is passed on to the generated spack install commands",
+        help="use `only` to prune redundant build dependencies\n"
+        "option is also passed to generated spack install commands",
     )
     subparser.add_argument(
         "-o",
@@ -834,14 +864,14 @@ def env_depfile_setup_parser(subparser):
         "--generator",
         default="make",
         choices=("make",),
-        help="specify the depfile type\n\ncurrently only make is supported",
+        help="specify the depfile type (only supports `make`)",
     )
     subparser.add_argument(
         metavar="specs",
         dest="specs",
         nargs=argparse.REMAINDER,
         default=None,
-        help="generate a depfile only for matching specs in the environment",
+        help="limit the generated file to matching specs",
     )
 
 
@@ -910,7 +940,12 @@ def setup_parser(subparser):
         setup_parser_cmd_name = "env_%s_setup_parser" % name
         setup_parser_cmd = globals()[setup_parser_cmd_name]
 
-        subsubparser = sp.add_parser(name, aliases=aliases, help=setup_parser_cmd.__doc__)
+        subsubparser = sp.add_parser(
+            name,
+            aliases=aliases,
+            description=setup_parser_cmd.__doc__,
+            help=spack.cmd.first_line(setup_parser_cmd.__doc__),
+        )
         setup_parser_cmd(subsubparser)
 
 
diff --git a/share/spack/spack-completion.bash b/share/spack/spack-completion.bash
index 2994de4b27..10011a10b3 100644
--- a/share/spack/spack-completion.bash
+++ b/share/spack/spack-completion.bash
@@ -1030,7 +1030,7 @@ _spack_env() {
 _spack_env_activate() {
     if $list_options
     then
-        SPACK_COMPREPLY="-h --help --sh --csh --fish --bat --pwsh --with-view -v --without-view -V -p --prompt --temp --create --envfile --keep-relative -d --dir"
+        SPACK_COMPREPLY="-h --help --sh --csh --fish --bat --pwsh -v --with-view -V --without-view -p --prompt --temp --create --envfile --keep-relative -d --dir"
     else
         _environments
     fi
diff --git a/share/spack/spack-completion.fish b/share/spack/spack-completion.fish
index 57533497b9..8ef18c63bd 100644
--- a/share/spack/spack-completion.fish
+++ b/share/spack/spack-completion.fish
@@ -1472,22 +1472,22 @@ complete -c spack -n '__fish_spack_using_command edit' -s N -l namespace -r -d '
 
 # spack env
 set -g __fish_spack_optspecs_spack_env h/help
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a activate -d 'set the current environment'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a deactivate -d 'deactivate any active environment in the shell'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a activate -d 'set the active environment'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a deactivate -d 'deactivate the active environment'
 complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a create -d 'create a new environment'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a remove -d 'remove an existing environment'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a rm -d 'remove an existing environment'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a remove -d 'remove managed environment(s)'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a rm -d 'remove managed environment(s)'
 complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a rename -d 'rename an existing environment'
 complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a mv -d 'rename an existing environment'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a list -d 'list managed environments'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a ls -d 'list managed environments'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a status -d 'print whether there is an active environment'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a st -d 'print whether there is an active environment'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a list -d 'list all managed environments'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a ls -d 'list all managed environments'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a status -d 'print active environment status'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a st -d 'print active environment status'
 complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a loads -d 'list modules for an installed environment '"'"'(see spack module loads)'"'"''
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a view -d 'manage a view associated with the environment'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a update -d 'update environments to the latest format'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a revert -d 'restore environments to their state before update'
-complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a depfile -d 'generate a depfile from the concrete environment specs'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a view -d 'manage the environment'"'"'s view'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a update -d 'update the environment manifest to the latest schema format'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a revert -d 'restore the environment manifest to its previous format'
+complete -c spack -n '__fish_spack_using_command_pos 0 env' -f -a depfile -d 'generate a depfile to exploit parallel builds across specs'
 complete -c spack -n '__fish_spack_using_command env' -s h -l help -f -a help
 complete -c spack -n '__fish_spack_using_command env' -s h -l help -d 'show this help message and exit'
 
@@ -1506,20 +1506,20 @@ complete -c spack -n '__fish_spack_using_command env activate' -l bat -f -a shel
 complete -c spack -n '__fish_spack_using_command env activate' -l bat -d 'print bat commands to activate the environment'
 complete -c spack -n '__fish_spack_using_command env activate' -l pwsh -f -a shell
 complete -c spack -n '__fish_spack_using_command env activate' -l pwsh -d 'print powershell commands to activate environment'
-complete -c spack -n '__fish_spack_using_command env activate' -l with-view -s v -r -f -a with_view
-complete -c spack -n '__fish_spack_using_command env activate' -l with-view -s v -r -d 'set runtime environment variables for specific view'
-complete -c spack -n '__fish_spack_using_command env activate' -l without-view -s V -f -a without_view
-complete -c spack -n '__fish_spack_using_command env activate' -l without-view -s V -d 'do not set runtime environment variables for any view'
+complete -c spack -n '__fish_spack_using_command env activate' -s v -l with-view -r -f -a with_view
+complete -c spack -n '__fish_spack_using_command env activate' -s v -l with-view -r -d 'set runtime environment variables for the named view'
+complete -c spack -n '__fish_spack_using_command env activate' -s V -l without-view -f -a without_view
+complete -c spack -n '__fish_spack_using_command env activate' -s V -l without-view -d 'do not set runtime environment variables for any view'
 complete -c spack -n '__fish_spack_using_command env activate' -s p -l prompt -f -a prompt
-complete -c spack -n '__fish_spack_using_command env activate' -s p -l prompt -d 'decorate the command line prompt when activating'
+complete -c spack -n '__fish_spack_using_command env activate' -s p -l prompt -d 'add the active environment to the command line prompt'
 complete -c spack -n '__fish_spack_using_command env activate' -l temp -f -a temp
-complete -c spack -n '__fish_spack_using_command env activate' -l temp -d 'create and activate an environment in a temporary directory'
+complete -c spack -n '__fish_spack_using_command env activate' -l temp -d 'create and activate in a temporary directory'
 complete -c spack -n '__fish_spack_using_command env activate' -l create -f -a create
 complete -c spack -n '__fish_spack_using_command env activate' -l create -d 'create and activate the environment if it doesn'"'"'t exist'
 complete -c spack -n '__fish_spack_using_command env activate' -l envfile -r -f -a envfile
-complete -c spack -n '__fish_spack_using_command env activate' -l envfile -r -d 'either a lockfile (must end with '"'"'.json'"'"' or '"'"'.lock'"'"') or a manifest file'
+complete -c spack -n '__fish_spack_using_command env activate' -l envfile -r -d 'manifest or lock file (ends with '"'"'.json'"'"' or '"'"'.lock'"'"')'
 complete -c spack -n '__fish_spack_using_command env activate' -l keep-relative -f -a keep_relative
-complete -c spack -n '__fish_spack_using_command env activate' -l keep-relative -d 'copy relative develop paths verbatim into the new environment when initializing from envfile'
+complete -c spack -n '__fish_spack_using_command env activate' -l keep-relative -d 'copy envfile'"'"'s relative develop paths verbatim when create'
 complete -c spack -n '__fish_spack_using_command env activate' -s d -l dir -f -a dir
 complete -c spack -n '__fish_spack_using_command env activate' -s d -l dir -d 'activate environment based on the directory supplied'
 
@@ -1546,13 +1546,13 @@ complete -c spack -n '__fish_spack_using_command env create' -s h -l help -d 'sh
 complete -c spack -n '__fish_spack_using_command env create' -s d -l dir -f -a dir
 complete -c spack -n '__fish_spack_using_command env create' -s d -l dir -d 'create an environment in a specific directory'
 complete -c spack -n '__fish_spack_using_command env create' -l keep-relative -f -a keep_relative
-complete -c spack -n '__fish_spack_using_command env create' -l keep-relative -d 'copy relative develop paths verbatim into the new environment when initializing from envfile'
+complete -c spack -n '__fish_spack_using_command env create' -l keep-relative -d 'copy envfile'"'"'s relative develop paths verbatim'
 complete -c spack -n '__fish_spack_using_command env create' -l without-view -f -a without_view
 complete -c spack -n '__fish_spack_using_command env create' -l without-view -d 'do not maintain a view for this environment'
 complete -c spack -n '__fish_spack_using_command env create' -l with-view -r -f -a with_view
-complete -c spack -n '__fish_spack_using_command env create' -l with-view -r -d 'specify that this environment should maintain a view at the specified path (by default the view is maintained in the environment directory)'
+complete -c spack -n '__fish_spack_using_command env create' -l with-view -r -d 'maintain view at WITH_VIEW (vs. environment'"'"'s directory)'
 complete -c spack -n '__fish_spack_using_command env create' -l include-concrete -r -f -a include_concrete
-complete -c spack -n '__fish_spack_using_command env create' -l include-concrete -r -d 'name of old environment to copy specs from'
+complete -c spack -n '__fish_spack_using_command env create' -l include-concrete -r -d 'copy concrete specs from INCLUDE_CONCRETE'"'"'s environment'
 
 # spack env remove
 set -g __fish_spack_optspecs_spack_env_remove h/help y/yes-to-all f/force
@@ -1562,7 +1562,7 @@ complete -c spack -n '__fish_spack_using_command env remove' -s h -l help -d 'sh
 complete -c spack -n '__fish_spack_using_command env remove' -s y -l yes-to-all -f -a yes_to_all
 complete -c spack -n '__fish_spack_using_command env remove' -s y -l yes-to-all -d 'assume "yes" is the answer to every confirmation request'
 complete -c spack -n '__fish_spack_using_command env remove' -s f -l force -f -a force
-complete -c spack -n '__fish_spack_using_command env remove' -s f -l force -d 'remove the environment even if it is included in another environment'
+complete -c spack -n '__fish_spack_using_command env remove' -s f -l force -d 'force removal even when included in other environment(s)'
 
 # spack env rm
 set -g __fish_spack_optspecs_spack_env_rm h/help y/yes-to-all f/force
@@ -1572,7 +1572,7 @@ complete -c spack -n '__fish_spack_using_command env rm' -s h -l help -d 'show t
 complete -c spack -n '__fish_spack_using_command env rm' -s y -l yes-to-all -f -a yes_to_all
 complete -c spack -n '__fish_spack_using_command env rm' -s y -l yes-to-all -d 'assume "yes" is the answer to every confirmation request'
 complete -c spack -n '__fish_spack_using_command env rm' -s f -l force -f -a force
-complete -c spack -n '__fish_spack_using_command env rm' -s f -l force -d 'remove the environment even if it is included in another environment'
+complete -c spack -n '__fish_spack_using_command env rm' -s f -l force -d 'force removal even when included in other environment(s)'
 
 # spack env rename
 set -g __fish_spack_optspecs_spack_env_rename h/help d/dir f/force
@@ -1580,9 +1580,9 @@ set -g __fish_spack_optspecs_spack_env_rename h/help d/dir f/force
 complete -c spack -n '__fish_spack_using_command env rename' -s h -l help -f -a help
 complete -c spack -n '__fish_spack_using_command env rename' -s h -l help -d 'show this help message and exit'
 complete -c spack -n '__fish_spack_using_command env rename' -s d -l dir -f -a dir
-complete -c spack -n '__fish_spack_using_command env rename' -s d -l dir -d 'the specified arguments correspond to directory paths'
+complete -c spack -n '__fish_spack_using_command env rename' -s d -l dir -d 'positional arguments are environment directory paths'
 complete -c spack -n '__fish_spack_using_command env rename' -s f -l force -f -a force
-complete -c spack -n '__fish_spack_using_command env rename' -s f -l force -d 'allow overwriting of an existing environment'
+complete -c spack -n '__fish_spack_using_command env rename' -s f -l force -d 'force renaming even if overwriting an existing environment'
 
 # spack env mv
 set -g __fish_spack_optspecs_spack_env_mv h/help d/dir f/force
@@ -1590,9 +1590,9 @@ set -g __fish_spack_optspecs_spack_env_mv h/help d/dir f/force
 complete -c spack -n '__fish_spack_using_command env mv' -s h -l help -f -a help
 complete -c spack -n '__fish_spack_using_command env mv' -s h -l help -d 'show this help message and exit'
 complete -c spack -n '__fish_spack_using_command env mv' -s d -l dir -f -a dir
-complete -c spack -n '__fish_spack_using_command env mv' -s d -l dir -d 'the specified arguments correspond to directory paths'
+complete -c spack -n '__fish_spack_using_command env mv' -s d -l dir -d 'positional arguments are environment directory paths'
 complete -c spack -n '__fish_spack_using_command env mv' -s f -l force -f -a force
-complete -c spack -n '__fish_spack_using_command env mv' -s f -l force -d 'allow overwriting of an existing environment'
+complete -c spack -n '__fish_spack_using_command env mv' -s f -l force -d 'force renaming even if overwriting an existing environment'
 
 # spack env list
 set -g __fish_spack_optspecs_spack_env_list h/help
@@ -1659,15 +1659,15 @@ complete -c spack -n '__fish_spack_using_command_pos_remainder 0 env depfile' -f
 complete -c spack -n '__fish_spack_using_command env depfile' -s h -l help -f -a help
 complete -c spack -n '__fish_spack_using_command env depfile' -s h -l help -d 'show this help message and exit'
 complete -c spack -n '__fish_spack_using_command env depfile' -l make-prefix -l make-target-prefix -r -f -a make_prefix
-complete -c spack -n '__fish_spack_using_command env depfile' -l make-prefix -l make-target-prefix -r -d 'prefix Makefile targets (and variables) with <TARGET>/<name>'
+complete -c spack -n '__fish_spack_using_command env depfile' -l make-prefix -l make-target-prefix -r -d 'prefix Makefile targets/variables with <TARGET>/<name>,'
 complete -c spack -n '__fish_spack_using_command env depfile' -l make-disable-jobserver -f -a jobserver
 complete -c spack -n '__fish_spack_using_command env depfile' -l make-disable-jobserver -d 'disable POSIX jobserver support'
 complete -c spack -n '__fish_spack_using_command env depfile' -l use-buildcache -r -f -a use_buildcache
-complete -c spack -n '__fish_spack_using_command env depfile' -l use-buildcache -r -d 'when using `only`, redundant build dependencies are pruned from the DAG'
+complete -c spack -n '__fish_spack_using_command env depfile' -l use-buildcache -r -d 'use `only` to prune redundant build dependencies'
 complete -c spack -n '__fish_spack_using_command env depfile' -s o -l output -r -f -a output
 complete -c spack -n '__fish_spack_using_command env depfile' -s o -l output -r -d 'write the depfile to FILE rather than to stdout'
 complete -c spack -n '__fish_spack_using_command env depfile' -s G -l generator -r -f -a make
-complete -c spack -n '__fish_spack_using_command env depfile' -s G -l generator -r -d 'specify the depfile type'
+complete -c spack -n '__fish_spack_using_command env depfile' -s G -l generator -r -d 'specify the depfile type (only supports `make`)'
 
 # spack extensions
 set -g __fish_spack_optspecs_spack_extensions h/help l/long L/very-long d/deps p/paths s/show=