URLs should allow picking a branch or tag explicitely

[Leonidas-from-XIV]

Desired Behavior

When I pin a repo, I want to be able to tell Dune explicitely whether the fragment in the URL is a tag or a branch.

Example

(pin
 (url "git+https://github.com/FStarLang/FStar.git#v0.9.5.0")
 (package
  (name fstar)))

(package (name repro) (depends fstar))

This is currently impossible because v0.9.5.0 is both a branch and a tag in the repo and as a user I have no option to tell Dune which one it is. A possible workaround is to replace the tag with the commit hash, which is mostly workable, but with branches the commit the branch head points to is expected to change so it would require updating the pin all the time.

This ticket is inspired by #11113, which shows that repositories like this exist in the wild and are not just theoretical cases.

[rgrinberg]

This situation is probably more common than we might think. I believe it arises from the pattern of making a maintenance branch for released versions.

[Leonidas-from-XIV]

Yes, it's also a bit annoying if it used to work (because the tag was created) but stopped (because a branch was created afterwards). The OPAM manual on URLs is surprisingly vague on this. I'll continue to investigate if they have a solution.

Otherwise, the options I see:

1. Parse the fragment and if it is branch-FOO or tag-FOO (or similar) then assume FOO is a branch or tag respectively.
2. Allow something like (branch FOO) or (tag FOO) in the definition (and I guess ignore the fragment in the URL? Or keep it in the URL but don't interpret it as reference?)

[rgrinberg]

I'd like a solution that ideally opam could adopt as well. So I'm not keen on 2.

[Leonidas-from-XIV]

@kit-ty-kate pointed out that in OPAM the whole path to the reference can be used, so

1. opam pin add fstar [email protected]:FStarLang/FStar.git#refs/tags/v0.9.5.0
2. opam pin add fstar [email protected]:FStarLang/FStar.git#refs/heads/v0.9.5.0

This seems fairly sensible as it does not introduce any magic syntax and in my testing it worked just fine, so I've created #11142 as a repro case to implement something similar on the Dune side.