Concepts

Four ideas carry the whole system. Get these down and every command reads like plain English.

Repository

Any git remote. star never requires a forge — it runs git against whatever URL you give it. A repository becomes useful to you the moment it is configured (star repo add), and its clone lives in a local cache that is safe to delete at any time.

Namespace

A repository’s identity in your config: the last two path components of its remote.

https://git.jingus.dev/jingus/starters   →   jingus/starters

Namespaces qualify templates — jingus/starters#rust-cli — so two repositories can both offer a rust-cli without colliding. If a remote’s tail is awkward or ambiguous, override it:

star repo add https://github.com/acme/mono --name acme/templates

Namespaces are validated: no #, no .., not absolute.

Template

Any directory inside a repository that contains a star.toml whose first line is not #star-ignore. That’s the entire registration mechanism — there is no manifest of manifests to keep in sync. A repository is a template collection precisely because any directory can opt in, and an empty star.toml is a perfectly valid zero-config template (the name falls back to the directory name).

When you scaffold, the template’s tree is materialized into your target — the star.toml itself is never copied, at any depth.

See the star.toml reference for every field.

Pin

The commit a configured repository is locked to. All scaffolding reads the pinned tree, which makes star use reproducible until you choose otherwise. Pins move only when you say so:

star repo update jingus/starters   # abc1234 → def5678

Ad-hoc URL references (star use https://…#name) are the exception: they resolve remote HEAD and are never pinned.

How the pieces fit