# salt.states.git

States to manage git repositories and git configuration

Important

Before using git over ssh, make sure your remote host fingerprint exists in your `~/.ssh/known_hosts` file.

Changed in version 2015.8.8: This state module now requires git 1.6.5 (released 10 October 2009) or newer.

salt.states.git.cloned(name, target, branch=None, user=None, password=None, identity=None, https_user=None, https_pass=None, output_encoding=None)

  Added in version 2018.3.3,2019.2.0.

  Ensure that a repository has been cloned to the specified target directory. If not, clone that repository. No fetches will be performed once cloned.

  name

    Address of the remote repository

  target

    Name of the target directory where repository should be cloned

  branch

    Remote branch to check out. If unspecified, the default branch (i.e. the one to the remote HEAD points) will be checked out.

    Note

    The local branch name will match the remote branch name. If the branch name is changed, then that branch will be checked out locally, but keep in mind that remote repository will not be fetched. If your use case requires that you keep the clone up to date with the remote repository, then consider using `git.latest`.

  user

    User under which to run git commands. By default, commands are run by the user under which the minion is running.

  password

    Windows only. Required when specifying `user`. This parameter will be ignored on non-Windows platforms.

  identity

    Path to a private key to use for ssh URLs. Works the same way as in `git.latest`, see that state's documentation for more information.

  https_user

    HTTP Basic Auth username for HTTPS (only) clones

  https_pass

    HTTP Basic Auth password for HTTPS (only) clones

  output_encoding

    Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases.

    Note

    This should only be needed if the files in the repository were created with filenames using an encoding other than UTF-8 to handle Unicode characters.

salt.states.git.config_set(name, value=None, multivar=None, repo=None, user=None, password=None, output_encoding=None, **kwargs)

  Added in version 2014.7.0.

  Changed in version 2015.8.0: Renamed from `git.config` to `git.config_set`. For earlier versions, use `git.config`.

  Ensure that a config value is set to the desired value(s)

  name

    Name of the git config value to set

  value

    Set a single value for the config item

  multivar

    Set multiple values for the config item

    Note

    The order matters here, if the same parameters are set but in a different order, they will be removed and replaced in the order specified.

    Added in version 2015.8.0.

  repo

    Location of the git repository for which the config value should be set. Required unless `global` is set to `True`.

  user

    User under which to run git commands. By default, the commands are run by the user under which the minion is running.

  password

    > Windows only. Required when specifying `user`. This parameter will be ignored on non-Windows platforms.

    Added in version 2016.3.4.

  globalFalse

    If `True`, this will set a global git config option

  output_encoding

    Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases.

    Note

    This should only be needed if the files in the repository were created with filenames using an encoding other than UTF-8 to handle Unicode characters.

    Added in version 2018.3.1.

  Local Config Example:

      # Single value
      mylocalrepo:
        git.config_set:
          - name: user.email
          - value: foo@bar.net
          - repo: /path/to/repo

      # Multiple values
      mylocalrepo:
        git.config_set:
          - name: mysection.myattribute
          - multivar:
            - foo
            - bar
            - baz
          - repo: /path/to/repo

  Global Config Example (User ``foo``):

      mylocalrepo:
        git.config_set:
          - name: user.name
          - value: Foo Bar
          - user: foo
          - global: True

salt.states.git.config_unset(name, value_regex=None, repo=None, user=None, password=None, output_encoding=None, **kwargs)

  Added in version 2015.8.0.

  Ensure that the named config key is not present

  name

    The name of the configuration key to unset. This value can be a regex, but the regex must match the entire key name. For example, `foo\.` would not match all keys in the `foo` section, it would be necessary to use `foo\..+` to do so.

  value_regex

    Regex indicating the values to unset for the matching key(s)

    Note

    This option behaves differently depending on whether or not `all` is set to `True`. If it is, then all values matching the regex will be deleted (this is the only way to delete multiple values from a multivar). If `all` is set to `False`, then this state will fail if the regex matches more than one value in a multivar.

  allFalse

    If `True`, unset all matches

  repo

    Location of the git repository for which the config value should be set. Required unless `global` is set to `True`.

  user

    User under which to run git commands. By default, commands are run by the user under which the minion is running.

  password

    > Windows only. Required when specifying `user`. This parameter will be ignored on non-Windows platforms.

    Added in version 2016.3.4.

  globalFalse

    If `True`, this will set a global git config option

  output_encoding

    Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases.

    Note

    This should only be needed if the files in the repository were created with filenames using an encoding other than UTF-8 to handle Unicode characters.

    Added in version 2018.3.1.

  Examples:

      # Value matching 'baz'
      mylocalrepo:
        git.config_unset:
          - name: foo.bar
          - value_regex: 'baz'
          - repo: /path/to/repo

      # Ensure entire multivar is unset
      mylocalrepo:
        git.config_unset:
          - name: foo.bar
          - all: True

      # Ensure all variables in 'foo' section are unset, including multivars
      mylocalrepo:
        git.config_unset:
          - name: 'foo\..+'
          - all: True

      # Ensure that global config value is unset
      mylocalrepo:
        git.config_unset:
          - name: foo.bar
          - global: True

salt.states.git.detached(name, rev, target, remote='origin', user=None, password=None, force_clone=False, force_checkout=False, fetch_remote=True, hard_reset=False, submodules=False, identity=None, https_user=None, https_pass=None, output_encoding=None, **kwargs)

  Added in version 2016.3.0.

  Make sure a repository is cloned to the given target directory and is a detached HEAD checkout of the commit ID resolved from `rev`.

  name

    Address of the remote repository.

  rev

    The branch, tag, or commit ID to checkout after clone. If a branch or tag is specified it will be resolved to a commit ID and checked out.

  target

    Name of the target directory where repository is about to be cloned.

  remoteorigin

    Git remote to use. If this state needs to clone the repo, it will clone it using this value as the initial remote name. If the repository already exists, and a remote by this name is not present, one will be added.

  user

    User under which to run git commands. By default, commands are run by the user under which the minion is running.

  password

    > Windows only. Required when specifying `user`. This parameter will be ignored on non-Windows platforms.

    Added in version 2016.3.4.

  force_cloneFalse

    If the `target` directory exists and is not a git repository, then this state will fail. Set this argument to `True` to remove the contents of the target directory and clone the repo into it.

  force_checkoutFalse

    When checking out the revision ID, the state will fail if there are unwritten changes. Set this argument to `True` to discard unwritten changes when checking out.

  fetch_remoteTrue

    If `False` a fetch will not be performed and only local refs will be reachable.

  hard_resetFalse

    If `True` a hard reset will be performed before the checkout and any uncommitted modifications to the working directory will be discarded. Untracked files will remain in place.

    Note

    Changes resulting from a hard reset will not trigger requisites.

  submodulesFalse

    Update submodules

  identity

    A path on the minion (or a SaltStack fileserver URL, e.g. `salt://path/to/identity_file`) to a private key to use for SSH authentication.

  https_user

    HTTP Basic Auth username for HTTPS (only) clones

  https_pass

    HTTP Basic Auth password for HTTPS (only) clones

  output_encoding

    Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases.

    Note

    This should only be needed if the files in the repository were created with filenames using an encoding other than UTF-8 to handle Unicode characters.

    Added in version 2018.3.1.

salt.states.git.latest(name, target, rev='HEAD', branch=None, user=None, password=None, update_head=True, force_checkout=False, force_clone=False, force_fetch=False, force_reset=False, submodules=False, bare=False, mirror=False, remote='origin', fetch_tags=True, sync_tags=True, depth=None, identity=None, https_user=None, https_pass=None, refspec_branch='*', refspec_tag='*', output_encoding=None, **kwargs)

  Make sure the repository is cloned to the given directory and is up-to-date.

  name

    Address of the remote repository, as passed to `git clone`

    Note

    From the Git documentation, there are two URL formats supported for SSH authentication. The below two examples are equivalent:

        # ssh:// URL
        ssh://user@server/project.git

        # SCP-like syntax
        user@server:project.git

    A common mistake is to use an `ssh://` URL, but with a colon after the domain instead of a slash. This is invalid syntax in Git, and will therefore not work in Salt. When in doubt, confirm that a `git clone` works for the URL before using it in Salt.

    It has been reported by some users that SCP-like syntax is incompatible with git repos hosted on Atlassian Stash/BitBucket Server. In these cases, it may be necessary to use `ssh://` URLs for SSH authentication.

  revHEAD

    The remote branch, tag, or revision ID to checkout after clone / before update. If specified, then Salt will also ensure that the tracking branch is set to `<remote>/<rev>`, unless `rev` refers to a tag or SHA1, in which case Salt will ensure that the tracking branch is unset.

    If `rev` is not specified, it will be assumed to be `HEAD`, and Salt will not manage the tracking branch at all.

    Changed in version 2015.8.0: If not specified, `rev` now defaults to the remote repository's HEAD.

  target

    Name of the target directory where repository is about to be cloned

  branch

    Name of the local branch into which to checkout the specified rev. If not specified, then Salt will not care what branch is being used locally and will just use whatever branch is currently there.

    Added in version 2015.8.0.

    Note

    If this argument is not specified, this means that Salt will not change the local branch if the repository is reset to another branch/tag/SHA1. For example, assume that the following state was run initially:

        foo_app:
          git.latest:
            - name: https://mydomain.tld/apps/foo.git
            - target: /var/www/foo
            - user: www

    This would have cloned the HEAD of that repo (since a `rev` wasn't specified), and because `branch` is not specified, the branch in the local clone at `/var/www/foo` would be whatever the default branch is on the remote repository (usually `master`, but not always). Now, assume that it becomes necessary to switch this checkout to the `dev` branch. This would require `rev` to be set, and probably would also require `force_reset` to be enabled:

        foo_app:
          git.latest:
            - name: https://mydomain.tld/apps/foo.git
            - target: /var/www/foo
            - user: www
            - rev: dev
            - force_reset: True

    The result of this state would be to perform a hard-reset to `origin/dev`. Since `branch` was not specified though, while `/var/www/foo` would reflect the contents of the remote repo's `dev` branch, the local branch would still remain whatever it was when it was cloned. To make the local branch match the remote one, set `branch` as well, like so:

        foo_app:
          git.latest:
            - name: https://mydomain.tld/apps/foo.git
            - target: /var/www/foo
            - user: www
            - rev: dev
            - branch: dev
            - force_reset: True

    This may seem redundant, but Salt tries to support a wide variety of use cases, and doing it this way allows for the use case where the local branch doesn't need to be strictly managed.

  user

    Local system user under which to run git commands. By default, commands are run by the user under which the minion is running.

    Note

    This is not to be confused with the username for http(s)/SSH authentication.

    Added in version 0.17.0.

  password

    Windows only. Required when specifying `user`. This parameter will be ignored on non-Windows platforms.

    Added in version 2016.3.4.

  update_headTrue

    If set to `False`, then the remote repository will be fetched (if necessary) to ensure that the commit to which `rev` points exists in the local checkout, but no changes will be made to the local HEAD.

    Added in version 2015.8.3.

  force_checkoutFalse

    When checking out the local branch, the state will fail if there are unwritten changes. Set this argument to `True` to discard unwritten changes when checking out.

  force_cloneFalse

    If the `target` directory exists and is not a git repository, then this state will fail. Set this argument to `True` to remove the contents of the target directory and clone the repo into it.

  force_fetchFalse

    If a fetch needs to be performed, non-fast-forward fetches will cause this state to fail. Set this argument to `True` to force the fetch even if it is a non-fast-forward update.

    Added in version 2015.8.0.

  force_resetFalse

    If the update is not a fast-forward, this state will fail. Set this argument to `True` to force a hard-reset to the remote revision in these cases.

    Changed in version 2019.2.0: This option can now be set to `remote-changes`, which will instruct Salt not to discard local changes if the repo is up-to-date with the remote repository.

  submodulesFalse

    Update submodules on clone or branch change

  bareFalse

    Set to `True` if the repository is to be a bare clone of the remote repository.

  mirror

    Set to `True` if the repository is to be a mirror of the remote repository. This implies that `bare` set to `True`, and thus is incompatible with `rev`.

  remoteorigin

    Git remote to use. If this state needs to clone the repo, it will clone it using this value as the initial remote name. If the repository already exists, and a remote by this name is not present, one will be added.

  fetch_tagsTrue

    If `True`, then when a fetch is performed all tags will be fetched, even those which are not reachable by any branch on the remote.

  sync_tagsTrue

    If `True`, then Salt will delete tags which exist in the local clone but are not found on the remote repository.

    Added in version 2018.3.4.

  depth

    Defines depth in history when git a clone is needed in order to ensure latest. E.g. `depth: 1` is useful when deploying from a repository with a long history. Use rev to specify branch or tag. This is not compatible with revision IDs.

    Changed in version 2019.2.0: This option now supports tags as well as branches, on Git 1.8.0 and newer.

  identity

    Path to a private key to use for ssh URLs. This can be either a single string, or a list of strings. For example:

        # Single key
        git@github.com:user/repo.git:
          git.latest:
            - user: deployer
            - identity: /home/deployer/.ssh/id_rsa

        # Two keys
        git@github.com:user/repo.git:
          git.latest:
            - user: deployer
            - identity:
              - /home/deployer/.ssh/id_rsa
              - /home/deployer/.ssh/id_rsa_alternate

    If multiple keys are specified, they will be tried one-by-one in order for each git command which needs to authenticate.

    Warning

    Unless Salt is invoked from the minion using `salt-call`, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the sshd(8) manpage for information on securing the keypair from the remote side in the `authorized_keys` file.

    Changed in version 2015.8.7: Salt will no longer attempt to use passphrase-protected keys unless invoked from the minion using `salt-call`, to prevent blocking waiting for user input.

    Changed in version 2016.3.0: Key can now be specified as a SaltStack fileserver URL (e.g. `salt://path/to/identity_file`).

  https_user

    HTTP Basic Auth username for HTTPS (only) clones

    Added in version 2015.5.0.

  https_pass

    HTTP Basic Auth password for HTTPS (only) clones

    Added in version 2015.5.0.

  refspec_branch*

    A glob expression defining which branches to retrieve when fetching. See git-fetch(1) for more information on how refspecs work.

    Added in version 2017.7.0.

  refspec_tag*

    A glob expression defining which tags to retrieve when fetching. See git-fetch(1) for more information on how refspecs work.

    Added in version 2017.7.0.

  output_encoding

    Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases.

    Note

    This should only be needed if the files in the repository were created with filenames using an encoding other than UTF-8 to handle Unicode characters.

    Added in version 2018.3.1.

  Note

  Clashing ID declarations can be avoided when including different branches from the same git repository in the same SLS file by using the `name` argument. The example below checks out the `gh-pages` and `gh-pages-prod` branches from the same repository into separate directories. The example also sets up the `ssh_known_hosts` ssh key required to perform the git checkout.

      gitlab.example.com:
        ssh_known_hosts:
          - present
          - user: root
          - enc: ecdsa
          - fingerprint: 4e:94:b0:54:c1:5b:29:a2:70:0e:e1:a3:51:ee:ee:e3

      git-website-staging:
        git.latest:
          - name: git@gitlab.example.com:user/website.git
          - rev: gh-pages
          - target: /usr/share/nginx/staging
          - identity: /root/.ssh/website_id_rsa
          - require:
            - pkg: git
            - ssh_known_hosts: gitlab.example.com

      git-website-staging:
        git.latest:
          - name: git@gitlab.example.com:user/website.git
          - rev: gh-pages
          - target: /usr/share/nginx/staging
          - identity: salt://website/id_rsa
          - require:
            - pkg: git
            - ssh_known_hosts: gitlab.example.com

      git-website-prod:
        git.latest:
          - name: git@gitlab.example.com:user/website.git
          - rev: gh-pages-prod
          - target: /usr/share/nginx/prod
          - identity: /root/.ssh/website_id_rsa
          - require:
            - pkg: git
            - ssh_known_hosts: gitlab.example.com

salt.states.git.present(name, force=False, bare=True, template=None, separate_git_dir=None, shared=None, user=None, password=None, output_encoding=None)

  Ensure that a repository exists in the given directory

  Warning

  If the minion has Git 2.5 or later installed, `name` points to a worktree, and `force` is set to `True`, then the worktree will be deleted. This has been corrected in Salt 2015.8.0.

  name

    Path to the directory

    Changed in version 2015.8.0: This path must now be absolute

  forceFalse

    If `True`, and if `name` points to an existing directory which does not contain a git repository, then the contents of that directory will be recursively removed and a new repository will be initialized in its place.

  bareTrue

    If `True`, and a repository must be initialized, then the repository will be a bare repository.

    Note

    This differs from the default behavior of `git.init`, make sure to set this value to `False` if a bare repo is not desired.

  template

    If a new repository is initialized, this argument will specify an alternate template directory.

    Added in version 2015.8.0.

  separate_git_dir

    If a new repository is initialized, this argument will specify an alternate `$GIT_DIR`

    Added in version 2015.8.0.

  shared

    Set sharing permissions on git repo. See git-init(1) for more details.

    Added in version 2015.5.0.

  user

    User under which to run git commands. By default, commands are run by the user under which the minion is running.

    Added in version 0.17.0.

  password

    > Windows only. Required when specifying `user`. This parameter will be ignored on non-Windows platforms.

    Added in version 2016.3.4.

  output_encoding

    Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases.

    Note

    This should only be needed if the files in the repository were created with filenames using an encoding other than UTF-8 to handle Unicode characters.

    Added in version 2018.3.1.