What does the new `branch` argument mean in git.latest states, and how do I use it?

Question

We just recently upgraded from Salt 2014.7 to 2015.8, and I’m confused by the new behavior in the git.latest state, namely the new branch argument.

In our staging environments, we’re accustomed to deploying to a named branch, which the git.latest state obtains off the pillar and plops into the rev argument. Something like this:

{% set branch = salt['pillar.get']('myapp:branch', 'master') %}
{% set code_prefix = "/tmp/myapp" %}

{{ code_prefix }}:
  file.directory:
    - user: myapp
    - group: myapp

myapp-repo:
  git.latest:
    - name: git@github.com:MyOrg/myrepo.git
    - rev: {{ branch }}
    - force_checkout: true
    - force_clone: true
    - force_fetch: true
    - force_reset: true
    - target: {{ code_prefix }}
    - user: myapp
    - require:
        - file: {{ code_prefix }}

After the upgrade, we started getting weird git errors in some repos; I’m not sure exactly what’s causing the errors, but it seems to be related to the new behavior where the rev of the working directory changes but the local named branch doesn’t change and so it mismatches the remote version of the local branch.

Long story short, setting the branch argument to git.latest seems to solve the problem:

myapp-repo:
  git.latest:
    - name: git@github.com:MyOrg/myrepo.git
    - rev: {{ branch }}
    - branch: {{ branch }}
    - force_checkout: true
    - force_clone: true
    - force_fetch: true
    - force_reset: true
    - target: {{ code_prefix }}
    - user: myapp
    - require:
        - file: {{ code_prefix }}

But I’m wondering: why do I suddenly need the branch argument? What’s going to happen if I ever deploy a sha or a tag instead of a branch name?

Should I be concerned? Am I Doing It Wrong™?

Answer 1

The branch parameter specifies which branch to use in the destination to checkout the rev branch/tag/commit. If you do not use this parameter, the rev will be checked out in whatever branch was active in the destination.

The documentation is pretty clear about that, I think:

Name of the branch into which to checkout the specified rev. If not specified, then Salt will not care what branch is being used locally and will just use whatever branch is currently there.

Note: If not specified, this means that the local branch name will not be changed if the repository is reset to another branch/tag/SHA1.

I don't know what was the previous behaviour. Now if you checkout a commit or a tag without specifying a local branch, there will be a hard reset of the local checked out branch to the specified rev, regardless of its previous state (provided you use force_reset=True)

Personally, I use a local branch name that is not present in the distant repository, so that there is no confusion about what is checked out.