From d954d155434ba21975ad3bdff0e27b24bf2ec847 Mon Sep 17 00:00:00 2001
From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
Date: Mon, 30 Sep 2024 09:59:49 -0400
Subject: [PATCH] [2.17] Clarify galaxy CLI --help about install locations
 (#83919) (#83963)

* 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>
(cherry picked from commit 85d9a40aacd4ec04dd6dd86cb681efb3475645c3)

* ansible-galaxy - fix the usage for role/collection install (#83979)

(cherry picked from commit bf8da52aace99515b89952939aab8ef1abd091ef)
---
 .../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 805bd650372..5c506b0c4e2 100755
--- a/lib/ansible/cli/galaxy.py
+++ b/lib/ansible/cli/galaxy.py
@@ -490,12 +490,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 = f"ansible-galaxy {galaxy_type} install"
+            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)
@@ -548,8 +567,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)])