---
title: "Set up a repository with tisket, zettel, diataxis, and gaff"
description: "Keep issues, notes, and docs in git, then watch a commit hook refuse a broken page."
type: tutorial
canonical_url: https://eng.rip/set-up-a-repository/
---

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

You need git and the four tools installed. The install commands are in [Tools](<tools.md>).

## Create the repository

Run these commands in your terminal:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
mkdir .gaff
```

Create `.gaff/gaff.yml` with this content:

```yaml
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

- [How to keep an issue's research in notes](<how-to-keep-an-issues-research-in-notes.md>)
- [How to check issues, notes, and docs before a commit](<how-to-check-issues-notes-and-docs-before-a-commit.md>)
- [How to share notes, issues, and docs across repositories](<how-to-share-notes-issues-and-docs-across-repositories.md>)
- [How to vendor agent skills with almanac](<how-to-vendor-agent-skills-with-almanac.md>)
- [How to serve issues, notes, and skills over MCP](<how-to-serve-issues-notes-and-skills-over-mcp.md>)

Each tool has its own getting-started page: [tisket](https://tisket.eng.rip/getting-started/), [zettel](https://zettel.eng.rip/getting-started/), [diataxis](https://diataxis.eng.rip/getting-started/), and [gaff](https://gaff.eng.rip/getting-started/).