salt.modules.git

Support for the Git SCM

salt.modules.git.add(cwd, filename, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

Changed in version 2015.8.0: The --verbose command line argument is now implied

Interface to git-add(1)

cwd
The path to the git checkout
filename
The location of the file/directory to add, relative to cwd
opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the add subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.add /path/to/repo foo/bar.py
salt myminion git.add /path/to/repo foo/bar.py opts='--dry-run'
salt.modules.git.archive(cwd, output, rev='HEAD', prefix=None, git_opts='', user=None, password=None, ignore_retcode=False, **kwargs)

Changed in version 2015.8.0: Returns True if successful, raises an error if not.

Interface to git-archive(1), exports a tarball/zip file of the repository

cwd

The path to be archived

Note

git archive permits a partial archive to be created. Thus, this path does not need to be the root of the git repository. Only the files within the directory specified by cwd (and its subdirectories) will be in the resulting archive. For example, if there is a git checkout at /tmp/foo, then passing /tmp/foo/bar as the cwd will result in just the files underneath /tmp/foo/bar to be exported as an archive.

output
The path of the archive to be created
overwrite
: False

Unless set to True, Salt will over overwrite an existing archive at the path specified by the output argument.

New in version 2015.8.0.

rev
: HEAD
The revision from which to create the archive
format

Manually specify the file format of the resulting archive. This argument can be omitted, and git archive will attempt to guess the archive type (and compression) from the filename. zip, tar, tar.gz, and tgz are extensions that are recognized automatically, and git can be configured to support other archive types with the addition of git configuration keys.

See the git-archive(1) manpage explanation of the --format argument (as well as the CONFIGURATION section of the manpage) for further information.

New in version 2015.8.0.

prefix

Prepend <prefix> to every filename in the archive. If unspecified, the name of the directory at the top level of the repository will be used as the prefix (e.g. if cwd is set to /foo/bar/baz, the prefix will be baz, and the resulting archive will contain a top-level directory by that name).

Note

The default behavior if the --prefix option for git archive is not specified is to not prepend a prefix, so Salt's behavior differs slightly from git archive in this respect. Use prefix='' to create an archive with no prefix.

Changed in version 2015.8.0: The behavior of this argument has been changed slightly. As of this version, it is necessary to include the trailing slash when specifying a prefix, if the prefix is intended to create a top-level directory.

git_opts

Any additional options to add to git command itself (not the archive subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Example:

salt myminion git.archive /path/to/repo /path/to/archive.tar
salt.modules.git.branch(cwd, name=None, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

Interface to git-branch(1)

cwd
The path to the git checkout
name
Name of the branch on which to operate. If not specified, the current branch will be assumed.
opts

Any additional options to add to the command line, in a single string

Note

To create a branch based on something other than HEAD, pass the name of the revision as opts. If the revision is in the format remotename/branch, then this will also set the remote tracking branch.

Additionally, on the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the branch subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

# Set remote tracking branch
salt myminion git.branch /path/to/repo mybranch opts='--set-upstream-to origin/mybranch'
# Create new branch
salt myminion git.branch /path/to/repo mybranch upstream/somebranch
# Delete branch
salt myminion git.branch /path/to/repo mybranch opts='-d'
# Rename branch (2015.8.0 and later)
salt myminion git.branch /path/to/repo newbranch opts='-m oldbranch'
salt.modules.git.checkout(cwd, rev=None, force=False, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

Interface to git-checkout(1)

cwd
The path to the git checkout
opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the checkout subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

rev

The remote branch or revision to checkout.

Changed in version 2015.8.0: Optional when using -b or -B in opts.

force
: False
Force a checkout even if there might be overwritten changes
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

# Checking out local local revisions
salt myminion git.checkout /path/to/repo somebranch user=jeff
salt myminion git.checkout /path/to/repo opts='testbranch -- conf/file1 file2'
salt myminion git.checkout /path/to/repo rev=origin/mybranch opts='--track'
# Checking out remote revision into new branch
salt myminion git.checkout /path/to/repo upstream/master opts='-b newbranch'
# Checking out current revision into new branch (2015.8.0 and later)
salt myminion git.checkout /path/to/repo opts='-b newbranch'
salt.modules.git.clone(cwd, url=None, name=None, opts='', git_opts='', user=None, password=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False, saltenv='base')

Interface to git-clone(1)

cwd

Location of git clone

Changed in version 2015.8.0: If name is passed, then the clone will be made within this directory.

url

The URL of the repository to be cloned

Changed in version 2015.8.0: Argument renamed from repository to url

name

Optional alternate name for the top-level directory to be created by the clone

New in version 2015.8.0.

opts
Any additional options to add to the command line, in a single string
git_opts

Any additional options to add to git command itself (not the clone subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

identity

Path to a private key to use for ssh URLs

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.

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

Changed in version 2016.3.0.

https_user

Set HTTP Basic Auth username. Only accepted for HTTPS URLs.

New in version 20515.5.0.

https_pass

Set HTTP Basic Auth password. Only accepted for HTTPS URLs.

New in version 2015.5.0.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

saltenv

The default salt environment to pull sls files from

New in version 2016.3.1.

CLI Example:

salt myminion git.clone /path/to/repo_parent_dir git://github.com/saltstack/salt.git
salt.modules.git.commit(cwd, message, opts='', git_opts='', user=None, password=None, filename=None, ignore_retcode=False)

Interface to git-commit(1)

cwd
The path to the git checkout
message
Commit message
opts

Any additional options to add to the command line, in a single string. These opts will be added to the end of the git command being run.

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

The -m option should not be passed here, as the commit message will be defined by the message argument.

git_opts

Any additional options to add to git command itself (not the commit subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

filename

The location of the file/directory to commit, relative to cwd. This argument is optional, and can be used to commit a file without first staging it.

Note

This argument only works on files which are already tracked by the git repository.

New in version 2015.8.0.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.commit /path/to/repo 'The commit message'
salt myminion git.commit /path/to/repo 'The commit message' filename=foo/bar.py
salt.modules.git.config_get(key, cwd=None, user=None, password=None, ignore_retcode=False, **kwargs)

Get the value of a key in the git configuration file

key

The name of the configuration key to get

Changed in version 2015.8.0: Argument renamed from setting_name to key

cwd

The path to the git checkout

Changed in version 2015.8.0: Now optional if global is set to True

global
: False

If True, query the global git configuration. Otherwise, only the local git configuration will be queried.

New in version 2015.8.0.

all
: False

If True, return a list of all values set for key. If the key does not exist, None will be returned.

New in version 2015.8.0.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.config_get user.name cwd=/path/to/repo
salt myminion git.config_get user.email global=True
salt myminion git.config_get core.gitproxy cwd=/path/to/repo all=True
salt.modules.git.config_get_regexp(key, value_regex=None, cwd=None, user=None, password=None, ignore_retcode=False, **kwargs)

New in version 2015.8.0.

Get the value of a key or keys in the git configuration file using regexes for more flexible matching. The return data is a dictionary mapping keys to lists of values matching the value_regex. If no values match, an empty dictionary will be returned.

key
Regex on which key names will be matched
value_regex

If specified, return all values matching this regex. The return data will be a dictionary mapping keys to lists of values matching the regex.

Important

Only values matching the value_regex will be part of the return data. So, if key matches a multivar, then it is possible that not all of the values will be returned. To get all values set for a multivar, simply omit the value_regex argument.

cwd
The path to the git checkout
global
: False
If True, query the global git configuration. Otherwise, only the local git configuration will be queried.
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False
If True, do not log an error to the minion log if the git command returns a nonzero exit status.

CLI Examples:

# Matches any values for key 'foo.bar'
salt myminion git.config_get_regexp /path/to/repo foo.bar
# Matches any value starting with 'baz' set for key 'foo.bar'
salt myminion git.config_get_regexp /path/to/repo foo.bar 'baz.*'
# Matches any key starting with 'user.'
salt myminion git.config_get_regexp '^user\.' global=True
salt.modules.git.config_set(key, value=None, multivar=None, cwd=None, user=None, password=None, ignore_retcode=False, **kwargs)

Changed in version 2015.8.0: Return the value(s) of the key being set

Set a key in the git configuration file

cwd

The path to the git checkout. Must be an absolute path, or the word global to indicate that a global key should be set.

Changed in version 2014.7.0: Made cwd argument optional if is_global=True

key

The name of the configuration key to set

Changed in version 2015.8.0: Argument renamed from setting_name to key

value

The value to set for the specified key. Incompatible with the multivar argument.

Changed in version 2015.8.0: Argument renamed from setting_value to value

add
: False

Add a value to a key, creating/updating a multivar

New in version 2015.8.0.

multivar

Set a multivar all at once. Values can be comma-separated or passed as a Python list. Incompatible with the value argument.

New in version 2015.8.0.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

global
: False
If True, set a global variable

CLI Example:

salt myminion git.config_set user.email me@example.com cwd=/path/to/repo
salt myminion git.config_set user.email foo@bar.com global=True
salt.modules.git.config_unset(key, value_regex=None, cwd=None, user=None, password=None, ignore_retcode=False, **kwargs)

New in version 2015.8.0.

Unset a key in the git configuration file

cwd
The path to the git checkout. Must be an absolute path, or the word global to indicate that a global key should be unset.
key
The name of the configuration key to unset
value_regex
Regular expression that matches exactly one key, used to delete a single value from a multivar. Ignored if all is set to True.
all
: False
If True unset all values for a multivar. If False, and key is a multivar, an error will be raised.
global
: False
If True, unset set a global variable. Otherwise, a local variable will be unset.
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False
If True, do not log an error to the minion log if the git command returns a nonzero exit status.

CLI Example:

salt myminion git.config_unset /path/to/repo foo.bar
salt myminion git.config_unset /path/to/repo foo.bar all=True
salt.modules.git.current_branch(cwd, user=None, password=None, ignore_retcode=False)

Returns the current branch name of a local checkout. If HEAD is detached, return the SHA1 of the revision which is currently checked out.

cwd
The path to the git checkout
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Example:

salt myminion git.current_branch /path/to/repo
salt.modules.git.describe(cwd, rev='HEAD', user=None, password=None, ignore_retcode=False)

Returns the git-describe(1) string (or the SHA1 hash if there are no tags) for the given revision.

cwd
The path to the git checkout
rev
: HEAD
The revision to describe
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.describe /path/to/repo
salt myminion git.describe /path/to/repo develop
salt.modules.git.diff(cwd, item1=None, item2=None, opts='', git_opts='', user=None, password=None, no_index=False, cached=False, paths=None)

New in version 2015.8.12,2016.3.3,2016.11.0.

Interface to git-diff(1)

cwd
The path to the git checkout
item1 and item2
Revision(s) to pass to the git diff command. One or both of these arguments may be ignored if some of the options below are set to True. When cached is False, and no revisions are passed to this function, then the current working tree will be compared against the index (i.e. unstaged changes). When two revisions are passed, they will be compared to each other.
opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the diff subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

no_index
: False

When it is necessary to diff two files in the same repo against each other, and not diff two different revisions, set this option to True. If this is left False in these instances, then a normal git diff will be performed against the index (i.e. unstaged changes), and files in the paths option will be used to narrow down the diff output.

Note

Requires Git 1.5.1 or newer. Additionally, when set to True, item1 and item2 will be ignored.

cached
: False

If True, compare staged changes to item1 (if specified), otherwise compare them to the most recent commit.

Note

item2 is ignored if this option is is set to True.

paths
File paths to pass to the git diff command. Can be passed as a comma-separated list or a Python list.

CLI Example:

# Perform diff against the index (staging area for next commit)
salt myminion git.diff /path/to/repo
# Compare staged changes to the most recent commit
salt myminion git.diff /path/to/repo cached=True
# Compare staged changes to a specific revision
salt myminion git.diff /path/to/repo mybranch cached=True
# Perform diff against the most recent commit (includes staged changes)
salt myminion git.diff /path/to/repo HEAD
# Diff two commits
salt myminion git.diff /path/to/repo abcdef1 aabbccd
# Diff two commits, only showing differences in the specified paths
salt myminion git.diff /path/to/repo abcdef1 aabbccd paths=path/to/file1,path/to/file2
# Diff two files with one being outside the working tree
salt myminion git.diff /path/to/repo no_index=True paths=path/to/file1,/absolute/path/to/file2
salt.modules.git.fetch(cwd, remote=None, force=False, refspecs=None, opts='', git_opts='', user=None, password=None, identity=None, ignore_retcode=False, saltenv='base')

Changed in version 2015.8.2: Return data is now a dictionary containing information on branches and tags that were added/updated

Interface to git-fetch(1)

cwd
The path to the git checkout
remote

Optional remote name to fetch. If not passed, then git will use its default behavior (as detailed in git-fetch(1)).

New in version 2015.8.0.

force

Force the fetch even when it is not a fast-forward.

New in version 2015.8.0.

refspecs

Override the refspec(s) configured for the remote with this argument. Multiple refspecs can be passed, comma-separated.

New in version 2015.8.0.

opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the fetch subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

identity

Path to a private key to use for ssh URLs

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.

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

Changed in version 2016.3.0.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

saltenv

The default salt environment to pull sls files from

New in version 2016.3.1.

CLI Example:

salt myminion git.fetch /path/to/repo upstream
salt myminion git.fetch /path/to/repo identity=/root/.ssh/id_rsa
salt.modules.git.init(cwd, bare=False, template=None, separate_git_dir=None, shared=None, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

Interface to git-init(1)

cwd
The path to the directory to be initialized
bare
: False

If True, init a bare repository

New in version 2015.8.0.

template

Set this argument to specify an alternate template directory

New in version 2015.8.0.

separate_git_dir

Set this argument to specify an alternate $GIT_DIR

New in version 2015.8.0.

shared

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

New in version 2015.8.0.

opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the init subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.init /path/to/repo
# Init a bare repo (before 2015.8.0)
salt myminion git.init /path/to/bare/repo.git opts='--bare'
# Init a bare repo (2015.8.0 and later)
salt myminion git.init /path/to/bare/repo.git bare=True
salt.modules.git.is_worktree(cwd, user=None, password=None)

New in version 2015.8.0.

This function will attempt to determine if cwd is part of a worktree by checking its .git to see if it is a file containing a reference to another gitdir.

cwd
path to the worktree to be removed
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

CLI Example:

salt myminion git.is_worktree /path/to/repo
salt.modules.git.list_branches(cwd, remote=False, user=None, password=None, ignore_retcode=False)

New in version 2015.8.0.

Return a list of branches

cwd
The path to the git checkout
remote
: False

If True, list remote branches. Otherwise, local branches will be listed.

Warning

This option will only return remote branches of which the local checkout is aware, use git.fetch to update remotes.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.list_branches /path/to/repo
salt myminion git.list_branches /path/to/repo remote=True
salt.modules.git.list_tags(cwd, user=None, password=None, ignore_retcode=False)

New in version 2015.8.0.

Return a list of tags

cwd
The path to the git checkout
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.list_tags /path/to/repo
salt.modules.git.list_worktrees(cwd, stale=False, user=None, password=None, **kwargs)

New in version 2015.8.0.

Returns information on worktrees

Changed in version 2015.8.4: Version 2.7.0 added the list subcommand to git-worktree(1) which provides a lot of additional information. The return data has been changed to include this information, even for pre-2.7.0 versions of git. In addition, if a worktree has a detached head, then any tags which point to the worktree's HEAD will be included in the return data.

Note

By default, only worktrees for which the worktree directory is still present are returned, but this can be changed using the all and stale arguments (described below).

cwd
The path to the git checkout
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

all
: False
If True, then return all worktrees tracked under $GIT_DIR/worktrees, including ones for which the gitdir is no longer present.
stale
: False
If True, return only worktrees whose gitdir is no longer present.

Note

Only one of all and stale can be set to True.

CLI Examples:

salt myminion git.list_worktrees /path/to/repo
salt myminion git.list_worktrees /path/to/repo all=True
salt myminion git.list_worktrees /path/to/repo stale=True
salt.modules.git.ls_remote(cwd=None, remote='origin', ref=None, opts='', git_opts='', user=None, password=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False, saltenv='base')

Interface to git-ls-remote(1). Returns the upstream hash for a remote reference.

cwd
The path to the git checkout. Optional (and ignored if present) when remote is set to a URL instead of a remote name.
remote
: origin

The name of the remote to query. Can be the name of a git remote (which exists in the git checkout defined by the cwd parameter), or the URL of a remote repository.

Changed in version 2015.8.0: Argument renamed from repository to remote

ref

The name of the ref to query. Optional, if not specified, all refs are returned. Can be a branch or tag name, or the full name of the reference (for example, to get the hash for a Github pull request number 1234, ref can be set to refs/pull/1234/head

Changed in version 2015.8.0: Argument renamed from branch to ref

Changed in version 2015.8.4: Defaults to returning all refs instead of master.

opts

Any additional options to add to the command line, in a single string

New in version 2015.8.0.

git_opts

Any additional options to add to git command itself (not the ls-remote subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

identity

Path to a private key to use for ssh URLs

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.

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

Changed in version 2016.3.0.

https_user

Set HTTP Basic Auth username. Only accepted for HTTPS URLs.

New in version 2015.5.0.

https_pass

Set HTTP Basic Auth password. Only accepted for HTTPS URLs.

New in version 2015.5.0.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

saltenv

The default salt environment to pull sls files from

New in version 2016.3.1.

CLI Example:

salt myminion git.ls_remote /path/to/repo origin master
salt myminion git.ls_remote remote=https://mydomain.tld/repo.git ref=mytag opts='--tags'
salt.modules.git.merge(cwd, rev=None, opts='', git_opts='', user=None, password=None, ignore_retcode=False, **kwargs)

Interface to git-merge(1)

cwd
The path to the git checkout
rev

Revision to merge into the current branch. If not specified, the remote tracking branch will be merged.

New in version 2015.8.0.

opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the merge subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Example:

# Fetch first...
salt myminion git.fetch /path/to/repo
# ... then merge the remote tracking branch
salt myminion git.merge /path/to/repo
# .. or merge another rev
salt myminion git.merge /path/to/repo rev=upstream/foo
salt.modules.git.merge_base(cwd, refs=None, octopus=False, is_ancestor=False, independent=False, fork_point=None, opts='', git_opts='', user=None, password=None, ignore_retcode=False, **kwargs)

New in version 2015.8.0.

Interface to git-merge-base(1).

cwd
The path to the git checkout
refs
Any refs/commits to check for a merge base. Can be passed as a comma-separated list or a Python list.
all
: False
Return a list of all matching merge bases. Not compatible with any of the below options except for octopus.
octopus
: False

If True, then this function will determine the best common ancestors of all specified commits, in preparation for an n-way merge. See here for a description of how these bases are determined.

Set all to True with this option to return all computed merge bases, otherwise only the "best" will be returned.

is_ancestor
: False

If True, then instead of returning the merge base, return a boolean telling whether or not the first commit is an ancestor of the second commit.

Note

This option requires two commits to be passed.

Changed in version 2015.8.2: Works properly in git versions older than 1.8.0, where the --is-ancestor CLI option is not present.

independent
: False
If True, this function will return the IDs of the refs/commits passed which cannot be reached by another commit.
fork_point

If passed, then this function will return the commit where the commit diverged from the ref specified by fork_point. If no fork point is found, None is returned.

Note

At most one commit is permitted to be passed if a fork_point is specified. If no commits are passed, then HEAD is assumed.

opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

This option should not be necessary unless new CLI arguments are added to git-merge-base(1) and are not yet supported in Salt.

git_opts

Any additional options to add to git command itself (not the merge-base subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False
if True, do not log an error to the minion log if the git command returns a nonzero exit status.

CLI Examples:

salt myminion git.merge_base /path/to/repo HEAD upstream/mybranch
salt myminion git.merge_base /path/to/repo 8f2e542,4ad8cab,cdc9886 octopus=True
salt myminion git.merge_base /path/to/repo refs=8f2e542,4ad8cab,cdc9886 independent=True
salt myminion git.merge_base /path/to/repo refs=8f2e542,4ad8cab is_ancestor=True
salt myminion git.merge_base /path/to/repo fork_point=upstream/master
salt myminion git.merge_base /path/to/repo refs=mybranch fork_point=upstream/master
salt.modules.git.merge_tree(cwd, ref1, ref2, base=None, user=None, password=None, ignore_retcode=False)

New in version 2015.8.0.

Interface to git-merge-tree(1), shows the merge results and conflicts from a 3-way merge without touching the index.

cwd
The path to the git checkout
ref1
First ref/commit to compare
ref2
Second ref/commit to compare
base
The base tree to use for the 3-way-merge. If not provided, then git.merge_base will be invoked on ref1 and ref2 to determine the merge base to use.
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False
if True, do not log an error to the minion log if the git command returns a nonzero exit status.

CLI Examples:

salt myminion git.merge_tree /path/to/repo HEAD upstream/dev
salt myminion git.merge_tree /path/to/repo HEAD upstream/dev base=aaf3c3d
salt.modules.git.pull(cwd, opts='', git_opts='', user=None, password=None, identity=None, ignore_retcode=False, saltenv='base')

Interface to git-pull(1)

cwd
The path to the git checkout
opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the pull subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

identity

Path to a private key to use for ssh URLs

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.

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

Changed in version 2016.3.0.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

saltenv

The default salt environment to pull sls files from

New in version 2016.3.1.

CLI Example:

salt myminion git.pull /path/to/repo opts='--rebase origin master'
salt.modules.git.push(cwd, remote=None, ref=None, opts='', git_opts='', user=None, password=None, identity=None, ignore_retcode=False, saltenv='base', **kwargs)

Interface to git-push(1)

cwd
The path to the git checkout
remote

Name of the remote to which the ref should being pushed

New in version 2015.8.0.

ref
: master

Name of the ref to push

Note

Being a refspec, this argument can include a colon to define local and remote ref names.

opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the push subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

identity

Path to a private key to use for ssh URLs

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.

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

Changed in version 2016.3.0.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

saltenv

The default salt environment to pull sls files from

New in version 2016.3.1.

CLI Example:

# Push master as origin/master
salt myminion git.push /path/to/repo origin master
# Push issue21 as upstream/develop
salt myminion git.push /path/to/repo upstream issue21:develop
# Delete remote branch 'upstream/temp'
salt myminion git.push /path/to/repo upstream :temp
salt.modules.git.rebase(cwd, rev='master', opts='', git_opts='', user=None, password=None, ignore_retcode=False)

Interface to git-rebase(1)

cwd
The path to the git checkout
rev
: master
The revision to rebase onto the current branch
opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the rebase subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Example:

salt myminion git.rebase /path/to/repo master
salt myminion git.rebase /path/to/repo 'origin master'
salt myminion git.rebase /path/to/repo origin/master opts='--onto newbranch'
salt.modules.git.remote_get(cwd, remote='origin', user=None, password=None, redact_auth=True, ignore_retcode=False)

Get the fetch and push URL for a specific remote

cwd
The path to the git checkout
remote
: origin
Name of the remote to query
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

redact_auth
: True

Set to False to include the username/password if the remote uses HTTPS Basic Auth. Otherwise, this information will be redacted.

Warning

Setting this to False will not only reveal any HTTPS Basic Auth that is configured, but the return data will also be written to the job cache. When possible, it is recommended to use SSH for authentication.

New in version 2015.5.6.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.remote_get /path/to/repo
salt myminion git.remote_get /path/to/repo upstream
salt.modules.git.remote_refs(url, heads=False, tags=False, user=None, password=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False, saltenv='base')

New in version 2015.8.0.

Return the remote refs for the specified URL

url
URL of the remote repository
heads
: False
Restrict output to heads. Can be combined with tags.
tags
: False
Restrict output to tags. Can be combined with heads.
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

identity

Path to a private key to use for ssh URLs

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.

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

Changed in version 2016.3.0.

https_user
Set HTTP Basic Auth username. Only accepted for HTTPS URLs.
https_pass
Set HTTP Basic Auth password. Only accepted for HTTPS URLs.
ignore_retcode
: False
If True, do not log an error to the minion log if the git command returns a nonzero exit status.
saltenv

The default salt environment to pull sls files from

New in version 2016.3.1.

CLI Example:

salt myminion git.remote_refs https://github.com/saltstack/salt.git
salt.modules.git.remote_set(cwd, url, remote='origin', user=None, password=None, https_user=None, https_pass=None, push_url=None, push_https_user=None, push_https_pass=None, ignore_retcode=False)
cwd
The path to the git checkout
url
Remote URL to set
remote
: origin
Name of the remote to set
push_url

If unset, the push URL will be identical to the fetch URL.

New in version 2015.8.0.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

https_user

Set HTTP Basic Auth username. Only accepted for HTTPS URLs.

New in version 2015.5.0.

https_pass

Set HTTP Basic Auth password. Only accepted for HTTPS URLs.

New in version 2015.5.0.

push_https_user

Set HTTP Basic Auth user for push_url. Ignored if push_url is unset. Only accepted for HTTPS URLs.

New in version 2015.8.0.

push_https_pass

Set HTTP Basic Auth password for push_url. Ignored if push_url is unset. Only accepted for HTTPS URLs.

New in version 2015.8.0.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.remote_set /path/to/repo git@github.com:user/repo.git
salt myminion git.remote_set /path/to/repo git@github.com:user/repo.git remote=upstream
salt myminion git.remote_set /path/to/repo https://github.com/user/repo.git remote=upstream push_url=git@github.com:user/repo.git
salt.modules.git.remotes(cwd, user=None, password=None, redact_auth=True, ignore_retcode=False)

Get fetch and push URLs for each remote in a git checkout

cwd
The path to the git checkout
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

redact_auth
: True

Set to False to include the username/password for authenticated remotes in the return data. Otherwise, this information will be redacted.

Warning

Setting this to False will not only reveal any HTTPS Basic Auth that is configured, but the return data will also be written to the job cache. When possible, it is recommended to use SSH for authentication.

New in version 2015.5.6.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Example:

salt myminion git.remotes /path/to/repo
salt.modules.git.reset(cwd, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

Interface to git-reset(1), returns the stdout from the git command

cwd
The path to the git checkout
opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the reset subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

# Soft reset to a specific commit ID
salt myminion git.reset /path/to/repo ac3ee5c
# Hard reset
salt myminion git.reset /path/to/repo opts='--hard origin/master'
salt.modules.git.rev_parse(cwd, rev=None, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

New in version 2015.8.0.

Interface to git-rev-parse(1)

cwd
The path to the git checkout
rev

Revision to parse. See the SPECIFYING REVISIONS section of the git-rev-parse(1) manpage for details on how to format this argument.

This argument is optional when using the options in the Options for Files section of the git-rev-parse(1) manpage.

opts
Any additional options to add to the command line, in a single string
git_opts

Any additional options to add to git command itself (not the rev-parse subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False
If True, do not log an error to the minion log if the git command returns a nonzero exit status.

CLI Examples:

# Get the full SHA1 for HEAD
salt myminion git.rev_parse /path/to/repo HEAD
# Get the short SHA1 for HEAD
salt myminion git.rev_parse /path/to/repo HEAD opts='--short'
# Get the develop branch's upstream tracking branch
salt myminion git.rev_parse /path/to/repo 'develop@{upstream}' opts='--abbrev-ref'
# Get the SHA1 for the commit corresponding to tag v1.2.3
salt myminion git.rev_parse /path/to/repo 'v1.2.3^{commit}'
# Find out whether or not the repo at /path/to/repo is a bare repository
salt myminion git.rev_parse /path/to/repo opts='--is-bare-repository'
salt.modules.git.revision(cwd, rev='HEAD', short=False, user=None, password=None, ignore_retcode=False)

Returns the SHA1 hash of a given identifier (hash, branch, tag, HEAD, etc.)

cwd
The path to the git checkout
rev
: HEAD
The revision
short
: False
If True, return an abbreviated SHA1 git hash
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Example:

salt myminion git.revision /path/to/repo mybranch
salt.modules.git.rm(cwd, filename, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

Interface to git-rm(1)

cwd
The path to the git checkout
filename

The location of the file/directory to remove, relative to cwd

Note

To remove a directory, -r must be part of the opts parameter.

opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the rm subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.rm /path/to/repo foo/bar.py
salt myminion git.rm /path/to/repo foo/bar.py opts='--dry-run'
salt myminion git.rm /path/to/repo foo/baz opts='-r'
salt.modules.git.stash(cwd, action='save', opts='', git_opts='', user=None, password=None, ignore_retcode=False)

Interface to git-stash(1), returns the stdout from the git command

cwd
The path to the git checkout
opts
Any additional options to add to the command line, in a single string. Use this to complete the git stash command by adding the remaining arguments (i.e. 'save <stash comment>', 'apply stash@{2}', 'show', etc.). Omitting this argument will simply run git stash.
git_opts

Any additional options to add to git command itself (not the stash subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.stash /path/to/repo save opts='work in progress'
salt myminion git.stash /path/to/repo apply opts='stash@{1}'
salt myminion git.stash /path/to/repo drop opts='stash@{1}'
salt myminion git.stash /path/to/repo list
salt.modules.git.status(cwd, user=None, password=None, ignore_retcode=False)

Changed in version 2015.8.0: Return data has changed from a list of lists to a dictionary

Returns the changes to the repository

cwd
The path to the git checkout
user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Example:

salt myminion git.status /path/to/repo
salt.modules.git.submodule(cwd, command, opts='', git_opts='', user=None, password=None, identity=None, ignore_retcode=False, saltenv='base', **kwargs)

Changed in version 2015.8.0: Added the command argument to allow for operations other than update to be run on submodules, and deprecated the init argument. To do a submodule update with init=True moving forward, use command=update opts='--init'

Interface to git-submodule(1)

cwd
The path to the submodule
command

Submodule command to run, see git-submodule(1) <git submodule> for more information. Any additional arguments after the command (such as the URL when adding a submodule) must be passed in the opts parameter.

New in version 2015.8.0.

opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= (as in the CLI examples below) to avoid causing errors with Salt's own argument parsing.

git_opts

Any additional options to add to git command itself (not the submodule subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

init
: False

If True, ensures that new submodules are initialized

Deprecated since version 2015.8.0: Pass init as the command parameter, or include --init in the opts param with command set to update.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

identity

Path to a private key to use for ssh URLs

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.

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

Changed in version 2016.3.0.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

saltenv

The default salt environment to pull sls files from

New in version 2016.3.1.

CLI Example:

# Update submodule and ensure it is initialized (before 2015.8.0)
salt myminion git.submodule /path/to/repo/sub/repo init=True
# Update submodule and ensure it is initialized (2015.8.0 and later)
salt myminion git.submodule /path/to/repo/sub/repo update opts='--init'

# Rebase submodule (2015.8.0 and later)
salt myminion git.submodule /path/to/repo/sub/repo update opts='--rebase'

# Add submodule (2015.8.0 and later)
salt myminion git.submodule /path/to/repo/sub/repo add opts='https://mydomain.tld/repo.git'

# Unregister submodule (2015.8.0 and later)
salt myminion git.submodule /path/to/repo/sub/repo deinit
salt.modules.git.symbolic_ref(cwd, ref, value=None, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

New in version 2015.8.0.

Interface to git-symbolic-ref(1)

cwd
The path to the git checkout
ref
Symbolic ref to read/modify
value

If passed, then the symbolic ref will be set to this value and an empty string will be returned.

If not passed, then the ref to which ref points will be returned, unless --delete is included in opts (in which case the symbolic ref will be deleted).

opts
Any additional options to add to the command line, in a single string
git_opts

Any additional options to add to git command itself (not the symbolic-refs subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

# Get ref to which HEAD is pointing
salt myminion git.symbolic_ref /path/to/repo HEAD
# Set/overwrite symbolic ref 'FOO' to local branch 'foo'
salt myminion git.symbolic_ref /path/to/repo FOO refs/heads/foo
# Delete symbolic ref 'FOO'
salt myminion git.symbolic_ref /path/to/repo FOO opts='--delete'
salt.modules.git.version(versioninfo=False)

New in version 2015.8.0.

Returns the version of Git installed on the minion

versioninfo
: False
If True, return the version in a versioninfo list (e.g. [2, 5, 0])

CLI Example:

salt myminion git.version
salt.modules.git.worktree_add(cwd, worktree_path, ref=None, reset_branch=None, force=None, detach=False, opts='', git_opts='', user=None, password=None, ignore_retcode=False, **kwargs)

New in version 2015.8.0.

Interface to git-worktree(1), adds a worktree

cwd
The path to the git checkout
worktree_path
Path to the new worktree. Can be either absolute, or relative to cwd.
branch
Name of new branch to create. If omitted, will be set to the basename of the worktree_path. For example, if the worktree_path is /foo/bar/baz, then branch will be baz.
ref
Name of the ref on which to base the new worktree. If omitted, then HEAD is use, and a new branch will be created, named for the basename of the worktree_path. For example, if the worktree_path is /foo/bar/baz then a new branch baz will be created, and pointed at HEAD.
reset_branch
: False
If False, then git-worktree(1) will fail to create the worktree if the targeted branch already exists. Set this argument to True to reset the targeted branch to point at ref, and checkout the newly-reset branch into the new worktree.
force
: False
By default, git-worktree(1) will not permit the same branch to be checked out in more than one worktree. Set this argument to True to override this.
opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= to avoid causing errors with Salt's own argument parsing.

All CLI options for adding worktrees as of Git 2.5.0 are already supported by this function as of Salt 2015.8.0, so using this argument is unnecessary unless new CLI arguments are added to git-worktree(1) and are not yet supported in Salt.

git_opts

Any additional options to add to git command itself (not the worktree subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.worktree_add /path/to/repo/main ../hotfix ref=origin/master
salt myminion git.worktree_add /path/to/repo/main ../hotfix branch=hotfix21 ref=v2.1.9.3
salt.modules.git.worktree_prune(cwd, dry_run=False, verbose=True, expire=None, opts='', git_opts='', user=None, password=None, ignore_retcode=False)

New in version 2015.8.0.

Interface to git-worktree(1), prunes stale worktree administrative data from the gitdir

cwd
The path to the main git checkout or a linked worktree
dry_run
: False
If True, then this function will report what would have been pruned, but no changes will be made.
verbose
: True
Report all changes made. Set to False to suppress this output.
expire
Only prune unused worktree data older than a specific period of time. The date format for this parameter is described in the documentation for the gc.pruneWorktreesExpire config param in the git-config(1) manpage.
opts

Any additional options to add to the command line, in a single string

Note

On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with opts= to avoid causing errors with Salt's own argument parsing.

All CLI options for pruning worktrees as of Git 2.5.0 are already supported by this function as of Salt 2015.8.0, so using this argument is unnecessary unless new CLI arguments are added to git-worktree(1) and are not yet supported in Salt.

git_opts

Any additional options to add to git command itself (not the worktree subcommand), in a single string. This is useful for passing -c to run git with temporary changes to the git configuration.

New in version 2017.7.0.

Note

This is only supported in git 1.7.2 and newer.

user
User under which to run the git command. By default, the command is 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.

New in version 2016.3.4.

ignore_retcode
: False

If True, do not log an error to the minion log if the git command returns a nonzero exit status.

New in version 2015.8.0.

CLI Examples:

salt myminion git.worktree_prune /path/to/repo
salt myminion git.worktree_prune /path/to/repo dry_run=True
salt myminion git.worktree_prune /path/to/repo expire=1.day.ago
salt.modules.git.worktree_rm(cwd, user=None)

New in version 2015.8.0.

Recursively removes the worktree located at cwd, returning True if successful. This function will attempt to determine if cwd is actually a worktree by invoking git.is_worktree. If the path does not correspond to a worktree, then an error will be raised and no action will be taken.

Warning

There is no undoing this action. Be VERY careful before running this function.

cwd
Path to the worktree to be removed
user
Used for path expansion when cwd is not an absolute path. By default, when cwd is not absolute, the path will be assumed to be relative to the home directory of the user under which the minion is running. Setting this option will change the home directory from which path expansion is performed.

CLI Examples:

salt myminion git.worktree_rm /path/to/worktree