gitdone

GitDone

Your agent says it shipped. Git decides.

One markdown table of what must exist for a project to be done, with every row held to git, and a percent you can defend. A row is Live only when a commit on the default branch or a merged pull request says so. A commit that would make the numbers lie is refused, and a claim stops holding the day its commit is reverted.

No account, no server, no model calls, no dependencies. The files live in your repository and stay readable without the tool.

[The scale](#the-scale-how-far-along-is-it) · [Install](#install) · [Instruction](#instruction) · The gate · Focus · Commands · FAQ · Sponsor

The scale: how far along is it?

Every project answers that question with two numbers, side by side.

• Strict counts only the rows a commit on the default branch or a merged pull request says are Live. It is what an outside reviewer would count, and nobody can talk it up.
• Weighted also credits work that stopped short of that, at weights written in the plan: by default a row built on a branch counts 0.8, and a partial row 0.4.

The gap between them is work that exists and has not shipped. Strict 25% with weighted 46% is a lot in progress and little out the door, and it is a different project from strict 40% with weighted 46%.

That is gitdone chart --scale --out scale.svg, for Bramble Kiosk, a fictional library kiosk partway through its work, whose history docs/demo/make_history.py generates. Here is the same state everywhere you would meet it.

When you open the project. Plain gitdone, with what comes next and where the recent commits went:

$ gitdone

All: strict 25% (4/16), weighted 46% · next: S1 (Reading lists and renewals), needs the head librarian's word at release All strict ████░░░░░░░░░░░░ 25% weighted ███████░░░░░░░░░ 46% Focus, last 14 days: 8 of 13 commits on plan, 3 off plan (printer, theme).

<!-- scale:end -->

In `STATUS.md`. Generated and committed, so anyone who opens the repository can read it, and the gate refuses a view that no longer matches the table:

Bramble Kiosk: 16 rows

- Strict: 4 of 16 live · █████░░░░░░░░░░░░░░░ 25%

- Weighted: █████████░░░░░░░░░░░ 46%

- Built on branches, not released: 2 · demo only: 1 · partial: 3 · not built: 6

| Domain | Rows | Live | Built | Demo | Partial | Not built | Strict | Weighted | |

|---|---|---|---|---|---|---|---|---|---|

| 1. Catalogue search | 4 | 2 | 1 | 0 | 1 | 0 | 50% | 80% | ██████████░░ |

| 2. Lending | 4 | 1 | 1 | 1 | 0 | 1 | 25% | 57% | ███████░░░░░ |

| 3. Accounts | 3 | 1 | 0 | 0 | 1 | 1 | 33% | 47% | ██████░░░░░░ |

| 4. Reporting | 3 | 0 | 0 | 0 | 0 | 3 | 0% | 0% | ░░░░░░░░░░░░ |

| 5. Accessibility | 2 | 0 | 0 | 0 | 1 | 1 | 0% | 20% | ██░░░░░░░░░░ |

Workstreams, in the plan's order

| # | Workstream | Rows | Strict | Weighted | State | Needs |

|---|---|---|---|---|---|---|

| 1 | S1 Reading lists and renewals | 3, 7 | 0/2 | 80% ████████░░ | built and reviewed; released with the next kiosk update | the head librarian's word at release |

| 2 | S2 Returns | 6, 8 | 0/2 | 25% ██░░░░░░░░ | self-return shown at the open day; fines not started | the fines policy from the library board |

| 3 | S3 Accounts | 9, 10, 11 | 1/3 | 47% █████░░░░░ | card sign-in live; the override screen in progress | |

Next, in order: S1 → S2 → S3.

On every pull request that moves a row. The Action keeps one comment, and puts each finding on its row's line in the diff:

gitdone · gate: PASS

| | Rows | Strict | Weighted | |

|---|---|---|---|---|

| All | 16 | 4 (25%) | 46% | █████░░░░░░░ |

Against main: Since 54a3bd4 (2026-03-02): All strict 3→4 of 16 (19%→25%), weighted 39%→46%. Moved: 7 Partial→Built, not live; 9 Partial→Live. Workstreams moved: S1, S3; not moved: S2.

Next: S1 Reading lists and renewals. Needs the head librarian's word at release.

On your README. gitdone badge --keep writes the badge with the view, and the gate holds it to the table:

Over time. gitdone chart --out burnup.svg draws the table's own git history, with the scope line visible when it grows:

Across every project you keep. gitdone portfolio ~/code, read offline, and a failing gate is hard to miss:

For someone who will never open the repository. gitdone report --out report.md gives the evidence behind the numbers, row by row, as Markdown for a client or a manager.

Install

You need Python 3.9 or newer and git. GitDone has no dependencies of its own. gh is used only for a row that names a pull request, and glab for a merge request.

gitdone --version says it worked. pipx upgrade gitdone moves to a new version, and pipx uninstall gitdone removes it. Your table and view stay, and they read fine without the tool. A hook lives in .git/hooks, in this clone only: delete pre-commit, pre-merge-commit and post-commit there to take it out.

With a coding agent

What each one does.

As a gate

Instruction

One project from nothing to a number you can defend. Run these in your repository, on your own rows. Every block is real output, trimmed where it runs long, and a test keeps it so.

1. Write down what done means

Rows are capabilities a stranger could check, like Sign-in, not tasks like refactor auth.

$ gitdone init --rows "Sign-in, Search, Export, Reports" --hook

wrote .gitdone.json, status-table.md (4 rows) and STATUS.md All: strict 0% (0/4), weighted 0% · next: row 1 (Sign-in)

$ git add .gitdone.json status-table.md STATUS.md && git commit -q -m 'Track the scope' result: PASS

<!-- guide-begin:end -->

--hook guards the commits after this one, in this clone. --ci adds the Action, --agents the agents' rules, and --badge a badge.

Instead of --rows, start from a file's checklist or spec with --from-checklist TODO.md, or from GitHub issues with --from-issues. A checked item is Live only if what it names holds, and otherwise starts as Partial with the reason beside it, and an unchecked one starts as Not built, so the first number you see is already true.

2. Open the project with gitdone

$ gitdone

All: strict 0% (0/4), weighted 0% · next: row 1 (Sign-in) All strict ░░░░░░░░░░░░░░░░ 0% weighted ░░░░░░░░░░░░░░░░ 0%

<!-- guide-open:end -->

It says where things stand and what comes next. gitdone next lists the rows to work on now, and gitdone rows --open lists everything left.

3. Work, and name the row in the commit message

$ git add signin.py && git commit -q -m 'row 1: sign-in'

$ git switch -q -c search && git add search.py && git commit -q -m 'row 2: search by title'

$ git switch -q main

<!-- guide-work:end -->

The second commit is on a branch, for the next step. Naming the row is how gitdone focus knows where the work went, and nothing else depends on it.

4. Move a row when the work moves

$ gitdone shipped 1 b942cf2

row 1: Not built → Live (verified: commit b942cf2 is on main) All: strict 25% (1/4), weighted 25% · next: row 2 (Search) to commit: git add status-table.md STATUS.md

$ gitdone mark 2 built --branch search row 2: Not built → Built, not live All: strict 25% (1/4), weighted 45% · next: row 2 (Search) to commit: git add status-table.md STATUS.md

$ gitdone mark 3 partial "CSV works, PDF does not yet" row 3: Not built → Partial All: strict 25% (1/4), weighted 55% · next: row 2 (Search) to commit: git add status-table.md STATUS.md

<!-- guide-move:end -->

Only these move the numbers, and each one is held to its rule. Git is asked, and shipped refuses a commit that is not on the default branch, or one that only reverts another.

The weights are yours to change in .gitdone.json, and so are the kinds. With a remote, shipped wants the commit pushed, and mark --branch wants the branch pushed.

5. Change the scope out loud

$ gitdone add "Password reset"

added row 5 All: strict 20% (1/5), weighted 44% · next: row 2 (Search) to commit: git add status-table.md