ansible.builtin.git (v2.3.3.0-1) — module

Install Ansible via pip

Install with pip install ansible==2.3.3.0.post1

Description

Manage I(git) checkouts of repositories to deploy files or software.

Requirements

• git>=1.7.1 (the command line tool)

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Example git checkout from Ansible Playbooks
- git:
    repo: git://foosball.example.org/path/to/repo.git
    dest: /srv/checkout
    version: release-0.22

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Example read-write git checkout from github
- git:
    repo: ssh://git@github.com/mylogin/hello.git
    dest: /home/mylogin/hello

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Example just ensuring the repo checkout exists
- git:
    repo: git://foosball.example.org/path/to/repo.git
    dest: /srv/checkout
    update: no

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Inputs

    
bare:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - if C(yes), repository will be created as a bare repo, otherwise it will be a standard
      repo with a workspace.
    required: false
    version_added: '1.4'
    version_added_collection: ansible.builtin

dest:
    description:
    - The path of where the repository should be checked out. This parameter is required,
      unless C(clone) is set to C(no).
    required: true

repo:
    aliases:
    - name
    description:
    - git, SSH, or HTTP(S) protocol address of the git repository.
    required: true

clone:
    choices:
    - 'yes'
    - 'no'
    default: 'yes'
    description:
    - If C(no), do not clone the repository if it does not exist locally
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

depth:
    default: null
    description:
    - Create a shallow clone with a history truncated to the specified number or revisions.
      The minimum possible value is C(1), otherwise ignored. Needs I(git>=1.9.1) to work
      correctly.
    required: false
    version_added: '1.2'
    version_added_collection: ansible.builtin

force:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - If C(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`
    required: false
    version_added: '0.7'
    version_added_collection: ansible.builtin

umask:
    default: null
    description:
    - The umask to set before doing any checkouts, or any other repository maintenance.
    required: false
    version_added: '2.2'
    version_added_collection: ansible.builtin

remote:
    default: origin
    description:
    - Name of the remote.
    required: false

update:
    choices:
    - 'yes'
    - 'no'
    default: 'yes'
    description:
    - If C(no), do not retrieve new revisions from the origin repository
    required: false
    version_added: '1.2'
    version_added_collection: ansible.builtin

refspec:
    default: null
    description:
    - Add an additional refspec to be fetched. If version is set to a I(SHA-1) not reachable
      from any branch or tag, this option may be necessary to specify the ref containing
      the I(SHA-1). Uses the same syntax as the 'git fetch' command. An example value
      could be "refs/meta/config".
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

version:
    default: HEAD
    description:
    - What version of the repository to check out.  This can be the the literal string
      C(HEAD), a branch name, a tag name. It can also be a I(SHA-1) hash, in which case
      C(refspec) needs to be specified if the given revision is not already available.
    required: false

key_file:
    default: None
    description:
    - Specify an optional private key file to use for the checkout.
    required: false
    version_added: '1.5'
    version_added_collection: ansible.builtin

ssh_opts:
    default: None
    description:
    - 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"
    required: false
    version_added: '1.5'
    version_added_collection: ansible.builtin

recursive:
    choices:
    - 'yes'
    - 'no'
    default: 'yes'
    description:
    - if C(no), repository will be cloned without the --recursive option, skipping sub-modules.
    required: false
    version_added: '1.6'
    version_added_collection: ansible.builtin

reference:
    default: null
    description:
    - Reference repository (see "git clone --reference ...")
    required: false
    version_added: '1.4'
    version_added_collection: ansible.builtin

executable:
    default: null
    description:
    - Path to git executable to use. If not supplied, the normal mechanism for resolving
      binary paths will be used.
    required: false
    version_added: '1.4'
    version_added_collection: ansible.builtin

verify_commit:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - if C(yes), when cloning or checking out a C(version) verify the signature of a GPG
      signed commit. This requires C(git) version>=2.1.0 to be installed. The commit MUST
      be signed and the public key MUST be trusted in the GPG trustdb.
    required: false
    version_added: '2.0'
    version_added_collection: ansible.builtin

accept_hostkey:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - if C(yes), adds the hostkey for the repo url if not already added. If ssh_opts contains
      "-o StrictHostKeyChecking=no", this parameter is ignored.
    required: false
    version_added: '1.5'
    version_added_collection: ansible.builtin

track_submodules:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - if C(yes), submodules will track the latest commit on their master branch (or other
      branch specified in .gitmodules).  If C(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.
    required: false
    version_added: '1.8'
    version_added_collection: ansible.builtin

Outputs

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