add/discover: `--pin <commit|tag|branch>` to record a fixed ref

[tony]

Summary

When importing an existing checkout, add and discover capture only the repository URL — not the currently checked-out ref. There's no per-repo rev field and no CLI option to pin a repo to a specific commit/tag/branch, so a config can't capture a reproducible snapshot.

Note: the existing options.pin is a config-mutation guard (it stops re-import/overwrite of an entry), not a git ref pin. The two are easy to confuse — this request is specifically about pinning the checked-out revision.

Current behavior (v1.60.1)

• add/discover write {repo: <url>} with no ref captured (src/vcspull/cli/add.py, src/vcspull/cli/discover.py).
• RepoEntryDict has no rev/tag/branch field; only worktrees carry tag/branch/commit (src/vcspull/types.py).

The backend already supports it (libvcs v0.41.0)

• GitSync(rev=…) / GitSync.from_pip_url('…@<rev>'); update_repo() checks out the requested rev (src/libvcs/sync/git.py).

Proposal

1. Add --pin [<ref>] to add and discover:
   • with no value: capture the current ref (git rev-parse HEAD, or the symbolic tag/branch when checked out on one);
   • with a value: pin to the given commit/tag/branch.
2. Persist as a per-repo rev: key, plumbed to GitSync(rev=…) on sync.

Related

• Lock format, vcs.lock #463 (lock format vcs.lock) — a per-repo rev would be the natural unit a lockfile pins.
• git worktree for tags/refs #507 (git worktree for tags/refs, closed) — overlapping ref-checkout machinery, but for worktrees rather than the primary checkout.