Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions site/src/content/blog/who-writes-pro-git.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
title: 'Who writes Pro Git'
description: 'Agents help build this book, but they never write a sentence of it. Here is where the line is, why it is there, and how we enforce it.'
date: 2026-08-02
automated: true
---

AI agents have a hand in building this edition of _Pro Git_ — the tooling, the figures,
the planning work — and they have not written one sentence of the book.
That's a firm rule, not a preference, and this post explains why it's there and how it works.

## The book is written by humans

_Pro Git_ has named authors.
When you read an explanation of the index, or a walkthrough of interactive rebase, you're
reading someone who decided what mattered and what to leave out — what order made sense,
what analogy would land, what caveat was worth the interruption.
That judgment is the work.
A book isn't a delivery mechanism for facts that could be regenerated from a prompt;
it's an argument, made in a particular voice, by people who've thought carefully about
what a reader needs to know.

That's why the rule holds even when a machine-written change looks obviously helpful.
It's not weighed against convenience.
If a task would have an agent compose, rewrite, paraphrase, or "polish" the book's sentences,
the agent stops and hands it back to a human — every time.

## What agents actually do

There's plenty of work around the book that agents handle well:

- **Mechanical search-and-replace** — renaming `master` to `main` in examples,
correcting a command flag, fixing a broken link. Substitutions, not rewrites.
- **Figures and diagrams** — generating, placing, and wiring up images.
- **Planning and inventory** — building the revision plan, the checklist in
[`progress.asc`](https://github.com/progit/progit3/blob/main/progress.asc),
scope analyses.
- **Research** — investigating Git's release history and behavior changes,
checking what a flag does across versions. Findings are reported for a human to write up.
- **Rearranging content** — moving existing sections, reordering material, fixing
cross-references — as long as the sentences aren't rewritten.
- **Tooling and this site** — the build pipeline, the Astro site, the scripts that
get the book online.

## The test

The rule has a one-line version: does the change put new or altered sentences in front
of the reader?
If yes, a human writes it.
If the agent is moving, replacing, illustrating, researching, or planning around prose
that a human wrote, that's fair game.
When in doubt, treat it as prose.

## How it's enforced

The rules live in
[`AGENTS.md`](https://github.com/progit/progit3/blob/main/AGENTS.md) at the root of
the repository — the file every agent reads before touching anything in this project.
It's checked in and public, so you can read the exact instructions the agents are given.

Every change lands as a commit or pull request in the open, on the
[`progit/progit3`](https://github.com/progit/progit3) repository.
There's no process that can't be audited.

The blog is the one exception: some posts exist to communicate project updates, and those
are generated by agents working on the project.
Every one of them carries a "This post was written by AI" banner — like the one at the
top of this post.
Human-written posts are labeled too.
There's no ambiguity, and no unlabeled machine writing anywhere on this site.
The [authorship page](../../authorship/) spells the full policy out if you want it in
one place.

This post is itself an example of how the exception works.
If you want to argue with where we've drawn the line, `AGENTS.md` is one pull request away.