Skip to content
The AI Agent Factory

15.2 Git through the agent

Approved by
Panaversity ·
20 min read

In everyday life. A careful writer saves a copy of a contract before each round of edits, and labels it with what changed. For a risky idea, the writer starts a separate draft. If the draft goes badly, the last good copy is still there. Git is a tool that keeps those copies for a folder of code, exactly, each time you save a step.

What you will learn. How to read what git shows you: the saved copies, a separate draft, and what a draft changed. And how to ask for an undo that loses nothing.

Why it matters. Every later step in this chapter is built from these few words. A review reads a diff, and a pull request offers a branch.

What does git keep?

Every saved copy, and every separate draft. You have asked your agent for git steps in every lab since Chapter 12. Here is what they made. This is the whole history of the practice folder from 15.1, as git prints it. Read it from the bottom, oldest first:

* 6b6bc0a (agent-speedup) Speed up the due list with a single pass
| * b1c6d2f (tag: weekend-rule-start, weekend-rule) Add the weekend rule behind PAY_WEEKEND_RULE, off by default
| * bfc668f Failing tests for the weekend rule
|/
* 5297ed8 (HEAD -> main, tag: lab15-start) Lab 15 starting files: a stub workflow and the change brief convention
* f66221b (tag: ch14) Brightline AP at the end of Chapter 14
This lineMeans
The bottom line, f66221bThe oldest saved copy. f66221b is its short id, and the words after it are its label
The line with mainThe newest saved copy of the good copy, which is named main
The slanted line above itTwo separate drafts start here, from that copy
The two lines that end at weekend-ruleThe two saved copies of one draft, named weekend-rule
The top line, agent-speedupThe one saved copy of the other draft

Git has a word for each of the two things in this table.

  • A commit is one saved copy with its label. Every line with a * is a commit. Its label is called its message, and it says what changed.
  • A branch is a line of commits with a name. main is the branch everyone trusts. weekend-rule and agent-speedup are the separate drafts. Nothing on them has touched main.

A name after tag: is a fixed name for that one commit. You can leave the rest of the brackets for now.

Commits on main in a line, older to newer, with the tag ch14 on an early commit and the tag lab15-start where a branch begins. The branch weekend-rule has three commits: tests first, the rule, and a fix for a problem a review found. A commit from the merge joins both histories, and a later commit updates the notes. A key explains a commit, a branch and a tag.

Figure 15.3. Commits and a branch. main stays the trusted line while the weekend rule grows on its own branch, and is joined to main at the end.

Who types the git commands?

The agent does. You say what you want, and you read what comes back. You do not need to memorize a command. You need to recognize what each one does.

You sayThe agent runsYou check
"What has changed?"git status, then git diffOnly the files you expected changed
"Save this step."git add and git commit -m "..."The message says what changed and why
"Start the weekend work on its own branch."git switch -c weekend-ruleThe branch starts from the right commit
"Show the history."git log --oneline --graphYour commits, in the order you expect
"What did this branch change since it left main?"git diff main...weekend-ruleOnly the files the task needed

If "What has changed?" lists a file that the task had no reason to touch, ask why before anything is saved.

How do I read a diff?

Line by line: - marks a removed line, and + marks an added one. Here is one pair of lines from the branch agent-speedup. It is the first line of a test:

-test("eight invoices, $19,229.53, are due by Friday, March 5", () => {
+test("six invoices, $11,679.58, are due by Friday, March 5", () => {

This is a diff: two copies side by side, with the changes marked, as the writer marks the changes between two drafts. Read the - line, then the + line, and ask what changed in meaning. Here the old test expected eight invoices, and the new one expects six. This is the mistake from the opening story: the agent changed the test to agree with its new code.

A small diff can carry a large change in meaning. On the same branch, one character changed in the script: <= became <. An invoice due exactly on the cutoff day is now left out. You will find that line yourself in Try it.

How do I undo a commit?

Ask for a revert: a new commit that reverses an old one. The agent runs git revert with the commit's id. Nothing is erased. The old commit stays in the history, and the new one sits after it. The writer does the same: a bad round of edits is not torn up. A new copy is saved that takes the edits back out.

This is the undo to ask for, because git keeps every commit, and a revert only adds one.

At work. Ana asks the agent: "Make a branch for the weekend rule from main, and show me the history." It runs git switch -c weekend-rule and git log --oneline --graph. She checks that the branch starts at the newest commit on main. Later the agent proposes git reset --hard HEAD~1, which drops the last commit, to "clean up". She says no, and asks what it wants to undo. A git revert does the same job and keeps the history.

Try it

In your practice folder from 15.1, read the history, find one changed character, and undo a commit.

  1. Send: "Show me the history of all the branches as a graph. Change nothing." Find the line with main. Find the two lines that carry the names weekend-rule and agent-speedup. Then find the slanted line where both branches left main.
  2. Send: "Show me what the branch agent-speedup changed in the file src/due-by-friday.ts, the script that makes the due list. Show only the removed and added lines that hold the word cutoff. Change nothing." In your notes, write which character changed. Predict: will the due list get longer or shorter?
  3. Send: "Switch to agent-speedup, run the due list for 2027-03-05, show me the last line, and switch back to main."
  4. Send: "List the files that the branch weekend-rule changed since it left main. Change nothing." Count them.
  5. Send: "Add the line 'Practice note for 15.2.' to the end of NOTES.md on main, and commit it."
  6. Predict: after an undo that keeps the history, will main have fewer commits or more? Then send: "Undo that commit, in the way that keeps the history. Then show me the history of main." Read the command before you approve it.

What you should see. The graph is the one at the top of this lesson. <= became <, so the due list drops from 8 invoices to 6 invoices, total $11,679.58. The branch weekend-rule changed six files. For the undo, the agent should offer git revert, which adds a commit. So main ends with four commits, two more than it started with, and the newest one reverts your note. If the agent offers git reset --hard, say no, and ask what it wants to remove.

The operating rule: let the agent type the git commands, and read what each one shows. To undo a commit, ask for a revert. Never let a command that throws away work run until you know exactly what it removes.

Other git words you will meet

You do not need these to finish this lesson. Come back to this table when a later lesson or the lab uses one.

WordWhat it means
RepositoryA folder whose past versions git keeps. It is the writer's folder of copies
TagA name for one commit that never moves, such as ch14. A branch name moves forward with each new commit
HEADThe commit your folder shows now. HEAD~1 is the commit before it, and HEAD~2 the one before that
StagingChoosing which edited files go into the next commit. One task's edits become one commit, and an unrelated edit waits for its own
MergeCarrying a branch's commits into another branch, as the writer carries a draft's changes into the good copy
Two dots or threeTwo ways to compare a branch with main. Three dots, git diff main...weekend-rule, show only what the branch changed since it left main. Two dots, git diff main..weekend-rule, also show what changed on main since then. Ask in words for the one you want: "only what the branch changed since it left main"
Merge conflictTwo branches changed the same lines differently, so git stops the merge and marks both versions in the file. The part above ======= is your branch, and the part below is the branch you are merging in. A person decides what the lines should say, the marks come out, and the result is committed

main has commits A, B, C and D. The branch weekend-rule leaves main at B, the merge base, and has commits 1 and 2. Two dots, git diff main..weekend-rule, compare tip D with tip 2, so the diff includes changes made on either side. Three dots, git diff main...weekend-rule, compare B with 2, so the diff shows only what the branch proposes. A note says git diff only shows differences.

Figure 15.4. Two dots or three. Two dots compare the newest commit on each side. Three dots compare the branch with where it left main, which is what a reviewer wants.

Which commands need a pause?

The ones that throw away work. Most git commands are safe to approve, because git keeps every commit. But git can bring back only what was committed.

If the agent proposesIt would
git reset --hardThrow away edits that are not committed yet. It can drop commits too
git checkout -- . or git restore .Throw away edits that are not committed yet
git cleanDelete files git is not keeping
git push --forceOverwrite the history on a copy that others share (15.3)

It is like clearing the writer's desk: pages that were never saved as a copy are gone. Before you approve one of these, ask the agent exactly what it removes, and whether anyone else has those commits.

If your app does not stop for local commands. Under Ask for approval, Codex runs commands inside the project without asking (12.8). Say this in your first message: "Before any command that rewrites history or throws away work, stop and ask me." A request guides the agent, but it cannot bind it. So also have the agent commit each step, and read the history after each one.

In your tool: the details

Your app's change pane usually shows less than the whole branch: the agent's last turn, or the edits not committed yet. Before a pull request, ask for the three-dot diff of the whole branch. Here is where each app shows the agent's changes, and how it gives a session its own branch.

The Changes card opens a diff view, file by file. Comment on a line with +, and Claude makes the change. Turn on Worktree before the session starts. Worktrees go in .claude/worktrees/.1

The review pane shows unstaged or staged changes, a commit, the branch diff or the last turn. Stage or revert a file or one part of it, and comment on lines.2 For a branch of its own, use the separate Worktree control when you start a chat. Work in chooses this computer or the cloud.3

With Changed files on, in Settings, the timeline shows each completed turn's changed files, line counts and diffs. Read the whole branch with git diff. Choose a worktree and its base branch when you start a session.4


Next. 15.3 puts a shared copy of the repository where a whole team can see it.

Check yourself

Question 1 / 9

0 answered

You ask the agent "What has changed?" It runs git status and lists src/reconcile.ts and data/vendors.csv as modified. What do you do first?

  1. Use Claude Code Desktop, Anthropic.↑
  2. Code review, OpenAI.↑
  3. Codex modes, OpenAI.↑
  4. Changelog, OpenCode.↑
Owner
Panaversity