salt.states.git¶

States to manage git repositories and git configuration

重要

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

在 2015.8.8 版更改: This state module now requires git 1.6.5 (released 10 October 2009) or newer.

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

2014.7.0 新版功能.

在 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

注解

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.

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: Optional name of a user as whom git config will be run
global : False: If True, this will set a global git config option

在 2015.8.0 版更改: Option renamed from is_global to global. For earlier versions, use is_global.

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, **kwargs)¶

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)

注解

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 mutliple 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.
all : False: 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: Optional name of a user as whom git config will be run
global : False: If True, this will set a global git config option

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, ref, target=None, remote='origin', user=None, force_clone=False, force_checkout=False, fetch_remote=True, hard_reset=False, submodules=False, identity=None, https_user=None, https_pass=None, onlyif=False, unless=False, **kwargs)¶

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

name: Address of the remote repository.
ref: 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.
remote : origin: 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.
force_clone : False: 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_checkout : False: 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_remote : True: If False a fetch will not be performed and only local refs will be reachable.
hard_reset : False: 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.

注解

Changes resulting from a hard reset will not trigger requisites.
submodules : False: Update submodules
identity: A path on the minion server to a private key to use over SSH Key can be specified as a SaltStack file server URL eg. salt://location/identity_file
https_user: HTTP Basic Auth username for HTTPS (only) clones
https_pass: HTTP Basic Auth password for HTTPS (only) clones
onlyif: 一个用于检查的命令，仅当``onlyif``选项指向的命令返回true时才执行name定义的命令
unless: 用于检查的命令，仅当``unless``选项指向的命令返回false时才执行name指向的命令

salt.states.git.latest(name, rev='HEAD', target=None, branch=None, user=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, depth=None, identity=None, https_user=None, https_pass=None, onlyif=False, unless=False, **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"

rev : HEAD

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.

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

注解

If not specified, this means that the local branch name will not be changed if the repository is reset to another branch/tag/SHA1.

2015.8.0 新版功能.

user

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

0.17.0 新版功能.

update_head : True

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.

2015.8.3 新版功能.

force : False

2015.8.0 版后已移除: Use force_clone instead. For earlier Salt versions, force must be used.

force_checkout : False

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_clone : False

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_fetch : False

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.

2015.8.0 新版功能.

force_reset : False

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.

submodules : False

Update submodules on clone or branch change

bare : False

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.

remote : origin

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.

remote_name

2015.8.0 版后已移除: Use remote instead. For earlier Salt versions, remote_name must be used.

fetch_tags : True

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.

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. This is not compatible with tags or revision IDs.

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.

警告

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.

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

Key can be specified as a SaltStack file server URL, eg. salt://location/identity_file

2016.3.0 新版功能.

https_user

HTTP Basic Auth username for HTTPS (only) clones

2015.5.0 新版功能.

https_pass

HTTP Basic Auth password for HTTPS (only) clones

2015.5.0 新版功能.

onlyif

一个用于检查的命令，仅当``onlyif``选项指向的命令返回true时才执行name定义的命令

unless

用于检查的命令，仅当``unless``选项指向的命令返回false时才执行name指向的命令

注解

Clashing ID declarations can be avoided when including different branches from the same git repository in the same sls file by using the name declaration. 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: ssh://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: ssh://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

    .. versionadded:: 2016.3.0

git-website-prod:
  git.latest:
    - name: ssh://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.mod_run_check(cmd_kwargs, onlyif, unless)¶

Execute the onlyif and unless logic. Return a result dict if:

onlyif failed (onlyif != 0)
unless succeeded (unless == 0)

Otherwise, returns True

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

Ensure that a repository exists in the given directory

警告

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

在 2015.8.0 版更改: This path must now be absolute
force : False: 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.
bare : True: If True, and a repository must be initialized, then the repository will be a bare repository.

注解

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`_

2015.8.0 新版功能.
separate_git_dir: If a new repository is initialized, this argument will specify an alternate $GIT_DIR

2015.8.0 新版功能.
shared: Set sharing permissions on git repo. See git-init(1) for more details.

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.

0.17.0 新版功能.