Problem
Shortcodes remove parsing ambiguity (which is their value), but they force users to mentally translate a URL from their browser into gh:user/repo/subpath form. The natural workflow is: navigate to the template in the browser, copy the URL bar, paste it. That should just work.
Proposed feature
Accept full https:// URLs that follow vendor-specific tree-URL patterns and parse them into (url, ref, subpath):
- GitHub:
https://github.com/OWNER/REPO/tree/REF/PATH
- GitLab:
https://gitlab.com/OWNER/REPO/-/tree/REF/PATH
- Codeberg:
https://codeberg.org/OWNER/REPO/src/branch/REF/PATH
Additional behavior:
- Plain repo URLs (no
/tree/...) clone at default branch, repo root — works today, keep working
blob URLs (file views) → rejected with a clear error: "URL points at a file, not a directory — copy from a folder view instead"
- Branch names can contain slashes (e.g.
feature/foo). Disambiguate by running git ls-remote once before clone and using longest-prefix match against the known refs. Fall back to single-segment-ref interpretation if offline.
- Add
--ref <REF> and --subpath <PATH> CLI flags on diecut new as escape hatches for self-hosted / enterprise / unknown vendors
- If a tree URL and
--ref/--subpath disagree → error: "ambiguous source — remove one"
- Non-big-three vendors work as plain URLs, using the flags for ref/subpath
Non-goals
Acceptance criteria
Problem
Shortcodes remove parsing ambiguity (which is their value), but they force users to mentally translate a URL from their browser into
gh:user/repo/subpathform. The natural workflow is: navigate to the template in the browser, copy the URL bar, paste it. That should just work.Proposed feature
Accept full
https://URLs that follow vendor-specific tree-URL patterns and parse them into(url, ref, subpath):https://github.com/OWNER/REPO/tree/REF/PATHhttps://gitlab.com/OWNER/REPO/-/tree/REF/PATHhttps://codeberg.org/OWNER/REPO/src/branch/REF/PATHAdditional behavior:
/tree/...) clone at default branch, repo root — works today, keep workingblobURLs (file views) → rejected with a clear error: "URL points at a file, not a directory — copy from a folder view instead"feature/foo). Disambiguate by runninggit ls-remoteonce before clone and using longest-prefix match against the known refs. Fall back to single-segment-ref interpretation if offline.--ref <REF>and--subpath <PATH>CLI flags ondiecut newas escape hatches for self-hosted / enterprise / unknown vendors--ref/--subpathdisagree → error: "ambiguous source — remove one"Non-goals
Acceptance criteria
ls-remote-based ref disambiguation with offline fallback--refand--subpathflags ondiecut new