# salt.modules.git

Support for the Git SCM

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

  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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None, **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

  overwriteFalse

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

    Added in version 2015.8.0.

  revHEAD

    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.

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

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

  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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

  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.

    Added 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`.

  forceFalse

    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.

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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', output_encoding=None)

  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

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

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

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

    Added in version 2015.5.0.

  https_pass

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

    Added in version 2015.5.0.

  ignore_retcodeFalse

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

    Added in version 2015.8.0.

  saltenv

    The default salt environment to pull sls files from

    Added in version 2016.3.1.

  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.

  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, output_encoding=None)

  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.

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

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

    Added in version 2015.8.0.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None, **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`

  globalFalse

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

    Added in version 2015.8.0.

  allFalse

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

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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_regex(key, value_regex=None, cwd=None, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs)

  This function is an alias of `config_get_regexp`.

  > Added 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

  > globalFalse

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

  >   Added in version 2016.3.4.

  > ignore_retcodeFalse

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

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

  > 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_get_regexp(key, value_regex=None, cwd=None, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs)

  Added 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

  globalFalse

    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.

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

  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.

  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, output_encoding=None, **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`

  addFalse

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

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

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.0.

  globalFalse

    If `True`, set a global variable

  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.

  CLI Examples:

      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, output_encoding=None, **kwargs)

  Added 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`.

  allFalse

    If `True` unset all values for a multivar. If `False`, and `key` is a multivar, an error will be raised.

  globalFalse

    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.

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

  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.

  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, output_encoding=None)

  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.

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  CLI Example:

      salt myminion git.current_branch /path/to/repo

salt.modules.git.describe(cwd, rev='HEAD', user=None, password=None, ignore_retcode=False, output_encoding=None)

  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

  revHEAD

    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.

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

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

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

    Added in version 2016.3.4.

  no_indexFalse

    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.

  cachedFalse

    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.

  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.

  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.discard_local_changes(cwd, path='.', user=None, password=None, ignore_retcode=False, output_encoding=None)

  Added in version 2019.2.0.

  Runs a `git checkout -- <path>` from the directory specified by `cwd`.

  cwd

    The path to the git checkout

  path

    path relative to cwd (defaults to `.`)

  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.

  ignore_retcodeFalse

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

  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.

  CLI Example:

      salt myminion git.discard_local_changes /path/to/repo
      salt myminion git.discard_local_changes /path/to/repo path=foo

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', output_encoding=None)

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

    Added in version 2015.8.0.

  force

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

    Added in version 2015.8.0.

  refspecs

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

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

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

    Added 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_retcodeFalse

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

    Added in version 2015.8.0.

  saltenv

    The default salt environment to pull sls files from

    Added in version 2016.3.1.

  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.

  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, output_encoding=None)

  Interface to git-init(1)

  cwd

    The path to the directory to be initialized

  bareFalse

    If `True`, init a bare repository

    Added in version 2015.8.0.

  template

    Set this argument to specify an alternate template directory

    Added in version 2015.8.0.

  separate_git_dir

    Set this argument to 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.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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

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

    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.

  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, output_encoding=None)

  Added in version 2015.8.0.

  Return a list of branches

  cwd

    The path to the git checkout

  remoteFalse

    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.

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  CLI Examples:

      salt myminion git.list_tags /path/to/repo

salt.modules.git.list_worktrees(cwd, stale=False, user=None, password=None, output_encoding=None, **kwargs)

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

    Added in version 2016.3.4.

  allFalse

    If `True`, then return all worktrees tracked under $GIT_DIR/worktrees, including ones for which the gitdir is no longer present.

  staleFalse

    If `True`, return only worktrees whose gitdir is no longer present.

  Note

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

  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.

  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, output_encoding=None, 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.

  remoteorigin

    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

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

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

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

    Added in version 2015.5.0.

  https_pass

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

    Added in version 2015.5.0.

  ignore_retcodeFalse

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

    Added in version 2015.8.0.

  saltenv

    The default salt environment to pull sls files from

    Added in version 2016.3.1.

  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.

  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, identity=None, ignore_retcode=False, output_encoding=None, **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.

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

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

    Added in version 2016.3.4.

  identity

    Path to a private key to use for ssh URLs. Salt will not 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`.

    Note

    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.

    Added in version 2018.3.5,2019.2.1,3000.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None, **kwargs)

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

  allFalse

    Return a list of all matching merge bases. Not compatible with any of the below options except for `octopus`.

  octopusFalse

    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_ancestorFalse

    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.

  independentFalse

    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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

  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.

  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, output_encoding=None)

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

  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.

  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', output_encoding=None)

  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.

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

    Added 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_retcodeFalse

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

    Added in version 2015.8.0.

  saltenv

    The default salt environment to pull sls files from

    Added in version 2016.3.1.

  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.

  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', output_encoding=None, **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

    Added in version 2015.8.0.

  refmaster

    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.

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

    Added 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_retcodeFalse

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

    Added in version 2015.8.0.

  saltenv

    The default salt environment to pull sls files from

    Added in version 2016.3.1.

  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.

  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, output_encoding=None)

  Interface to git-rebase(1)

  cwd

    The path to the git checkout

  revmaster

    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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

  Get the fetch and push URL for a specific remote

  cwd

    The path to the git checkout

  remoteorigin

    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.

    Added in version 2016.3.4.

  redact_authTrue

    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.

    Added in version 2015.5.6.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None, saltenv='base', **kwargs)

  Added in version 2015.8.0.

  Return the remote refs for the specified URL by running `git ls-remote`.

  url

    URL of the remote repository

  filter

    Optionally provide a ref name to `git ls-remote`. This can be useful to make this function run faster on repositories with many branches/tags.

    Added in version 2019.2.0.

  headsFalse

    Restrict output to heads. Can be combined with `tags`.

  tagsFalse

    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.

    Added 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_retcodeFalse

    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

    Added in version 2016.3.1.

  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.

  CLI Example:

      salt myminion git.remote_refs https://github.com/saltstack/salt.git
      salt myminion git.remote_refs https://github.com/saltstack/salt.git filter=develop

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, output_encoding=None)
  cwd

    The path to the git checkout

  url

    Remote URL to set

  remoteorigin

    Name of the remote to set

  push_url

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

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

    Added in version 2016.3.4.

  https_user

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

    Added in version 2015.5.0.

  https_pass

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

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

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

    Added in version 2015.8.0.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

  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.

    Added in version 2016.3.4.

  redact_authTrue

    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.

    Added in version 2015.5.6.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  CLI Example:

      salt myminion git.remotes /path/to/repo

salt.modules.git.reset(cwd, opts='', git_opts='', user=None, password=None, identity=None, ignore_retcode=False, output_encoding=None)

  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.

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

    Added in version 2016.3.4.

  identity

    Path to a private key to use for ssh URLs. Salt will not 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`.

    Note

    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.

    Added in version 2018.3.5,2019.2.1,3000.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

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

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

  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.

  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, output_encoding=None)

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

  cwd

    The path to the git checkout

  revHEAD

    The revision

  shortFalse

    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.

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

  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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

  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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

  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.

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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', output_encoding=None, **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.

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

    Added in version 2017.7.0.

    Note

    This is only supported in git 1.7.2 and newer.

  initFalse

    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.

    Added 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_retcodeFalse

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

    Added in version 2015.8.0.

  saltenv

    The default salt environment to pull sls files from

    Added in version 2016.3.1.

  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.

  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, output_encoding=None)

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

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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.tag(cwd, name, ref='HEAD', message=None, opts='', git_opts='', user=None, password=None, ignore_retcode=False, output_encoding=None)

  Added in version 2018.3.4.

  Interface to git-tag(1), adds and removes tags.

  cwd

    The path to the main git checkout or a linked worktree

  name

    Name of the tag

  refHEAD

    Which ref to tag (defaults to local clone's HEAD)

    Note

    This argument is ignored when either `-d` or `--delete` is present in the `opts` passed to this function.

  message

    Optional message to include with the tag. If provided, an annotated tag will be created.

  opts

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

    Note

    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 `worktree` subcommand), in a single string. This is useful for passing `-c` to run git with temporary changes to the git configuration.

    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.

  ignore_retcodeFalse

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

  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.

  CLI Example:

      # Create an non-annotated tag
      salt myminion git.tag /path/to/repo v1.2
      # Create an annotated tag
      salt myminion git.tag /path/to/repo v1.2 message='Version 1.2'
      # Delete the tag
      salt myminion git.tag /path/to/repo v1.2 opts='-d'

salt.modules.git.version(versioninfo=False)

  Added in version 2015.8.0.

  Returns the version of Git installed on the minion

  versioninfoFalse

    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, output_encoding=None, **kwargs)

  Added 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_branchFalse

    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.

  forceFalse

    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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

  Added 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_runFalse

    If `True`, then this function will report what would have been pruned, but no changes will be made.

  verboseTrue

    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.

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

    Added in version 2016.3.4.

  ignore_retcodeFalse

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

    Added in version 2015.8.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.

  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, output_encoding=None)

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

  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.

  CLI Examples:

      salt myminion git.worktree_rm /path/to/worktree