Clarify galaxy CLI --help about install locations

[AlanCoding]

SUMMARY

I asked a lot of questions to @john-westcott-iv on ansible/awx#14081 which we discovered really came down to docs of the ansible-galaxy commands themselves.

In #67843 a new ansible-galaxy install command was introduced which could install both roles and collections. The options are well-documented, but the effect of the command is actually unclear. To explain why this the case, consider:

ansible-galaxy role install --help

What does this command do? The help text should show this in the main body of the text. It doesn't quite do that, but it does have that information buried in an option.

  -p ROLES_PATH, --roles-path ROLES_PATH
                        The path to the directory containing your roles. The default is the first writable one
                        configured via DEFAULT_ROLES_PATH: {{ ANSIBLE_HOME ~
                        "/roles:/usr/share/ansible/roles:/etc/ansible/roles" }} . This argument may be specified
                        multiple times.

Yes, it is obvious that it installs roles but where does it install them? This help text answers that.

Surprisingly, this question is not answered at all for either

• ansible-galaxy install --help or
• ansible-galaxy collection install --help

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

lib/ansible/cli/galaxy.py

ADDITIONAL INFORMATION

With this change, we get:

$ ansible-galaxy role install --help
usage: ansible-galaxy role install [-h] [-s API_SERVER] [--token API_KEY] [-c] [--timeout TIMEOUT] [-v] [-f]
                                   [-p ROLES_PATH] [-i] [-n | --force-with-deps] [-r REQUIREMENTS] [-g]
                                   [role_name ...]

Install role(s) from file(s), URL(s) or Ansible Galaxy to the first entry in the config ROLES_PATH unless overriden
by --roles-path

$ ansible-galaxy collection install --help
usage: ansible-galaxy collection install [-h] [-s API_SERVER] [--token API_KEY] [-c] [--timeout TIMEOUT] [-v] [-f]
                                         [--clear-response-cache] [--no-cache] [-i] [-n | --force-with-deps]
                                         [-p COLLECTIONS_PATH] [-r REQUIREMENTS] [--pre] [-U] [--keyring KEYRING]
                                         [--disable-gpg-verify] [--signature SIGNATURES]
                                         [--required-valid-signature-count REQUIRED_VALID_SIGNATURE_COUNT]
                                         [--ignore-signature-status-code {EXPSIG,EXPKEYSIG,REVKEYSIG,BADSIG,ERRSIG,NO_PUBKEY,MISSING_PASSPHRASE,BAD_PASSPHRASE,NODATA,UNEXPECTED,ERROR,FAILURE,BADARMOR,KEYEXPIRED,KEYREVOKED,NO_SECKEY}]
                                         [--offline]
                                         [collection_name ...]

Install collection(s) from file(s), URL(s) or Ansible Galaxy to the first entry in the config COLLECTIONS_PATH
unless overriden by --collections-path

and

$ ansible-galaxy install --help
usage: ansible-galaxy role install [-h] [-s API_SERVER] [--token API_KEY] [-c] [--timeout TIMEOUT] [-v] [-f]
                                   [-p ROLES_PATH] [-i] [-n | --force-with-deps] [-r REQUIREMENTS] [-g]
                                   [role_name ...]

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.

To me, this answers the question of "what does this do?" for each command.

There are still some other shortcomings that I did not address with this, but I want to mention anyway:

• the ansible-galaxy install command has a --roles-path CLI option, but no collections path option
• the install subcommand isn't listed in ansible-galaxy --help

For now, I wanted to stop at a purely docs patch, as this should change the help text rendering, but not change anything about the behavior.

[s-hertel]

• the install subcommand isn't listed in ansible-galaxy --help

I agree this would be good to mention since it supports collections in addition to roles. Maybe the description could be amended to generally mention the role subcommands:

Perform various Role and Collection related operations. The role subcommands have top-level aliases. ansible-galaxy install has additional support to install collections from a requirements file if --roles-path is not provided.

[s-hertel]

This collections_path option is not the one used by install (https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/galaxy.py#L512-L514), and can include paths ansible-galaxy collection install will not use.

[AlanCoding]

Correct that, in devel branch, this --collections-path option is not used by ansible-galaxy install, and I'm not really trying to change that. For my own selfish purposes, I just want to consolidate our use cases such that we use the environment variables ANSIBLE_COLLECTIONS_PATHS and ANSIBLE_ROLES_PATH. And the reason I made this PR is because I found that non-obvious.

https://github.com/ansible/awx/blob/3624fe2cac7eccf845e46afbb88b6d2d8af7b41a/awx/playbooks/project_update.yml#L196-L197

You can use the --collections-path in this install command, which is why I made this particular change to this line:

ansible-galaxy collection install awx.awx -p alan

My gripe was that this help text was written assuming the user was running ansible-galaxy collection list -p alan/, but the option was reused for the ansible-galaxy collection install.

[s-hertel]

This could mention that if -p/--roles-path is provided only roles are installed. If there are collections in the requirements.yml too, a warning is given about the potentially ambiguous option, and that collections won't be installed.

the ansible-galaxy install command has a --roles-path CLI option, but no collections path option

None of the collection-specific CLI install options are supported, only collection options that are also supported by roles. Role-specific options are supported for backwards compatibility because ansible-galaxy install handled roles originally.

If a --collections-path option is added, -p should probably be removed as a valid alias for --roles-path, since it's also an alias normally for --collections-path.

[bcoca]

tempted to say just use --install-path and even if people see the 'wrong' help .. it will be right!

We can put it before existing options, move those to last and add deprecation to them in future

[nitzmahone]

consider as a 2.18 task