ansible/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt

You can install a collection in a git repository by providing the URI to the repository instead of a collection name or path to a ``tar.gz`` file. The collection must contain a ``galaxy.yml`` or ``MANIFEST.json`` file, which will be used to generate the would-be collection artifact data from the directory. The URI should be prefixed with ``git+`` (or with ``git@`` to use a private repository with ssh authentication) and optionally supports a comma-separated `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ version (for example, a commit or tag).

.. warning::

   Embedding credentials into a git URI is not secure. Make sure to use safe auth options for security reasons. For example, use `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_, `netrc <https://linux.die.net/man/5/netrc>`_ or `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_/`url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ in Git config to prevent your creds from being exposed in logs.

.. code-block:: bash

   # Install a collection in a repository using the latest commit on the branch 'devel'
   ansible-galaxy collection install git+https://github.com/organization/repo_name.git,devel

   # Install a collection from a private github repository
   ansible-galaxy collection install git@github.com:organization/repo_name.git

   # Install a collection from a local git repository
   ansible-galaxy collection install git+file:///home/user/path/to/repo/.git

In a ``requirements.yml`` file, you can also use the ``type`` and ``version`` keys in addition to using the ``git+repo,version`` syntax for the collection name.

.. code-block:: yaml

   collections:
     - name: https://github.com/organization/repo_name.git
       type: git
       version: devel

Git repositories can be used for collection dependencies as well. This can be helpful for local development and testing but built/published artifacts should only have dependencies on other artifacts.

.. code-block:: yaml

   dependencies: {'git@github.com:organization/repo_name.git': 'devel'}

Default repository search locations
-----------------------------------

There are two paths searched in a repository for collections by default.

The first is the ``galaxy.yml`` or ``MANIFEST.json`` file in the top level of the repository path. If the file exists it's used as the collection metadata and the individual collection will be installed.

.. code-block:: text

   ├── galaxy.yml
   ├── plugins/
   │   ├── lookup/
   │   ├── modules/
   │   └── module_utils/
   └─── README.md

The second is a ``galaxy.yml`` or ``MANIFEST.json`` file in each directory in the repository path (one level deep). In this scenario, each directory with a metadata file is installed as a collection.

.. code-block:: text

   directory/
   ├── docs/
   ├── MANIFEST.json
   ├── plugins/
   │   ├── inventory/
   │   └── modules/
   └── roles/

Specifying the location to search for collections
-------------------------------------------------

If you have a different repository structure or only want to install a subset of collections, you can add a fragment to the end of your URI (before the optional comma-separated version) to indicate which path ansible-galaxy should inspect for metadata file(s). The path should be a directory to a collection or multiple collections (rather than the path to a ``galaxy.yml`` file or ``MANIFEST.json`` file).

.. code-block:: text

   namespace/
   └── name/
       ├── docs/
       ├── galaxy.yml
       ├── plugins/
       │   ├── README.md
       │   └── modules/
       ├── README.md
       └── roles/

.. code-block:: bash

   # Install all collections in a particular namespace
   ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/

   # Install an individual collection using a specific commit
   ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/name/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5