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