Version selectors.md

1. If you install a pack without specifying a version, you will end up, quite predictably, on the latest master.

    $ st2 pack install cloudflare
    
    [...]

    $ git status
        On branch master
        Your branch is up-to-date with 'origin/master'.

2. If you install a pack using a commit ref (long or short) as the version, and master contains that commit, you will always end up on master even if other branches contain it, too. Tracking origin makes updates easy, btw:

    $ st2 pack install cloudflare=77ee04e
    
    [...]

    $ git status
        On branch master
        Your branch is behind 'origin/master' by 1 commit, and can be fast-forwarded.

3. If you install a pack using a commit ref (long or short) as the version, and there's a particular branch that contains that commit, but not master, you will end up on that branch (also tracking the remote, of course):

    $ st2 pack install cloudflare=fb7c858
    
    [...]

    $ git status
        On branch newbranch
        Your branch is up-to-date with 'origin/newbranch'.

4. Tags and branches also work as versions. If you specify a branch by name, you will end up on the latest commit of that branch:

    $ st2 pack install cloudflare=newbranch
    
    [...]

    $ git status
        On branch newbranch
        Your branch is up-to-date with 'origin/newbranch'.

5. If you specify a branch by name, and that branch has been merged into master, you will still end up on that branch, not master, since you requested it specifically:

    $ st2 pack install cloudflare=circle
    
    [...]

    $ git status
        On branch circle
        Your branch is up-to-date with 'origin/circle'.

6. If the pack repo has tagged versions (i.e. v0.1.0), both 0.1.0 and v0.1.0 can be specified. Same rules apply—you end up on master unless the tagged commit is on a particular branch, you can fast-forward to latest, and so on:

    $ st2 pack install cloudflare=0.1.0
    $ st2 pack install cloudflare=v0.1.0
    
    [...]

    $ git status
        On branch master
        Your branch is behind 'origin/master' by 2 commits, and can be fast-forwarded.

7. If your selector can't be resolved, but the pack has properly tagged versions, they will be suggested:

    $ st2 pack install cloudflare=OVER9000
    
    [  failed   ] download pack

    ValueError: "OVER9000" is not a valid version, hash, tag, or branch in 
    https://github.com/StackStorm-Exchange/stackstorm-cloudflare. 
    Available versions are: v0.1.0.

emedvedev/Version selectors.md