salt/doc/topics/releases/includes/git-2015.8.0.rst

.. _2015.8.0-git-:

=========================================
Git State and Execution Modules Rewritten
=========================================

The git state and execution modules have gone through an extensive overhaul.

Changes in the :py:func:`git.latest <salt.states.git.latest>` State
-------------------------------------------------------------------

- The ``branch`` argument has been added, allowing for a custom branch name to
  be used in the local checkout maintained by the :py:func:`git.latest
  <salt.states.git.latest>` state. This can be helpful in avoiding ambiguous
  refs in the local checkout when a tag is used as the ``rev`` argument. If no
  ``branch`` is specified, then the state uses the value of ``rev`` as the
  branch name.
- The ``always_fetch`` argument no longer has any effect, and will be removed
  in a future release. The state now detects whether or not a fetch is needed
  based on comparisons made between the local and remote repositories.
- The ``force_fetch`` argument has been added to force a fetch if the fetch is
  not a fast-forward (for instance, if someone has done a reset and
  force-pushed to the remote repository).
- The ``remote_name`` argument has been deprecated and renamed to ``remote``.
- The ``force`` argument has been deprecated and renamed to ``force_clone`` to
  reduce ambiguity with the other "force" arguments.
- Using SHA1 hashes (full or shortened) in the ``rev`` argument is now
  properly supported.
- Non-fast-forward merges are now detected before the repository is updated,
  and the state will not update the repository if the change is not a
  fast-forward. Non-fast-forward updates must be overridden with the
  ``force_reset`` argument. If ``force_reset`` is set to ``True``, the state
  will only reset the repository if it cannot be fast-forwarded. This is in
  contrast to the earlier behavior, in which a hard-reset would be performed
  every time the state was run if ``force_reset`` was set to ``True``.
- A ``git pull`` is no longer performed by this state, dropped in favor of a
  fetch-and-merge (or fetch-and-reset) workflow.

:py:func:`git.config_unset <salt.states.git.config_unset>` state added
----------------------------------------------------------------------

This state allows for configuration values (or entire keys) to be unset. See
:py:func:`here <salt.states.git.config_unset>` for more information and example
SLS.

git.config State Renamed to :py:func:`git.config_set <salt.states.git.config_set>`
----------------------------------------------------------------------------------

To reduce confusion after the addition of :py:func:`git.config_unset
<salt.states.git.config_unset>`, the git.config state has been renamed to
:py:func:`git.config_set <salt.states.git.config_set>`. The old config.get name
will still work for a couple releases, allowing time for SLS files to be
updated.

In addition, this state now supports managing multivar git configuration
values. See :py:func:`here <salt.states.git.config_set>` for more information
and example SLS.

Initial Support for Git Worktrees in Execution Module
-----------------------------------------------------

Several functions have been added to the execution module to manage worktrees_
(a feature new to Git 2.5.0). State support does not exist yet, but will follow
soon.

.. _worktrees: http://git-scm.com/docs/git-worktree

New Functions in Git Execution Module
-------------------------------------

- :py:func:`git.config_get_regexp <salt.modules.git.config_regexp>`
- :py:func:`git.config_unset <salt.modules.git.config_unset>`
- :py:func:`git.is_worktree <salt.modules.git.is_worktree>`
- :py:func:`git.list_branches <salt.modules.git.list_branches>`
- :py:func:`git.list_tags <salt.modules.git.list_tags>`
- :py:func:`git.list_worktrees <salt.modules.git.list_worktrees>`
- :py:func:`git.merge_base <salt.modules.git.merge_base>`
- :py:func:`git.merge_tree <salt.modules.git.merge_tree>`
- :py:func:`git.rev_parse <salt.modules.git.rev_parse>`
- :py:func:`git.version <salt.modules.git.version>`
- :py:func:`git.worktree_rm <salt.modules.git.worktree_rm>`
- :py:func:`git.worktree_add <salt.modules.git.worktree_add>`
- :py:func:`git.worktree_prune <salt.modules.git.worktree_prune>`

Changes to Functions in Git Execution Module
--------------------------------------------

:py:func:`git.add <salt.states.git.add>`
****************************************

- ``--verbose`` is now implied when running the ``git add`` command, to provide
  a list of the files added in the return data.

:py:func:`git.archive <salt.modules.git.archive>`
*************************************************

- Now returns ``True`` when the ``git archive`` command was successful, and
  otherwise raises an error.
- The ``overwrite`` argument has been added to prevent an existing archive from
  being overwritten by this function.
- The ``fmt`` argument has been deprecated and renamed to ``format``.
- Trailing slash no longer implied in ``prefix`` argument, must be included if
  this argument is passed.

:py:func:`git.checkout <salt.modules.git.checkout>`
***************************************************

- The ``rev`` argument is now optional when using ``-b`` or ``-B`` in ``opts``,
  allowing for a branch to be created (or reset) using ``HEAD`` as the starting
  point.

:py:func:`git.clone <salt.modules.git.clone>`
*********************************************

- The ``name`` argument has been added to specify the name of the directory in
  which to clone the repository. If this option is specified, then the clone
  will be made within the directory specified by the ``cwd``, instead of at
  that location.
- The ``repository`` argument has been deprecated and renamed to ``url``.

:py:func:`git.config_get <salt.modules.git.config_get>`
*******************************************************

- The ``setting_name`` argument has been deprecated and renamed to ``key``.
- The ``global`` argument has been added, to query the global git configuration
- The ``all`` argument has been added to return a list of all values for the
  specified key, allowing for all values in a multivar to be returned.
- The ``cwd`` argument is now optional if ``global`` is set to ``True``

:py:func:`git.config_set <salt.modules.git.config_set>`
*******************************************************

- The value(s) of the key being set are now returned
- The ``setting_name`` argument has been deprecated and renamed to ``key``.
- The ``setting_value`` argument has been deprecated and renamed to ``value``.
- The ``is_global`` argument has been deprecated and renamed to ``global``.
- The ``multivar`` argument has been added to specify a list of values to set
  for the specified key. The ``value`` argument is not compatible with
  ``multivar``.
- The ``add`` argument has been added to add a value to a key (this essentially
  just adds an ``--add`` to the ``git config`` command that is run to set the
  value).

:py:func:`git.fetch <salt.modules.git.fetch>`
*********************************************

- The ``force`` argument has been added to force the fetch when it is not a
  fast-forward. This could have been achieved in previous Salt versions by
  including ``--force`` in the ``opts`` argument, this argument is just for
  convenience and to match the usage of other functions with ``force``
  arguments.
- The ``refspecs`` argument has been added to allow for one or more refspecs to
  be provided which override the one(s) specified by the
  **remote.remote_name.fetch** git configuration option.

:py:func:`git.ls_remote <salt.modules.git.ls_remote>`
*****************************************************

- The ``repository`` argument has been deprecated and renamed to ``remote``.
- The ``branch`` argument has been deprecated and renamed to ``ref``.
- The ``opts`` argument has been added to allow for additional CLI options to
  be passed to the ``git ls-remote`` command.

:py:func:`git.merge <salt.modules.git.merge>`
*********************************************

- The ``branch`` argument has been deprecated and renamed to ``rev``.

:py:func:`git.status <salt.modules.git.status>`
***********************************************

- Return data has been changed from a list of lists to a dictionary containing
  lists of files in the modified, added, deleted, and untracked states.

:py:func:`git.submodule <salt.modules.git.submodule>`
*****************************************************

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