These release notes are for an old release of Salt. This release might contain known security and other issues that are fixed in the latest release.

# Git State and Execution Modules Rewritten

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

## Changes in the `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 `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.

## `git.config_unset` state added

This state allows for configuration values (or entire keys) to be unset. See `here` for more information and example SLS.

## git.config State Renamed to `git.config_set`

To reduce confusion after the addition of `git.config_unset`, the git.config state has been renamed to `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 `here` 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.

## New Functions in Git Execution Module

- `git.config_get_regexp`

- `git.config_unset`

- `git.is_worktree`

- `git.list_branches`

- `git.list_tags`

- `git.list_worktrees`

- `git.merge_base`

- `git.merge_tree`

- `git.rev_parse`

- `git.version`

- `git.worktree_rm`

- `git.worktree_add`

- `git.worktree_prune`

## Changes to Functions in Git Execution Module

### `git.add`

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

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

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

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

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

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

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

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

### `git.merge`

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

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

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