Recipes
CI formatting gate
Fail the build when any tracked file is not formatted:
- name: Check formatting
run: prim fmt --check .
prim fmt --check writes nothing, exits 0 when everything is already
formatted, and exits 1 (listing the offending files) otherwise. The top-level
prim --check spelling still works as deprecated sugar (warns on stderr;
removed in v2.0) — prefer prim fmt --check in new pipelines.
A repository that is not formatted yet cannot adopt this gate on day one; see Incremental adoption on an unformatted repository for the two routes to it.
Incremental adoption on an unformatted repository
The gate above reports every pre-existing file that is not already in prim’s canonical form, which in a repository that has never been formatted can be most of the tree. Two strategies get that gate passing. Choose by whether a large one-off reformatting commit is acceptable.
Format as you touch
Gate only the files a change already modifies. The gate passes from the first commit, and coverage grows as the repository is edited:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # a merge base needs the history on both sides
- name: Check formatting of changed files
run: prim fmt --check --since "$(git merge-base origin/${{ github.base_ref }} HEAD)" .
That snippet is for a pull_request-triggered workflow: github.base_ref is
empty on a push event, which leaves prim with origin/ and exits 2.
Compare against the merge base, not against the branch name. --since <REF> is
a plain two-way git diff --name-only <REF>: it reports every path that differs
between <REF> and the working tree, in either direction. Naming the branch
directly also matches files modified on main after the branch point that
this branch never touched — the gate then fails on an unrelated unformatted
file. A branch cut from the tip of main therefore passes at first and starts
failing as main advances underneath it, and a branch that has already merged
main in does not hit the problem at all. (Only modifications trigger it: a
file added on main is a deletion relative to this branch’s working tree, and
prim drops those silently.) Any revision expression git diff accepts works, a
merge-base SHA included. prim fences the REF so git reads it only as a revision,
so a name that is also a path in the tree — a docs branch beside a docs/
directory — resolves to the branch rather than being ambiguous, and a REF git
cannot resolve exits 2 instead of narrowing the file set. The fencing uses
--end-of-options, so --since requires git 2.24 or newer. Both flags also ask
git to exclude deletions, which needs git 1.8.5 or newer.
Either flag exits 2 if git reports a changed path that is not on disk and that
git will still materialise — a file staged as a modification and then removed
from the working tree, for instance. A sparse checkout, a skip-worktree entry
and a dangling symlink are absent by design and do not raise it.
Locally the same filter formats rather than checks:
prim fmt --since "$(git merge-base main HEAD)" .
--staged applies the same idea to the index: it selects the paths
git diff --name-only --cached reports, which is what a commit is about to
contain. Use it to report on a commit before making it:
prim fmt --check --staged .
The index chooses the paths, but prim still reads each one from the working tree, so the report describes the commit only for files staged in full. A file staged in part is reported on its working-tree content, including the part that is not being committed.
Do not reach for prim fmt --staged . as a pre-commit hook on its own.
--staged only chooses which paths prim looks at; prim then writes the
formatted bytes to the working-tree file and never touches the index, so
git commit still records the unformatted blob that was staged before prim ran.
A run that writes under --staged ends with one warning on stderr naming how
many files it wrote and pointing at git diff, which is where the unstaged
formatting shows up, but a warning never raises the exit code, so it does not
turn the hook into a gate. A hook has to re-stage the result, and for a
partially staged file it has to deal with the unstaged remainder first. Both
existing hook recipes below —
git-std and
pre-commit — already do that and
pass prim the staged list themselves, so a hook needs neither of these flags.
Two limits are worth knowing before relying on either flag as a gate:
- They see only what git reports. An untracked file does not appear in
git diffoutput at all, so it is not gated until it is added to the index —prim fmt --check --since HEAD .passes on a brand-new file thatprim fmt --check .would fail. Deleted paths that git does report are skipped silently. - Both require the working directory to be inside a git working tree, and
--sincerequires git to resolve its REF. On a shallowactions/checkoutclone there is no merge base, so thegit merge-basesubstitution in the workflow above fails in the shell and prim is handed an empty REF. prim then exits2— a usage error, not a format finding — rather than passing silently. That is whatfetch-depth: 0above prevents.
Both filters intersect with the rest of discovery rather than replacing it, so
.primignore, --exclude, and the ignore files still apply, and the two are
mutually exclusive. See USAGE.md for the full
semantics.
Format once and record the exceptions
The alternative is to reformat the whole tree in a single commit, add whatever
must stay byte-exact to .primignore (see
Protecting golden files), and use the full
prim fmt --check . gate from then on:
prim fmt .
git commit -am "style: format the repository with prim"
git rev-parse HEAD >> .git-blame-ignore-revs
Make that commit on an otherwise clean tree: git commit -am also sweeps in any
unrelated pending edit, and this is the commit you least want anything else
mixed into.
This keeps every later diff free of formatting churn, at the cost of one commit
that touches many files. Point git at the ignore file
(git config blame.ignoreRevsFile .git-blame-ignore-revs) so that commit does
not obscure git blame output.
Format-as-you-touch suits a repository where a large reformatting commit would
conflict with branches already open, or is not permitted by review policy. Its
running cost is the mirror image of that: a change touching one line of an
unformatted file reformats the whole file, so every diff carries reformatting
that has nothing to do with the change under review, for as long as adoption
takes. Formatting once suits everything else: it is a shorter adoption period
and a simpler gate. Either way, once the whole tree is formatted, drop --since
and go back to the CI formatting gate.
CI Markdown lint gate
Fail the build when a Markdown file has a content-lint finding:
- name: Lint Markdown content
run: prim lint .
prim lint never rewrites; it reports findings and exits 1 when any are
present. For Markdown specifically, every rule prim runs is an error, so there
is no silent warn-tier pass to worry about: if prim lint prints a Markdown
finding, the gate fails. Three settings decide which rules run — the always-on
floor tier, the strict tier once a path opts in via .editorconfig
prim_mdlint_strict = true, and MD013 once a path opts in via
prim_mdlint_report_line_length = true. See
USAGE.md for the rule lists.
Excluding a Markdown lint rule for a tree
A convention rule can legitimately fire across an entire tree — for example
MD033 (inline HTML) on a docs tree that intentionally uses <kbd> or
<img align="right">. Rather than adding a
<!-- markdownlint-disable-file MD033 --> comment to every affected file,
exclude the rule once per glob:
[docs/**.md]
prim_mdlint_strict = true
prim_mdlint_disable = MD033, MD041
prim_mdlint_disable only removes rules from the tier prim already selected for
that path — it is subtract-only, so it can never turn on a rule prim decided not
to run. See USAGE.md for the full resolution
semantics.
Checking links between files
prim checks the links that resolve inside a file — a dead heading anchor (MD051), an undefined reference definition (MD052) — and nothing beyond it. A link to another file is left to a dedicated link checker, because whether it resolves depends on the renderer the file is published through, not on the filesystem alone (AD-0013).
Run one beside prim. lychee checks
local and remote links across a whole tree and is the general choice; for an
mdBook site,
mdbook-linkcheck
resolves links the way mdBook itself does, which catches a link that exists on
disk but escapes the book root. Note that mdbook build on its own checks
nothing: it renders a link to a missing page without a warning and exits 0, so
the backend has to be installed and configured for the check to run.
Editor format-on-save
Point your editor’s “format with external command” hook at:
prim fmt --stdin-filepath "$FILE"
prim reads the buffer on stdin and writes the formatted result to stdout. The path is used only to select the right formatter.
Excluding files
prim respects .gitignore and .ignore automatically. To exclude a tracked
file from formatting (for example a deliberately malformed test fixture, or a
generated CHANGELOG.md), add it to a committed .primignore using gitignore
syntax:
# .primignore
CHANGELOG.md
fixtures/malformed.json
A lockfile needs no entry of its own: package-lock.json,
npm-shrinkwrap.json, pnpm-lock.yaml, and packages.lock.json are declined
outright by a built-in list (AD-0011), because prim can always tell that these
four are generated. CHANGELOG.md still needs the .primignore entry above —
some projects hand-author it, so prim cannot tell a generated changelog from a
hand-written one by name alone.
Protecting golden files
Test fixtures and golden files often contain deliberate formatting violations
(trailing whitespace, missing final newlines, non-canonical indentation) that
must stay byte-exact. Add those directories to .primignore — prim’s own
repository does this for its test fixtures:
# .primignore
crates/prim-fmt/tests/correctness/fixtures/
Note: .primignore applies however prim is invoked — a file it covers is left
alone whether prim walked to it or you named it on the command line (AD-0009).
Excluding a directory covers everything under it, and a later ! line cannot
take one file back out: under gitignore’s rules fixtures/ followed by
!fixtures/keep.md leaves keep.md covered, wherever the ! line is written.
That is what makes the entry worth having in a pre-commit hook, which passes
prim an explicit list of staged files. Naming an ignored path prints a warning
so the no-op is visible; pass --no-primignore to process it anyway.
To keep one file formatted, exclude the directory’s contents rather than the
directory itself. fixtures/* covers what is in the directory without covering
the directory, so the negation beneath it still works:
# .primignore
fixtures/*
!fixtures/keep.md
Skipping some of the paths given never changes the exit code, so a commit that
stages one ignored file alongside others still passes the hook — and so does one
that stages nothing but ignored files, because prim fmt and prim fix write
and doing nothing is the correct outcome there. A gate is the exception: where
prim fmt --check, prim fix --check, prim fix --diff,
prim fmt --check-idempotence, or prim lint is pointed only at paths it
skips, it examined nothing and exits 2 rather than reporting a clean run
(FR-4.4c). The rule counts the paths prim was pointed at, so
prim fmt --check --since <ref> . — the changed-file gate above — is outside
it: . was pointed at and was not skipped. It is a gate handed a path list that
the rule protects. Wire one with that in mind: a pipeline whose changed-file
list can legitimately be all-ignored — a release commit touching only a
.primignored CHANGELOG.md, say — should run the gate over the repository
rather than over the diff. Do not paper over it with || [ $? -eq 2 ] either:
2 is also how prim reports a file it could not parse, a path it could not
read, and a malformed --exclude glob, so a pipeline that accepts 2 accepts
those too.
A .primignore governs only the repository that holds it. prim reads the
.primignore files that apply from the path upward, stopping at the root of the
repository it was pointed at — the nearest directory holding a .git entry,
which is a file rather than a directory in a git worktree. So running prim
inside a nested checkout or a worktree uses that checkout’s own .primignore,
even when it sits at a path the enclosing repository’s .primignore names.
Running prim on the enclosing repository still prunes it, the way a .gitignore
entry would.
--exclude globs apply to directory walks and explicitly named files, including
descendants of an excluded directory.
Using prim with git-std
git-std generates CHANGELOG.md, which prim would otherwise hard-wrap as
Markdown. In repositories using both tools, add CHANGELOG.md to .primignore
(prim ships this entry by default).
Wiring prim into a git-std pre-commit hook
git-std hook run already resolves the staged-file list for you — a glob at the
end of a .githooks/pre-commit.hooks line restricts $@ to matching staged
files, and the ~ (fix) sigil stashes unstaged changes, runs the command, then
re-stages the result. prim needs none of that plumbing duplicated: pass it
whatever files git-std gives it, and prim’s own file-type detection skips
anything it doesn’t own (a .rs/.sh file, for example) with a warning instead
of failing:
# .githooks/pre-commit.hooks
~ prim fmt $@
No glob is required — an explicit glob like *.{md,json,yaml,toml} also works
and avoids invoking prim on staged files it will just skip, but it is an
optimization, not a correctness requirement. prim’s own repository wires itself
this way; see .githooks/pre-commit.hooks.
Using prim with the pre-commit framework
For repositories using the separate pre-commit
framework instead of (or alongside) git-std, prim ships a
.pre-commit-hooks.yaml manifest at the root of this repository. Reference it
from a consumer repository’s .pre-commit-config.yaml:
repos:
- repo: https://github.com/driftsys/prim
rev: v0.2.2 # pin to a released tag
hooks:
- id: prim
The hook uses language: system, so prim must already be on PATH (install it
with the install script or cargo install). The
pre-commit framework itself narrows the argument list to staged files matching
the hook’s types, the same way git-std’s $@ does — prim never needs to
re-derive that list itself.