star

star.toml

One file marks a directory as a template. It can be as rich or as empty as you like — an empty star.toml is a valid zero-config template whose name falls back to the directory name.

Full example

[template]
name = "rust-cli"                                # optional; defaults to directory name
author = "jingus"                                # optional
description = "My awesome Rust CLI template"     # optional
init-message = """                               # optional; printed after `star use`
Hope you enjoy my template! Use `nix develop` to enter the dev shell!
God bless!
"""

[star]
version = "0.0.1"                                # optional; future compatibility gate
ignore = ["target", "*.log", "secrets/"]         # optional; extra ignore globs

[template] fields

Field Type Default Purpose
name string directory name The template’s discoverable name (star use <name>)
author string — Shown in listings; free-form
description string — One-liner shown in listings and disambiguation prompts
init-message string — Printed after a successful star use — setup hints live here

[star] fields

Field Type Default Purpose
version string — Informational for now; will gate backward-incompatible schema changes
ignore array of globs [] Extra ignores, matched relative to the template root — layered on top of .gitignore. See ignore semantics

Design decisions

  • Both tables are optional. Lowering the cost of “just mark this directory as a template” is the whole point of the format.
  • star.toml files are never materialized — they are star metadata, not project files, at any depth. A template that wants to generate a template writes the file under a different name and renames it in whatever hook it ships.
  • #star-ignore on the first line marks the directory as not a template. Use cases: example manifests in docs, fixtures under test, a template for authoring templates. First line only — the check stays O(1).
  • [star] version is a compatibility gate in waiting. When the schema ever gains a backward-incompatible change, the version decides the behavior so old checkouts keep scaffolding identically.