Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explain role names installed from Git URLs #2767

Open
wants to merge 1 commit into
base: devel
Choose a base branch
from
+12 −3
Open

Explain role names installed from Git URLs #2767

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/docsite/rst/contributing/creating_role.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ Prior to Galaxy v3.0, the role import process would alter the GitHub repository
apply a regular expression, and remove 'ansible-' and 'role-' from the repository name. For example, a repository name of
*ansible-role-apache* would become *apache*.

Starting in v3.0, Galaxy no longer perform this calculation. Instead, the default role name is the unaltered repository name, with a
Starting in v3.0, Galaxy no longer performs this calculation. Instead, the default role name is the unaltered repository name, with a
couple minor exceptions, including: converting the name to all lowercase, and replacing any '-' or '.' characters with '_'.

To override the default name, set the ``role_name`` attribute in the role ``meta/main.yml`` file. The following snippet from a
Expand All @@ -193,4 +193,4 @@ To override the default name, set the ``role_name`` attribute in the role ``meta

.. note::

`role_name` is not used at all if the role is installed using its Git URL. Instead, the name of the repo is used.
`role_name` is ignored when installing a role using its Git URL. Instead, the role name defaults to the repository name.
11 changes: 10 additions & 1 deletion docs/docsite/rst/using/installing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ role.

.. code-block:: bash

$ ansible-galaxy install geerlingguy.apache,v1.0.0
$ ansible-galaxy install geerlingguy.apache,1.0.0

It's also possible to point directly to the git repository and specify a branch name or commit hash as the version.
For example, the following installs a specific commit:
Expand All @@ -67,6 +67,15 @@ For example, the following installs a specific commit:

$ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25

The name of a role installed from a repository defaults to the name of the repository (in this case ``ansible-role-apache``).
A different name can be specified after the version:

.. code-block:: bash

$ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,master,geerlingguy.apache

This command installs the latest commit from ``master`` with the same role name ``geerlingguy.apache`` used by Galaxy.

Listing Your Installed Roles
----------------------------

Expand Down