git-backed references.

A compact, human-writable string that identifies content in a remote git-hosted repository — without requiring a full URL.

owner/repo@ref:name

gref aims to be:

• Obvious — readable at a glance; looks like the shorthand people already type (owner/repo, owner/repo@v1, owner/repo:name).
• Minimal — only the pieces needed to locate content: host, owner, repository, ref, and name.
• Portable — the same string can be parsed by CLIs, package managers, agent tools, and config files.
• Host-friendly — defaults to a two-segment owner/repo form, with an optional host prefix for Gist, GitLab, and other forges.

gref specifies string syntax and structure. How a consumer downloads content, which ref or name to use when omitted, authentication, and caching are application-defined.

The general form is:

[host/]owner/repo[@ref][:name]

Whitespace is not allowed anywhere in a gref. Matching is case-sensitive for all components except where a host itself treats names case-insensitively (application-defined when resolving).

owner/repo

Implies no explicit host, ref, or name. Consumers apply their own defaults (see Application defaults).

owner/repo@main
owner/repo@v1.2.3
owner/repo@abc1234
owner/repo@feature/foo

ref is everything after the first @ following owner/repo, up to (but not including) a following :name, if any. It must not contain whitespace or :. It may contain / (common in branch names).

owner/repo:src/app.cs
owner/repo@v1:docs/readme.md
owner/repo@main:src/
owner/repo@main:my-skill

name is everything after the first : that follows the repository segment (and optional @ref). It is opaque at the grammar level: how a consumer interprets it is application-defined.

Common interpretations:

File and folder paths. When treated as a repository path, segments use / as the separator. A leading / is not required; consumers should treat foo/bar and /foo/bar as the same repository-relative path. A name that ends with / denotes a folder (tree) reference rather than a file (blob) reference. Consumers that resolve content should treat src/app.cs as a file and src/ as a directory.

Logical names. Applications MAY treat name as something other than a literal repository path. Examples include:

• a skill name looked up in a repo-root catalog.json (or similar index);
• a name resolved via a conventional folder structure (for example skills/{name}/ or .agents/skills/{name}/);
• a package, entrypoint, or other product-specific identifier.

When a logical name is used, the mapping from name to repository paths (or other artifacts) is entirely application-defined. The gref string still carries the same host, owner, repo, and optional ref; only the meaning of the suffix after : is specialized.

github.com/owner/repo@main:name
gist.github.com/owner/gistid
gitlab.com/owner/repo@main:name

When host is present it is a domain-like token: labels of alphanumerics and hyphens, separated by dots, ending with an alphabetic TLD of length ≥ 2.

Optional. When omitted, the consumer supplies a default (commonly github.com).

Other hosts are valid in the grammar; resolution is application-defined.

Non-empty. Must not contain /, @, :, or whitespace.

Non-empty. Must not contain @, :, or whitespace. Must not contain / (a / after owner/ starts a path only when using other URI forms — in gref, the repository name is a single segment).

On gist.github.com, repo is the gist identifier.

Optional. Branch name, tag name, or other commit-ish accepted by the host. Must not contain : or whitespace. May contain /.

When omitted, resolution of ref is application-defined. Implementations MAY:

• default to the repository’s default branch (commonly main or master);
• default to the latest published version (for example the newest release tag or package version the tool understands); or
• require an explicit @ref and reject or error when it is missing.

For reproducible shares (lockfiles, citations), prefer tags or commit SHAs over floating branch names.

Optional. Identifier for the content to locate within (or relative to) the repository.

At the string level, name is an opaque non-empty sequence of printable ASCII without whitespace. Applications MAY interpret it as:

1. File path — repository-relative path to a file (blob). Convention: does not end with /.
2. Folder path — repository-relative path to a directory (tree). Convention: ends with /.
3. Logical name — an application-specific key (for example a skill name resolved from a catalog.json, a conventional directory layout, or another product index).

The file/folder conventions above are recommended for path-like names so tools can share meaning without prior agreement. They are not mandatory for applications that only use logical names.

When omitted, the default name is application-defined (for example a well-known entry file, a default logical entry, or the repository root as a whole).

Normative structure (character classes for owner / repo / host are structural; see also Common subset):

gref        = [ host "/" ] owner "/" repo [ "@" ref ] [ ":" name ]

host        = label *( "." label ) "." tld
label       = alnum *63( alnum / "-" )
tld         = 2*alpha

owner       = 1*( unreserved )
repo        = 1*( unreserved )
ref         = 1*( %x21-39 / %x3B-7E )   ; non-empty; no ":" or space
name        = 1*( %x21-7E )             ; non-empty; no space

unreserved  = %x21-2E / %x30-39 / %x3B-3F / %x41-7E
              ; printable ASCII except space, "/" (0x2F), ":" (0x3A), "@" (0x40)
              ; — i.e. no gref delimiters
alnum       = ALPHA / DIGIT
alpha       = %x41-5A / %x61-7A

Parsing order:

1. If the string is an absolute URL of a known forge shape, first normalize it into gref form, then parse.
2. Else match the gref grammar.

A parse failure means the string is not a gref (it may still be a local path or another identifier — applications decide the fallback order).

Many GitHub-oriented tools additionally restrict:

These limits are not required by gref. Consumers talking to a specific API may tighten validation for that host.

# Defaults for host / ref / name left to the application
kzu/sandbox

# Explicit ref and name (file path)
kzu/sandbox@v1.2.3:src/hello.cs
kzu/sandbox@main:program.cs
kzu/sandbox@feature/foo:src/app.cs

# Folder path (trailing slash)
kzu/sandbox@main:src/
kzu/sandbox@v1:docs/guides/

# Logical name (application-resolved; e.g. skill catalog entry)
kzu/skills@main:code-review
owner/agents:my-skill

# Explicit host
github.com/kzu/sandbox@main:hello.cs
github.com/kzu/sandbox@main:src/

# GitHub Gist (repo = gist id)
gist.github.com/kzu/0ac826dc7de666546aaedd38e5965381
gist.github.com/kzu/0ac826dc7de666546aaedd38e5965381:run.cs

# GitLab
gitlab.com/kzu/runcs@main:program.cs

A structured gref should format back to:

[host/]owner/repo[@ref][:name]

Omit optional parts that are unset. Do not invent defaults when serializing unless the application documents that behavior.

Consumers MAY accept absolute HTTPS URLs pasted from a browser and normalize them to gref form before parsing.

https://github.com/{owner}/{repo}/blob/{ref}/{path}
→ github.com/{owner}/{repo}@{ref}:{name}

Where {name} is the repository-relative path from the blob URL (no trailing /).

https://github.com/{owner}/{repo}/tree/{ref}/{path}
→ github.com/{owner}/{repo}@{ref}:{name}/

The trailing / on the gref name marks a folder reference. If the tree URL points at the repository root (…/tree/{ref} with no further path), applications MAY omit :name or use a host-specific root convention.

https://gist.github.com/{owner}/{gistid}
→ gist.github.com/{owner}/{gistid}

https://gitlab.com/{owner}/{repo}/-/blob/{ref}/{path}
→ gitlab.com/{owner}/{repo}@{ref}:{name}

https://gitlab.com/{owner}/{repo}/-/tree/{ref}/{path}
→ gitlab.com/{owner}/{repo}@{ref}:{name}/

Other URL shapes are application-defined. Unknown hosts or shapes should not be forced into a gref.

gref is intentionally close to how developers already cite repository content in chat and CLIs.

These defaults are not required by gref; they are policies of tools that resolve grefs to downloadable content.

No single default for ref is mandated: a CLI that tracks floating source may use the default branch; a package-style runner may pin “latest release”; a strict resolver may demand @ref every time.

How name is resolved is likewise application-defined. A path-oriented tool may treat it as a repository-relative file or folder. A catalog- oriented tool may look up a skill or package id in catalog.json (or a conventional directory) and only then fetch concrete paths.

Local path disambiguation is also application-defined. A common pattern:

1. If the input exists as a local file, treat it as a path.
2. Else if gref parse succeeds, treat it as remote.
3. Else error.

• grefs can point at arbitrary public (or private) repositories. Tools that execute fetched content must treat it as untrusted code.
• Prefer fixed refs (tags or commit SHAs) for reproducible installs; floating branches (@main) change over time.
• Validate that resolved download URLs stay on the expected host before fetching.
• Do not expand environment variables or shell metacharacters inside gref components.
• Logical-name resolution (catalogs, directory walks) must not allow directory traversal or other path injection beyond the intended tree.

This specification is versioned with semantic-style tags (vMAJOR.MINOR.PATCH):

• MAJOR — incompatible grammar or meaning changes
• MINOR — backward-compatible additions (new optional forms, hosts)
• PATCH — clarifications, examples, non-normative text

The latest published version is always available at gref.sh.

This specification is available under the MIT License. See license.txt.