Documentation

git - Deploy software (or files) from git checkouts

Synopsis

  • Manage git checkouts of repositories to deploy files or software.

Requirements (on host that executes module)

  • git>=1.7.1 (the command line tool)

Options

parameter required default choices comments
accept_hostkey
(added in 1.5)
no no
  • yes
  • no
if yes, adds the hostkey for the repo url if not already added. If ssh_opts contains "-o StrictHostKeyChecking=no", this parameter is ignored.
bare
(added in 1.4)
no no
  • yes
  • no
if yes, repository will be created as a bare repo, otherwise it will be a standard repo with a workspace.
clone
(added in 1.9)
no yes
  • yes
  • no
If no, do not clone the repository if it does not exist locally
depth
no
    Create a shallow clone with a history truncated to the specified number or revisions. The minimum possible value is 1, otherwise ignored. Needs git>=1.9.1 to work correctly.
    dest
    yes
      Absolute path of where the repository should be checked out to. This parameter is required, unless clone is set to no This change was made in version 1.8.3. Prior to this version, the dest parameter was always required.
      executable
      (added in 1.4)
      no
        Path to git executable to use. If not supplied, the normal mechanism for resolving binary paths will be used.
        force
        no no
        • yes
        • no
        If yes, any modified files in the working repository will be discarded. Prior to 0.7, this was always 'yes' and could not be disabled. Prior to 1.9, the default was `yes`
        key_file
        (added in 1.5)
        no None
          Specify an optional private key file to use for the checkout.
          recursive
          (added in 1.6)
          no yes
          • yes
          • no
          if no, repository will be cloned without the --recursive option, skipping sub-modules.
          reference
          (added in 1.4)
          no
            Reference repository (see "git clone --reference ...")
            refspec
            (added in 1.9)
            no
              Add an additional refspec to be fetched. If version is set to a SHA-1 not reachable from any branch or tag, this option may be necessary to specify the ref containing the SHA-1. Uses the same syntax as the 'git fetch' command. An example value could be "refs/meta/config".
              remote
              no origin
                Name of the remote.
                repo
                yes
                  git, SSH, or HTTP(S) protocol address of the git repository.

                  aliases: name
                  ssh_opts
                  (added in 1.5)
                  no None
                    Creates a wrapper script and exports the path as GIT_SSH which git then automatically uses to override ssh arguments. An example value could be "-o StrictHostKeyChecking=no"
                    track_submodules
                    (added in 1.8)
                    no no
                    • yes
                    • no
                    if yes, submodules will track the latest commit on their master branch (or other branch specified in .gitmodules). If no, submodules will be kept at the revision specified by the main project. This is equivalent to specifying the --remote flag to git submodule update.
                    umask
                    (added in 2.2)
                    no
                      The umask to set before doing any checkouts, or any other repository maintenance.
                      update
                      no yes
                      • yes
                      • no
                      If no, do not retrieve new revisions from the origin repository
                      verify_commit
                      (added in 2.0)
                      no no
                      • yes
                      • no
                      if yes, when cloning or checking out a version verify the signature of a GPG signed commit. This requires git version>=2.1.0 to be installed. The commit MUST be signed and the public key MUST be trusted in the GPG trustdb.
                      version
                      no HEAD
                        What version of the repository to check out. This can be the the literal string HEAD, a branch name, a tag name. It can also be a SHA-1 hash, in which case refspec needs to be specified if the given revision is not already available.

                        Examples

                        # Example git checkout from Ansible Playbooks
                        - git:
                            repo: git://foosball.example.org/path/to/repo.git
                            dest: /srv/checkout
                            version: release-0.22
                        
                        # Example read-write git checkout from github
                        - git:
                            repo: ssh:[email protected]/mylogin/hello.git
                            dest: /home/mylogin/hello
                        
                        # Example just ensuring the repo checkout exists
                        - git:
                            repo: git://foosball.example.org/path/to/repo.git
                            dest: /srv/checkout
                            update: no
                        
                        # Example just get information about the repository whether or not it has
                        # already been cloned locally.
                        - git:
                            repo: git://foosball.example.org/path/to/repo.git
                            dest: /srv/checkout
                            clone: no
                            update: no
                        
                        # Example checkout a github repo and use refspec to fetch all pull requests
                        - git:
                            repo: https://github.com/ansible/ansible-examples.git
                            dest: /src/ansible-examples
                            refspec: '+refs/pull/*:refs/heads/*'
                        

                        Return Values

                        Common return values are documented here Return Values, the following are the fields unique to this module:

                        name description returned type sample
                        before commit revision before the repository was updated, "null" for new repository success string 67c04ebe40a003bda0efb34eacfb93b0cafdf628
                        after last commit revision of the repository retrived during the update success string 4c020102a9cd6fe908c9a4a326a38f972f63a903
                        remote_url_changed Contains True or False whether or not the remote URL was changed. success boolean True
                        warnings List of warnings if requested features were not available due to a too old git version. error string Your git version is too old to fully support the depth argument. Falling back to full checkouts.


                        Notes

                        Note

                        If the task seems to be hanging, first verify remote host is in known_hosts. SSH will prompt user to authorize the first contact with a remote host. To avoid this prompt, one solution is to use the option accept_hostkey. Another solution is to add the remote host public key in /etc/ssh/ssh_known_hosts before calling the git module, with the following command: ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts.

                        Status

                        This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

                        Support

                        This module is maintained by those with core commit privileges

                        For more information on what this means please read Module Support

                        For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.