AI commit messages: stop writing 'fix' and 'ok' in Git

How to write AI commit messages: why a diff shows what changed but not why, how to split commits, write a useful body and describe a pull request honestly.

A good commit message tells a later reader what a change does and why. An AI can write the "what" from the diff, but the "why" lives only in your head, so you have to give it. Do you often commit "fix" and then forget what you fixed? Let's look at it together.

You finish a feature in one evening. What does the Git history keep?

In the previous post, I gave the expense tracker app (a Telegram bot) a feature for edited messages: when the user edits a message they already sent, the matching expense is updated. The feature worked and had a test. But if you did all of that in one evening and committed whenever you reached a small stopping point, the history looks hard to read the next morning.

So that you can follow along without opening the previous post, I build two small Git repos with one script. Both repos record exactly the same sequence of changes and differ only in how the commits are named. The first repo, messy, is the kind of history everyone has produced. The second repo, tidy, holds the same changes split up and named properly. The script uses a tiny bot (a few lines of code) and a spec file, because all I need is something to commit. The real content of the bot does not matter in this post.

create-history.ts
// Build two temporary Git repos (in the temp folder of the operating system) for the same evening of work on the "edit a message" feature:
// one repo with messy commits, one with tidy commits that have explanatory bodies. Run: node create-history.ts <target-folder>
import { execFileSync } from "node:child_process";
import { mkdirSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";

const target = process.argv[2];
if (!target) throw new Error("Usage: node create-history.ts <target-folder>");

const SPEC_V12 = "# Expense tracker spec v1.2\n\n- Sending \"coffee 25k\" makes the bot record one expense.\n";
const SPEC_V13 = SPEC_V12.replace("v1.2", "v1.3") + "- Editing a message that was already sent updates the matching expense instead of adding a new one.\n";
const RECEIVE_MESSAGE = 'bot.on("message:text", handleMessage);\n';
const BOT = {
  original: RECEIVE_MESSAGE,
  wrongFilter: RECEIVE_MESSAGE + 'bot.on("edited_message.text", handleEdit);\n',
  rightFilter: RECEIVE_MESSAGE + 'bot.on("edited_message:text", handleEdit);\n',
  // Find the expense by the message_id of the edited message, not the last expense.
  findById: RECEIVE_MESSAGE + 'bot.on("edited_message:text", handleEdit); // find the expense by message_id\n',
};
const TEST = 'test("editing a message updates the expense instead of adding one", () => {});\n';
const NOTES = "# Verifying code the AI wrote\n\nRun it, compile it, then test it. Look up function names in the library code.\n";

type Step = { message: string; files: Record<string, string> };

// The same sequence of changes, recorded in two ways.
const MESSY: Step[] = [
  { message: "fix", files: { "src/bot.ts": BOT.wrongFilter } },
  { message: "fix again", files: { "src/bot.ts": BOT.rightFilter } },
  { message: "ok", files: { "src/bot.test.ts": TEST } },
  { message: "update", files: { "spec.md": SPEC_V13, "README.md": "# Expense tracker\n\nSee spec.md.\n" } },
  { message: "fix more", files: { "src/bot.ts": BOT.findById } },
  { message: "done", files: { "docs/verification.md": NOTES } },
];

const TIDY: Step[] = [
  { message: "docs(spec): add requirement v1.3, editing a message updates the expense", files: { "spec.md": SPEC_V13 } },
  {
    message: [
      "feat(bot): update the expense when the user edits a message",
      "",
      'Telegram sends an edited message as a separate update ("edited_message"), so the',
      '"message:text" handler never receives it. Before this, the bot ignored it and the expense kept the old amount.',
      "",
      "Find the expense by the message_id of the edited message, not by order: the user",
      "can edit an old message, not only the last one.",
    ].join("\n"),
    files: { "src/bot.ts": BOT.findById },
  },
  { message: "test(bot): add a test for editing a message", files: { "src/bot.test.ts": TEST } },
  { message: "docs: write down how to verify code the AI wrote", files: { "docs/verification.md": NOTES } },
];

function buildRepo(name: string, steps: Step[]): void {
  const folder = join(target, name);
  rmSync(folder, { recursive: true, force: true });
  mkdirSync(join(folder, "src"), { recursive: true });
  mkdirSync(join(folder, "docs"), { recursive: true });
  const git = (...args: string[]) => execFileSync("git", ["-c", "user.name=Minh", "-c", "user.email=minh@example.com", ...args], { cwd: folder, stdio: "pipe" });
  git("init", "-q");
  // The first commit of both repos is the same: spec v1.2 and a bot that cannot handle edited messages yet.
  writeFileSync(join(folder, "spec.md"), SPEC_V12);
  writeFileSync(join(folder, "src/bot.ts"), BOT.original);
  git("add", "-A");
  git("commit", "-q", "-m", "chore: initialize the repo with a bot that records expenses");
  for (const step of steps) {
    for (const [file, content] of Object.entries(step.files)) writeFileSync(join(folder, file), content);
    git("add", "-A");
    git("commit", "-q", "-m", step.message);
  }
}

buildRepo("messy", MESSY);
buildRepo("tidy", TIDY);
console.log(`Built 2 repos in ${target}: messy (7 commits including the first one) and tidy (5 commits including the first one)`);

You need Git and Node.js 22.18 or newer (Node runs .ts files directly from that version). Run it with any temporary folder, then print the history of both repos:

Build the two repos and look at the history
mkdir repos
node create-history.ts repos
git -C repos/messy log --oneline --reverse
git -C repos/tidy log --oneline --reverse
Output (your commit hashes will differ)
Built 2 repos in repos: messy (7 commits including the first one) and tidy (5 commits including the first one)
a51f71b chore: initialize the repo with a bot that records expenses
91e9f6b fix
3b77c93 fix again
bc19bf4 ok
4d764d6 update
a19f974 fix more
36c2b71 done
bf07991 chore: initialize the repo with a bot that records expenses
6ed166a docs(spec): add requirement v1.3, editing a message updates the expense
c4b9690 feat(bot): update the expense when the user edits a message
ab92922 test(bot): add a test for editing a message
4bba848 docs: write down how to verify code the AI wrote

The first seven lines belong to messy, the last five to tidy. Both start with the same initial commit.

Who does a messy history hurt, and when?

It looks like a matter of taste, but the cost appears exactly when you need the history. Say a month from now someone (maybe you) reads the second line of src/bot.ts and wonders why this handler has a comment saying "find the expense by message_id". The way to find out is git blame, which tells you which commit last changed each line:

Who changed line 2 of bot.ts, and why?
git -C repos/messy blame -L2,2 -- src/bot.ts
git -C repos/tidy blame -L2,2 -- src/bot.ts
Output
a19f9749 (Minh 2026-11-17 18:52:39 +0700 2) bot.on("edited_message:text", handleEdit); // find the expense by message_id
c4b96907 (Minh 2026-11-17 18:52:39 +0700 2) bot.on("edited_message:text", handleEdit); // find the expense by message_id

The first line points to commit a19f974, which is "fix more". The second points to c4b9690. Both blames find the right commit, but when you open each with git show, you see two very different things. With "fix more", you only have the diff and must guess why. With c4b9690, you can read this:

Read the whole commit message
git -C repos/tidy show -s --format=%B c4b9690
Output
feat(bot): update the expense when the user edits a message

Telegram sends an edited message as a separate update ("edited_message"), so the
"message:text" handler never receives it. Before this, the bot ignored it and the expense kept the old amount.

Find the expense by the message_id of the edited message, not by order: the user
can edit an old message, not only the last one.

This is what a later reader needs: what the problem was, and why this approach was chosen. The documentation of Git itself says the same about the body of a commit message: it should explain the problem that the change solves and why the solution is better. You can read it in the Git guide to submitting patches. The same document recommends writing the subject line as an order to the code ("make xyzzy do frotz", not "I changed xyzzy"). In practice I apply it simply by starting with a verb: add, fix, update, remove.

Check commits with a machine

With your eyes, the two repos look clearly different. But if you want to remind a whole team (or yourself at 11 pm), you need something automatic. I wrote a small script that reads the history of a Git repo and scores every commit against a few rules. The rules are ones I made up for this post. A real project should use an existing tool such as commitlint, or rules agreed by your team.

check-commits.ts
// Check the commits of a Git repo against a few simple rules. Run: node check-commits.ts <path-to-repo>
// This is a rule set I made up for this post, not a standard of Git or of Conventional Commits.
import { execFileSync } from "node:child_process";

export const MAX_SUBJECT = 72;
const TYPE = /^(feat|fix|docs|test|refactor|chore|perf|build|ci|style)(\([\w-]+\))?!?: \S.*/;
// A subject made of one generic word says nothing about the change.
const VAGUE = /^(fix|update|ok|done|fix again|fix more|wip|test|tmp)$/i;

export type Commit = { hash: string; subject: string; body: string };

export function checkCommit({ subject, body }: Commit): string[] {
  const problems: string[] = [];
  if (VAGUE.test(subject.trim())) problems.push("vague subject, does not say what changed");
  else if (!TYPE.test(subject)) problems.push("does not follow the form type(scope): description");
  if (subject.length > MAX_SUBJECT) problems.push(`subject is ${subject.length} characters long (maximum ${MAX_SUBJECT})`);
  // A change that adds a feature or fixes a bug should say why; docs and tests usually do not need to.
  if (/^(feat|fix)[(:!]/.test(subject) && body.trim() === "") problems.push("missing a body that explains why");
  return problems;
}

export function readCommits(repo: string): Commit[] {
  const raw = execFileSync("git", ["log", "--reverse", "--format=%h%x00%s%x00%b%x01"], { cwd: repo, encoding: "utf8" });
  return raw.split("\x01").map((chunk) => chunk.trim()).filter(Boolean).map((chunk) => {
    const [hash, subject, body = ""] = chunk.split("\x00");
    return { hash, subject, body };
  });
}

if (import.meta.main) {
  const repo = process.argv[2];
  if (!repo) throw new Error("Usage: node check-commits.ts <path-to-repo>");
  let withProblems = 0;
  const commits = readCommits(repo);
  for (const commit of commits) {
    const problems = checkCommit(commit);
    if (problems.length) withProblems++;
    console.log(`${problems.length ? "✗" : "✓"} ${commit.hash} ${commit.subject}${problems.map((p) => `\n    - ${p}`).join("")}`);
  }
  console.log(`\n${commits.length} commits, ${withProblems} with problems`);
}

Run it on both repos:

Score the two repos
node check-commits.ts repos/messy
node check-commits.ts repos/tidy
Output
✓ a51f71b chore: initialize the repo with a bot that records expenses
✗ 91e9f6b fix
    - vague subject, does not say what changed
✗ 3b77c93 fix again
    - vague subject, does not say what changed
✗ bc19bf4 ok
    - vague subject, does not say what changed
✗ 4d764d6 update
    - vague subject, does not say what changed
✗ a19f974 fix more
    - vague subject, does not say what changed
✗ 36c2b71 done
    - vague subject, does not say what changed

7 commits, 6 with problems
✓ bf07991 chore: initialize the repo with a bot that records expenses
✓ 6ed166a docs(spec): add requirement v1.3, editing a message updates the expense
✓ c4b9690 feat(bot): update the expense when the user edits a message
✓ ab92922 test(bot): add a test for editing a message
✓ 4bba848 docs: write down how to verify code the AI wrote

5 commits, 0 with problems

Six of the seven commits in the first repo are flagged, because their subjects say nothing. The second repo passes completely. I also wrote four tests for checkCommit (a vague subject is reported, a feat without a body is reported, a docs commit without a body is fine, a subject that is too long is reported), and all four are green when run with node --test check-commits.test.ts.

Besides naming, there is one more difference between the two repos that the script cannot measure: the second repo has four commits, one job per commit. That comes from the way you work, not from the way you write. Split commits by meaning, not by the moment you remembered something: one commit for the spec, one for the feature, one for the test, one for the docs. When you have already mixed things in one go, git add -p lets you pick each hunk of change for each commit. The practical benefit is that if one commit causes a bug, you undo exactly one job with git revert without dragging several other jobs along.

Asking an AI to write the message: what does it see, and what does it miss?

Now the main part. When you ask an AI to write a commit message, what it reads is usually the change itself (git diff). A diff tells you which lines were added and removed. It does not tell you why you did it. I will show the difference with a new change: a user reports that the bot stopped receiving messages after an error, and I add one bot.catch line so the error is only logged.

First, where the AI trips. If you paste only the diff, the answer you get will be the "what changed" part. I wrote an example of that kind of answer by hand, because I do not run a model in this post:

Illustrative example: the AI receives only the diff
feat(bot): add bot.catch to handle errors

This message is literally correct, but after reading it you still do not know what happened to the bot. If you also give your intent (one or two sentences about why), the AI has material to write the body. The script below builds a prompt from the changes you already ran git add on, together with the intent, and then you paste that prompt into whichever AI tool you use:

make-prompt.ts
// Build a prompt that asks an AI to write a commit message from the changes you already ran `git add` on. It does not call an AI: it only prints
// the prompt for you to paste into whatever tool you use.
// Run: node make-prompt.ts <path-to-repo> "<your intent: why you changed it>"
import { execFileSync } from "node:child_process";

export const MAX_DIFF_CHARS = 12_000;

const git = (repo: string, ...args: string[]) => execFileSync("git", args, { cwd: repo, encoding: "utf8" }).trim();

export function buildPrompt(repo: string, intent: string): string {
  const diff = git(repo, "diff", "--staged");
  if (!diff) throw new Error("Nothing has been added with git add: there is no change to describe.");
  if (!intent.trim()) throw new Error("Missing intent: the diff only shows WHAT changed, the AI cannot guess WHY you changed it.");
  const files = git(repo, "diff", "--staged", "--stat");
  const recent = git(repo, "log", "-5", "--format=- %s");
  const cut = diff.length > MAX_DIFF_CHARS;
  return [
    "Write a commit message in English for the changes below.",
    "Rules:",
    "- First line: type(scope): short description, at most 72 characters, no period at the end. The type is feat, fix, docs, test, refactor or chore.",
    "- Then one blank line, then a body (2 to 5 lines) that explains WHY the change was made and why this approach was chosen, without retelling every line of code.",
    "- Use only information that is in the diff and in my intent. Do not mention tests, benchmarks or effects that the diff does not show.",
    "- If the diff contains several unrelated pieces of work, do not write one combined message: say how many commits it should be split into and how.",
    "",
    "Subjects of recent commits (to keep the same style):",
    recent,
    "",
    `My intent: ${intent.trim()}`,
    "",
    "Changed files:",
    files,
    "",
    cut ? `Diff (cut to the first ${MAX_DIFF_CHARS} characters because it is too long; make smaller commits):` : "Diff:",
    cut ? diff.slice(0, MAX_DIFF_CHARS) : diff,
  ].join("\n");
}

if (import.meta.main) {
  const [repo, ...intent] = process.argv.slice(2);
  if (!repo) throw new Error('Usage: node make-prompt.ts <path-to-repo> "<intent>"');
  console.log(buildPrompt(repo, intent.join(" ")));
}

I have three reasons for building it this way. First, the script refuses to run if you give no intent, because without it the result is only "what changed". Second, the prompt includes the last five commit subjects, so the AI writes in the same style as your project instead of choosing one itself. Third, the prompt tells the AI to use only the information in the diff and the intent, and if the diff contains several jobs, to say it should be split instead of trying to merge them.

To try it, add one line to src/bot.ts of the tidy repo, then git add and run the script:

Make a new change, then build the prompt
printf 'bot.catch((err) => console.error(err.error));\n' >> repos/tidy/src/bot.ts
git -C repos/tidy add src/bot.ts
node make-prompt.ts repos/tidy "When handling a message throws an error, the bot stops receiving messages altogether. Add bot.catch so the error is only logged and the bot keeps running."
Output: the prompt, ready to paste
Write a commit message in English for the changes below.
Rules:
- First line: type(scope): short description, at most 72 characters, no period at the end. The type is feat, fix, docs, test, refactor or chore.
- Then one blank line, then a body (2 to 5 lines) that explains WHY the change was made and why this approach was chosen, without retelling every line of code.
- Use only information that is in the diff and in my intent. Do not mention tests, benchmarks or effects that the diff does not show.
- If the diff contains several unrelated pieces of work, do not write one combined message: say how many commits it should be split into and how.

Subjects of recent commits (to keep the same style):
- docs: write down how to verify code the AI wrote
- test(bot): add a test for editing a message
- feat(bot): update the expense when the user edits a message
- docs(spec): add requirement v1.3, editing a message updates the expense
- chore: initialize the repo with a bot that records expenses

My intent: When handling a message throws an error, the bot stops receiving messages altogether. Add bot.catch so the error is only logged and the bot keeps running.

Changed files:
src/bot.ts | 1 +
 1 file changed, 1 insertion(+)

Diff:
diff --git a/src/bot.ts b/src/bot.ts
index e7feb7e..c4fb362 100644
--- a/src/bot.ts
+++ b/src/bot.ts
@@ -1,2 +1,3 @@
 bot.on("message:text", handleMessage);
 bot.on("edited_message:text", handleEdit); // find the expense by message_id
+bot.catch((err) => console.error(err.error));

With that prompt, a good answer looks like the one below. It is an illustrative example that I wrote by hand, not the result of one specific run, so you know what I expect:

Illustrative example: the AI receives the diff and the intent
fix(bot): keep receiving messages when handling one message fails

When a handler throws, the bot stops and receives no more messages. Add bot.catch
so the error is only logged to the console and later messages are still handled.

The first line says what was done and the body says why. But do not paste it blindly. Before committing, I reread it and ask: is every sentence in this message true to the diff? For instance, if the AI adds "added a test for this case" and the diff contains no test file, that is an invention, and you must delete it. A message is a permanent record of your change, so the person responsible for every word in it is you, not the tool.

A pull request description follows the same principle

A pull request describes a whole branch instead of one commit, and the reader is a reviewer with little time. I use a four-part outline when I ask an AI for a draft:

Pull request description outline
## Why
What problem, who hit it, the evidence (an error link, a screenshot).

## What changed
Two to four bullet points, at the level of ideas, not a copy of the diff.

## How it was checked
The commands you ran and their real results. If you have not run something, say so.

## What the reviewer should look at
What you are unsure about, decisions that could be argued, changes that affect other places.

The third part is where an AI is most likely to make things up, because it may write "ran the full test suite and everything is green" even though nobody ran it. My rule is that I fill that part from real results, or if the AI fills it in, I rerun the commands and compare them with what it wrote. In a team project, this is the part where the reviewer trusts you most, so it is also where a mistake costs the most.

What to remember when you work with an AI

If I had to boil it down to a few habits, I would keep three. First, split commits by job before you ask the AI to write, because a diff with three unrelated jobs cannot get a good message. Second, always put your intent in the prompt, even when it is one sentence. Third, reread every sentence of the result and delete anything that is not in the diff. These three habits take less than a minute per commit.

If you already have a messy branch like messy and it is only yours, with nobody else using it, you can rename the commits with git rebase -i or git commit --amend. I do not run those two commands in this post, and you should only do it on a branch that has not been shared, because rewriting history that was pushed to others makes life hard for them.

The change is in. Who will review it?

Now every commit of the expense tracker tells a story, and the pull request explains why it exists. But one question is still unanswered: before merging, who reads that code and sees what you cannot? How useful it is to ask an AI to be the first reviewer, and how to use it without losing your own ability to read code, is for the next posts.

You can follow the whole journey in Build a side project with AI. If you are preparing for interviews, the questions about using AI while programming and about pull requests are in the interview question bank.

Get the next post by email.

One email a week, only when there is something worth reading. No spam.