Command reference

Installed as git-scaffold, every command runs as a Git subcommand: git scaffold <command>. Commands may be executed from any subdirectory of the worktree — the tool locates the actual worktree root itself.

• init · check · diff · apply · update · outdated · repatch · propose · version

git scaffold init

Initialize this repository from an upstream scaffold.

git scaffold init <git-url> [--ref <ref>] [--arg name=value]... [--existing] [--text-patch] [--force]

Verifies the current directory belongs to a Git worktree, creates .git-scaffold/config.toml, resolves the source, reads and validates the source descriptor, expands the managed file set, materializes the scaffold, and writes .git-scaffold/lock. If a required argument has not been supplied, initialization fails clearly.

git scaffold check

Verify managed files match the locked materialization.

git scaffold check

Reconstructs the expected contents from the target config, the lock, the source descriptor at the locked commit, the resolved arguments, and the target patches, then compares against the working tree. It never resolves the moving source ref merely to check for updates, and avoids network access when the locked commit is available locally.

git scaffold diff

Show differences between the working tree and the locked materialization.

git scaffold diff

Calculates the expected materialization from the locked commit and displays the differences as an ordinary unified diff. Never modifies the repository.

git scaffold apply

Make the working tree match the locked materialization.

git scaffold apply [--force]

Materializes the currently locked source. It never advances an existing lock because the configured ref has moved; if no lock exists yet, it may resolve the configured source and create the initial lock. A managed file that also carries unrelated local modifications causes a safe failure rather than silent loss of work.

git scaffold update

Update managed files to the currently resolved source ref.

git scaffold update [--force]

Resolves the configured source/ref again. If it resolves to the currently locked SHA, no update is required. Otherwise it constructs the complete new materialization — new descriptor, expanded globs, arguments, patches — validates the entire result, determines additions, modifications, and deletions (files leaving the managed set are deleted), writes the files, and updates the lock.

The operation is transactional: on any failure, no managed file changes and the lock stays unchanged.

$ git scaffold update
Updating scaffold

71db8b7 → 93ca782

error: .golangci.yml
patches/golangci.json: operation 4 failed:
path /run/timeout does not exist

No files changed.

git scaffold outdated

Report whether the source ref has advanced past the lock.

git scaffold outdated

Resolves the configured source/ref without modifying any target state and compares it with the locked SHA. Made for scripting and CI:

git scaffold repatch

Rewrite override patches from the current working-tree content of managed files.

git scaffold repatch [--text-patch]

Managed files are outputs, so a hand edit is reported by check rather than kept. repatch turns such edits into configuration: it compares every managed file with the patch-free materialization at the locked commit and regenerates the target's [overrides] and patch files so that materialization reproduces the working tree — exactly one patch per file, a json-patch where the source permits it for a JSON/YAML file and both sides parse (the file is normalized to the canonical serialization — for YAML only when the scaffold's own file already round-trips unchanged, since canonicalization drops comments and resolves YAML 1.1 scalars — unless the existing override already says json-patch, an explicit choice that is honoured regardless), a text-patch otherwise. Files check already accepts are left alone, override included. Files back at the scaffold's content lose their override, stale patch files are deleted, and comments and formatting in config.toml are preserved. The lock is never changed, and nothing is written until the complete result has been verified. check passes immediately afterwards.

P .golangci.yml (json-patch)
M .golangci.yml
U Makefile
D .git-scaffold/patches/Makefile.patch
✅️ updated patches

git scaffold propose

Propose a scaffold update via a pushed branch and pull request.

git scaffold propose [--branch <name>]

Performs the update on a tool-owned proposal branch (git-scaffold/update by default), commits (chore: update repository scaffold), pushes with safe force-update semantics, and creates a pull request if necessary — on github.com via the gh CLI. Repeated runs refresh the same branch and proposal rather than opening duplicates; when no update exists, no commit and no proposal are created. For unknown hosting providers the branch is still pushed, and the tool reports that automatic PR creation is unavailable. A custom creation command can be configured — see configuration.

git scaffold version

Print the version of git-scaffold.

$ git scaffold version
git-scaffold 0.1.0

Like every command, it may print a one-line newer-release notice to stderr when the periodic update check found one.