question/documentation: clarification about commit option

[qnikst]

I'm failing to find any documentation on how commit option is supposed to work for git location.
Could it be a tag or commit or branch-name?
If it could be a branch-name then there is a strange behaviour, because git reset --hard branch-name will fail unless branch-name is written as origin/branch-name.
Also it's not clear how stack is supposed to work in this case, should it check if there is update in relevant branches and if so then update it and reset, should stack always fetch from repo and then do a reset?

UPD. if branch-name is supported then stack doesn't try to check if updates are available.

I don't know if it's a bug or features as there are exists 2 different approaches:

1. allow installing only concrete versions that gives better reproducibility and stability, but it this case master becomes something special;
2. allow installing moving targets, then stack should be able to check if updates are available. But in this case users may want to be able to skip redundant steps (if there were no updates).

It seems that one way forward will be implementing 2 different options commit and branch with behaviour (1.) for the former and (2.) for the latter.

[snoyberg]

The syntax will be documented on the stack.yaml wiki page, there's an open issue for that, just haven't gotten to it yet. If you'd like to jump into it, I'll be much appreciative.

The feature is only intended to work for immutable references: SHAs and (theoretically) tags. The reason being that this feature works by cloning, resetting, and then never checking the directory again (as you discovered).

I think this is all working as intended, it just needs to be written down outside of the discussion in the original issue (#199).

[snoyberg]

I've updated the stack.yaml Wiki page with a full explanation. @qnikst if things are still unclear, please let me know.