README
¶
rig
Scaffold a project from a blueprint, and keep it in step with that blueprint afterwards.
rig new acme-api --blueprint JustSteveKing/go-api-template
rig apply # re-run the blueprint after the template moves on
rig validate # check a blueprint is sound, before using it
rig check # verify the toolchain a blueprint needs
A single static binary with one dependency. Git is the only thing it needs on your machine, and only for fetching templates and merging.
Why another scaffolder
Scaffolders are one-shot. The pain is not day one — it is month six, when your twelve services have all drifted from the template they came from and there is no way back.
rig apply re-runs the blueprint against an existing project. It records what
it generated in .rig/lock.yaml, so it can tell a file you edited from one
still as it was written: untouched files are updated, edited ones are merged
three-way, and only genuine clashes come back as conflicts.
Install
Nix — no install step needed to try it:
nix run github:JustSteveKing/rig -- new acme-api -b ./templates/go-api
To keep it, add the flake as an input:
{
inputs.rig.url = "github:JustSteveKing/rig";
environment.systemPackages = [ inputs.rig.packages.${pkgs.system}.default ];
}
An overlays.default is exported too, though note that nixpkgs already has an
unrelated package called rig, so taking the overlay shadows it.
The Nix package wraps the binary with git on its PATH, so rig works even on
a machine that has no git of its own.
Go:
go install github.com/JustSteveKing/rig/cmd/rig@latest
Binaries for Linux, macOS and Windows on the releases page.
What a template looks like
my-service-template/
.rig/
blueprint.yaml what to ask, what to check, what to run
partials/ file bodies the blueprint contributes
go.mod.tmpl the skeleton — ordinary project files
main.go.tmpl
# .rig/blueprint.yaml
version: "1"
name: go-service
description: A Go HTTP API with structured logging and graceful shutdown.
variables:
- name: module
prompt: "Go module path"
default: "github.com/acme/{{ .Rig.Project }}"
- name: database
type: choice
options: [postgres, mysql, none]
default: postgres
files:
- path: compose.yaml
when: '{{ ne .database "none" }}'
from: partials/compose.yaml.tmpl
hooks:
post_install: ["go mod tidy", "git init -q -b main"]
Everything rig owns lives under .rig, on both sides — so a template
repository reads as the skeleton it is, and a generated project carries one
dot directory rather than a file at its root.
Three things worth knowing up front
Rendering is opt-in. Only *.tmpl files are rendered by default;
everything else is copied byte for byte. {{ }} is also Blade, Helm, Jinja
and near enough GitHub Actions, and a scaffolder that rendered everything
would corrupt a Laravel skeleton on the first view file it touched.
Requirements come from the template's own manifests. go.mod,
package.json, composer.json, .tool-versions and others are read, so a
blueprint rarely has to restate a version its template already declares.
Hooks are confirmed before anything runs. They are the one place rig executes code it did not write, so the whole list is printed and approved once, before a single file exists.
Documentation
| Concepts | How rig works and why it is shaped this way |
| Authoring templates | Writing one, and testing it |
| Blueprint reference | Every field |
| CLI reference | Every command and flag |
| Applying updates | What rig apply does to each file |
| Adoption | Using this as a developer, or across a company |
Examples
templates/ holds three working blueprints, generated from and
built on every CI run:
go-api |
Self-contained. Choice variables, conditional files, partials |
laravel-api |
Wraps laravel/laravel — a template it does not own |
next-bun |
Multi-runtime requirements, chained conditionals |
go build -o bin/rig ./cmd/rig
./bin/rig new /tmp/acme-api --blueprint ./templates/go-api
Building
make build # ./bin/rig
make check # gofmt, vet and tests — what CI runs
With Nix, nix develop gives you the toolchain, or direnv allow loads it on
cd.
Contributions welcome; see CONTRIBUTING.md.
Licence
MIT.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
rig
command
Command rig scaffolds projects from a blueprint, and keeps them in step with the blueprint afterwards.
|
Command rig scaffolds projects from a blueprint, and keeps them in step with the blueprint afterwards. |
|
internal
|
|
|
blueprint
Package blueprint defines the blueprint.yaml schema and its parser.
|
Package blueprint defines the blueprint.yaml schema and its parser. |
|
cli
Package cli wires the pieces together into commands.
|
Package cli wires the pieces together into commands. |
|
fsutil
Package fsutil holds the filesystem helpers shared by the fetchers, the renderer and the command layer.
|
Package fsutil holds the filesystem helpers shared by the fetchers, the renderer and the command layer. |
|
hooks
Package hooks runs the shell commands a blueprint declares.
|
Package hooks runs the shell commands a blueprint declares. |
|
lockfile
Package lockfile records what a project was generated from, so that it can be regenerated later.
|
Package lockfile records what a project was generated from, so that it can be regenerated later. |
|
merge
Package merge performs the three-way merge that `rig apply` needs.
|
Package merge performs the three-way merge that `rig apply` needs. |
|
render
Package render turns a fetched template plus a set of answers into files on disk.
|
Package render turns a fetched template plus a set of answers into files on disk. |
|
requirements
Package requirements verifies that the runtimes and tools a blueprint needs are installed, at the versions it asks for.
|
Package requirements verifies that the runtimes and tools a blueprint needs are installed, at the versions it asks for. |
|
source
Package source fetches a blueprint's template skeleton into a local directory that the renderer can walk.
|
Package source fetches a blueprint's template skeleton into a local directory that the renderer can walk. |
|
toolchain
Package toolchain is what rig knows about languages and their tooling.
|
Package toolchain is what rig knows about languages and their tooling. |
|
ui
Package ui handles terminal input and output: prompting for variables, confirming dangerous steps, and printing progress.
|
Package ui handles terminal input and output: prompting for variables, confirming dangerous steps, and printing progress. |
|
validate
Package validate checks a blueprint without running it.
|
Package validate checks a blueprint without running it. |