How to check issues, notes, and docs before a commit

Use gaff’s pre-commit hook to refuse commits with broken issue references, broken note links, or Diátaxis type faults. Start with initialized stores and the tools installed; see Tools.

Declare the checks

Create .gaff/gaff.yml with these entries, or add them to its existing git: list:

git:
  - name: issues
    on: [pre-commit]
    command: ["tisket", "check"]
  - name: notes
    on: [pre-commit]
    command: ["zettel", "check"]
  - name: docs
    on: [pre-commit]
    command: ["diataxis", "check"]

Each entry has a name, an on list of git hooks, and a command argument array. Commands run with the repository as their working directory. required defaults to true; false reports a failure and runs the remaining entries.

If the repository vendors skills, add an entry with command: ["almanac", "sync", "--check"] to the same hook. That command exits 1 when a pinned skill drifts. See How to vendor agent skills with almanac.

Keep these checks on pre-commit. Git passes the remote name and URL to pre-push commands, and gaff forwards those arguments. A pre-push entry running zettel check fails with unexpected argument 'origin'.

Install and validate the hook

Run these commands in order:

gaff init --git
gaff check

Installation prints installed: pre-commit and writes .git/hooks/pre-commit. Gaff never sets core.hooksPath. It keeps a hook it did not write as <hook>.local and calls that hook first.

gaff check validates the configuration. It exits 1 when a named hook is not installed, so installation must come first. Run gaff init --git again after editing the hooks list; it writes one script per hook.

On a commit, inspect failures from the named check:

Check	Result
`tisket check`	Reports broken references and store problems; prints `no problems found` when clear.
`zettel check`	Reports broken links and invalid provenance. A single problem exits 1 with `1 problem(s):`, the note, and the target.
`diataxis check`	Faults exit 1. Advice does not fail the check.

Run the same gates in CI

Run the declared pre-commit entries against HEAD:

gaff ci --hook pre-commit

The command prints gaff ci: ok when the checks pass. Plain gaff ci also runs pre-push entries and fails when none is declared.

For generated GitHub workflows, declare github: entries using the configuration keys. A step with use_git: <entry> reuses that git entry’s command.

Render the workflows, then commit .github/workflows/<name>.yml:

gaff init --github

Check the committed workflows for drift:

gaff check --github

The check exits 1 when a committed workflow differs from the configuration.

Remove the hooks

To remove gaff’s scripts and restore the kept hooks, run:

gaff init --git --uninstall

Set up a repository with tisket, zettel, diataxis, and gaff How to keep an issue's research in notes