Skip to content

feat: accept full browser URLs (tree URLs, blob rejection, --ref / --subpath) #132

Description

@raiderrobert

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

  • Tree-URL parser for GitHub, GitLab, Codeberg
  • ls-remote-based ref disambiguation with offline fallback
  • --ref and --subpath flags on diecut new
  • Blob URL rejection with helpful error
  • Conflict detection when tree-URL and flags disagree
  • Integration tests: plain URL, tree URL, multi-slash branch, blob URL, conflict error, escape-hatch flags
  • Docs updated

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions