Set up a repository with tisket, zettel, diataxis, and gaff

You need git and the four tools installed. The install commands are in Tools.

Create the repository

Run these commands in your terminal:

mkdir acme
cd acme
git init

Git initializes a repository in acme. Keep your terminal in this directory for the rest of the lesson.

Track the work

Create a tracker and an issue, then list it:

tisket init
tisket issue create "Write the docs check guide" -b "Explain how to check the docs."
tisket issue list

The first two commands print nothing. The list shows the issue:

ID                               STATUS  TITLE
9kuo-write-the-docs-check-guide  todo    Write the docs check guide

Issue and note IDs have random 4-character prefixes, so yours differ from these examples. Use your own prefixes wherever a command names an issue or note; every command accepts them.

Open tisket.yml and .tisket/default/project.yml. The initialization creates both files. Open .tisket/default/9kuo-write-the-docs-check-guide.md to see the issue.

Start work on the issue:

tisket issue edit 9kuo -s in_progress

Look at the issue file again. Its status is now in_progress.

Record a finding

Create a note store and a note:

zettel init
zettel note create "diataxis check finds type faults" -t docs -p human -b "diataxis check reports type faults and broken links."

The initialization prints initialized a zettel store at <path>. The create command prints the note ID:

l0oq-diataxis-check-finds-type-faults

Open zettel.yml and .zettel/l0oq-diataxis-check-finds-type-faults.md. The -t flag sets the note’s tags. The -p human flag labels its text as written by a person.

Connect the issue to the note through its scratch notes:

tisket scratch 9kuo append "Background: zettel note l0oq."
tisket scratch 9kuo read

The read command prints the line:

Background: zettel note l0oq.

Create a docs page

Initialize the docs, create a how-to page, and check the set:

diataxis init
diataxis page create "How to check the docs" -T how-to --description "Find type faults and broken links"
diataxis check

The initialization writes diataxis.yml and makes docs/. It prints two lines naming those paths. The create command prints how-to-check-the-docs (how-to).

The check prints:

advice  the set                      no tutorial pages
advice  the set                      no reference pages
advice  the set                      no explanation pages

These are advice rather than faults. The check passes with exit code 0.

Install the commit hook

Make the gaff directory:

mkdir .gaff

Create .gaff/gaff.yml with this content:

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"]

Install the hook before checking the configuration:

gaff init --git
gaff check

The commands print:

installed: pre-commit
config ok: 0 reminder(s), 0 section(s), 0 guard(s), cap 4096 bytes

Open .git/hooks/pre-commit. The script calls gaff, which runs the checks from .gaff/gaff.yml.

Commit the files:

git add tisket.yml .tisket zettel.yml .zettel diataxis.yml docs .gaff
git commit -m "Track, note, and document the docs check guide"

Before git’s summary, the hook prints:

gaff: pre-commit: issues
no problems found
gaff: pre-commit: notes
no problems found
gaff: pre-commit: docs
advice  the set                      no tutorial pages
advice  the set                      no reference pages
advice  the set                      no explanation pages

The commit lands with 8 files.

Watch the hook refuse a page

Create a how-to page whose title does not start with “How to”, then try to commit it:

diataxis page create "Checking the docs" -T how-to
git add docs
git commit -m "Add a page"

The output ends with:

fault  checking-the-docs            a how-to title states a goal: "Checking the docs" does not start with "How to"
...
Error:   x 1 fault(s)

gaff: pre-commit: `docs` failed with 1

The commit does not happen.

Remove the page, close the issue, and commit:

diataxis page delete checking-the-docs
git add docs
tisket issue close 9kuo
git add .tisket
git commit -m "Close the docs check guide issue"

The delete command prints removed checking-the-docs. Closing moves the issue file into .tisket/default/.closed/ and sets its status to done. The hook’s checks pass, and the commit lands.

You have one repository with issues, notes, and docs in git. Its commit hook runs all three checks.

The how-to guides cover further work:

Each tool has its own getting-started page: tisket, zettel, diataxis, and gaff.

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