From 85d9a40aacd4ec04dd6dd86cb681efb3475645c3 Mon Sep 17 00:00:00 2001
From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
Date: Wed, 18 Sep 2024 15:07:21 -0400
Subject: [PATCH] Clarify galaxy CLI --help about install locations (#83919)

* add descriptions for `ansible-galaxy install` and `ansible-galaxy role|collection install`

* fix the usage for installing roles and collections together and include collections in the description for -r

Closes #81159

Co-authored-by: Alan Rominger <arominge@redhat.com>
Co-authored-by: Sandra McCann <samccann@redhat.com>
---
 .../fragments/ansible-galaxy-install-help.yml |  5 +++
 lib/ansible/cli/galaxy.py                     | 31 ++++++++++++++++---
 2 files changed, 32 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/fragments/ansible-galaxy-install-help.yml

diff --git a/changelogs/fragments/ansible-galaxy-install-help.yml b/changelogs/fragments/ansible-galaxy-install-help.yml
new file mode 100644
index 00000000000..31b6de9a3ca
--- /dev/null
+++ b/changelogs/fragments/ansible-galaxy-install-help.yml
@@ -0,0 +1,5 @@
+bugfixes:
+- >-
+  Add descriptions for ``ansible-galaxy install --help` and ``ansible-galaxy role|collection install --help``.
+- >-
+  ``ansible-galaxy install --help`` - Fix the usage text and document that the requirements file passed to ``-r`` can include collections and roles.
diff --git a/lib/ansible/cli/galaxy.py b/lib/ansible/cli/galaxy.py
index 6ea3f708eec..19ccd400445 100755
--- a/lib/ansible/cli/galaxy.py
+++ b/lib/ansible/cli/galaxy.py
@@ -468,12 +468,31 @@ class GalaxyCLI(CLI):
             ignore_errors_help = 'Ignore errors during installation and continue with the next specified ' \
                                  'collection. This will not ignore dependency conflict errors.'
         else:
-            args_kwargs['help'] = 'Role name, URL or tar file'
+            args_kwargs['help'] = 'Role name, URL or tar file. This is mutually exclusive with -r.'
             ignore_errors_help = 'Ignore errors and continue with the next specified role.'
 
+        if self._implicit_role:
+            # might install both roles and collections
+            description_text = (
+                'Install roles and collections from file(s), URL(s) or Ansible '
+                'Galaxy to the first entry in the config COLLECTIONS_PATH for collections '
+                'and first entry in the config ROLES_PATH for roles. '
+                'The first entry in the config ROLES_PATH can be overridden by --roles-path '
+                'or -p, but this will result in only roles being installed.'
+            )
+            prog = 'ansible-galaxy install'
+        else:
+            prog = parser._prog_prefix
+            description_text = (
+                'Install {0}(s) from file(s), URL(s) or Ansible '
+                'Galaxy to the first entry in the config {1}S_PATH '
+                'unless overridden by --{0}s-path.'.format(galaxy_type, galaxy_type.upper())
+            )
         install_parser = parser.add_parser('install', parents=parents,
                                            help='Install {0}(s) from file(s), URL(s) or Ansible '
-                                                'Galaxy'.format(galaxy_type))
+                                                'Galaxy'.format(galaxy_type),
+                                           description=description_text,
+                                           prog=prog,)
         install_parser.set_defaults(func=self.execute_install)
 
         install_parser.add_argument('args', metavar='{0}_name'.format(galaxy_type), nargs='*', **args_kwargs)
@@ -526,8 +545,12 @@ class GalaxyCLI(CLI):
                                              'This does not apply to collections in remote Git repositories or URLs to remote tarballs.'
                                         )
         else:
-            install_parser.add_argument('-r', '--role-file', dest='requirements',
-                                        help='A file containing a list of roles to be installed.')
+            if self._implicit_role:
+                install_parser.add_argument('-r', '--role-file', dest='requirements',
+                                            help='A file containing a list of collections and roles to be installed.')
+            else:
+                install_parser.add_argument('-r', '--role-file', dest='requirements',
+                                            help='A file containing a list of roles to be installed.')
 
             r_re = re.compile(r'^(?<!-)-[a-zA-Z]*r[a-zA-Z]*')  # -r, -fr
             contains_r = bool([a for a in self._raw_args if r_re.match(a)])