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/*
                        

                        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.

                        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.