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 (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.
    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.
                    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 full 40-character SHA-1 hash, the literal string HEAD, a branch name, or a tag name.

                      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://git@github.com/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/*

                      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 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.

                      This is a Core Module

                      For more information on what this means please read Core Modules

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