Design

Everything in git-scaffold hangs off one invariant:

Given the target configuration, locked upstream commit, upstream descriptor, target argument values and target patches, the expected contents of all scaffold-managed files are deterministic.

Manual modifications to generated managed files are not a supported customization mechanism — and everything else follows from the principles below.

Principles

Declarative

Configuration is data, not executable code. TOML throughout — no template language, no expressions, no conditionals or loops, no shell hooks, no embedded scripting. Remote scaffold content is treated as untrusted data, and a non-executable configuration keeps it that way.

Git-native

Sources are Git repositories and source versions are Git commits — any Git URL the installed Git supports, no hosting-provider API in the core. The executable is named git-scaffold, so it runs as git scaffold ….

Maintained, not generated once

The relationship with the source repository persists after initial creation. Targets explicitly update to later versions of their configured source — that is the point of the tool.

Source owns the scaffold interface

The source determines managed files, argument definitions, token representations, and allowed patch mechanisms. Targets provide values and intentional overrides. The argument name is the stable contract; token syntax stays the source's business.

Local divergence is explicit

Persistent differences from upstream must be represented by argument values, local patches, or native extension mechanisms of the managed format. The current contents of a generated file are never interpreted as an implicit local override.

Deterministic

Ordinary materialization uses the locked source commit. A moving branch, tag, or ref never silently changes generated output; advancing is always an explicit update.

Transactional

A failed update never leaves a partially updated repository or an advanced lock. Every modifying operation constructs and validates the complete result before changing anything.

Single repository

git-scaffold operates on one Git worktree. Fleet management is outside its scope — external tools such as gits invoke it across a fleet:

gits --repo-host github.com --repo-contains example-org \
    git scaffold update

Deliberate omissions

v0.1 deliberately excludes: fleet management and repository discovery, a template language of any kind, path templating and destination remapping, automatic preservation of generated-file edits, three-way merging, fuzzy conflict resolution, multiple upstream sources, recursive scaffold resolution, and hosting-provider API clients (provider CLIs such as gh are used instead). Template inheritance needs no special mechanism: a template repository simply contains already-materialized files from its own source while exposing its own descriptor to consumers.

The full specification

The complete requirements specification — descriptor semantics, the materialization pipeline, security constraints, and the required test matrix — lives in DESIGN.md in the repository.