# 15.2 Git through the agent (/building-ai-workers/code-review/git-through-the-agent)

---
type: Document
title: "15.2 Git through the agent"
description: "Repositories, commits, branches, diffs and history from the beginning, with the agent typing the git commands and you reading each one."
status: stable
order: 315.02
ksor:
  owner: team:panaversity
  audience: [ public ]
  approval:
    by: process:panaversity
    at: 2026-11-02T18:33:52Z
chapter: "15"
part: III
expert_status: builder-only
concepts: [ "15.2" ]
last_verified: 2026-10-31
generated:
  at: 2026-11-02T18:33:52Z
  by: esl-rewrite/1.2.0+ksor.1
trust_tier: unverified
build_id: sha256:e1fbcb7d9a8f8b9b7cb96875022325c02c9ba4be94cef13b301cbd39a9edad85
dirty: true
ksor_version: 0.0.60
---

**In everyday life.** A careful writer saves a copy of a contract before each round of edits, and labels it with the date and what changed. They keep a separate draft when trying something risky. If the risky draft goes badly, the last good copy is still there. **Git** is a tool that does this for a folder of code, automatically and exactly.

**What you will learn.** What the git words mean, and how to direct git through an agent while you read each command it runs.

**Why it matters.** Every later step in this chapter depends on these words. Reviews read diffs, and merges join branches.

### What do the git words mean?

You have used git commands in every lab since Chapter 12. Here is what they mean, from the start.

- A **repository** is a folder whose past versions git keeps. They live in a hidden `.git` folder inside it.
- The **working tree** is the files as they are on your disk right now, including edits you have not saved in git yet.
- A **commit** is a saved snapshot, or copy, of the whole project, with a message, an author, a time and a short id such as `a78b9d0`.
- **Staging** means choosing what goes into the next commit. `git add src/reconcile.ts` stages one file, and the commit then saves only what was staged. That is how one task's edits become one commit, and an unrelated edit waits for its own.
- A **`.gitignore`** file lists what git should never save, such as `node_modules/`, `.env` and `out/`. Brightline's keeps keys and installed packages out of git.
- The **history** is the chain of commits, each pointing to the one before it.
- A **branch** is a movable name for a line of commits. `main` is the line everyone trusts. A new branch lets you try a change without touching `main`.
- A **diff** shows the lines that differ between two snapshots: `-` for a removed line, `+` for an added one.
- A **merge** brings a branch's commits into another branch. A **tag** is a name that never moves, such as `ch14`.
- **`HEAD`** means the commit you are on now. `HEAD~1` is the one before it, and `HEAD~2` the one before that.

![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.](img/commits-and-branches.png)

*Figure 15.3. Commits, a branch and a merge. `main` stays the trusted line while the weekend rule grows on its own branch.*

### Who types the git commands?

The agent does, and you read them. A coding agent can run every git command for you, and in this book it does. Your job is to say what you want, read each command before you approve it, and read what it shows. You do not need to memorize commands. You need to recognize what they do.

| You say | The agent runs | You check |
| --- | --- | --- |
| "What has changed?" | `git status`, then `git diff` | Only the files you expected, and every line makes sense |
| "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-rule` | The branch was made from the right starting point |
| "Show the history." | `git log --oneline --graph` | Your commits, in the order you expect |
| "Did any test change?" | `git diff main...weekend-rule -- tests/ py/tests/` | Nothing, unless a test change was agreed |
| "What does this branch change, compared with `main`?" | `git diff main...weekend-rule` | Only the files the task needed |
| "Undo that commit." | `git revert <id>` | A new commit that reverses it. History is kept |

### What does my app's change pane show?

The same diff git shows, usually for the agent's last turn or the uncommitted edits, the ones not saved in a commit yet. Each desktop app from Chapter 12 shows the agent's changes in a pane, a panel of its own. It can also give a session its own **worktree**: a second working tree, in its own folder, on its own branch. Two sessions in two worktrees can work on two branches without colliding ([12.2](../agentic-coding/the-workspace.md)). Before a pull request, read the whole branch with `git diff main...<branch>`. And keep the app in a permission mode that asks before each command, so every `git push` and every `gh` command, the GitHub tool in [15.3](github-and-the-pull-request.md), waits for you ([12.3](../agentic-coding/permissions-and-plan.md)). [15.11](both-ai-vendors.md) shows where each app puts these.

### Two dots or three?

Three, when you review a branch. `git diff main..weekend-rule`, with two dots, is the same as `git diff main weekend-rule`. It compares the two branch tips, the latest commit on each, so it also shows anything that changed on `main` since the branch began. `git diff main...weekend-rule`, with three dots, compares the branch with the point where it left `main`. That shows only the branch's own work, which is usually what a reviewer wants.

![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.](img/two-and-three-dots.png)

*Figure 15.4. Two dots compare the tips. Three dots compare the branch with where it left `main`, which is what a reviewer wants.*

### How do I read a diff?

Minus for a line removed, plus for a line added, and then ask what changed in meaning. Here are two lines from the diff on the branch `agent-speedup`, which you will meet in the lab. The agent rewrote the whole loop, and these are the old and new versions of the cutoff check:

```diff
-    .filter((r) => r.due <= cutoff)
+    if (date < cutoff) out.push({ due: date, number, vendor: names[vendorId] ?? vendorId, cents: Number(cents) });
```

Read the `-` line, then the `+` line, and ask what is different in meaning, not only in how it looks. One character changes the meaning: `<=` became `<`. An invoice due exactly on the cutoff day is now left out.

### What happens when a merge conflicts?

Git stops and asks a person. Git merges two branches line by line. When both changed the same lines differently, it cannot choose, so it stops with a **merge conflict** and marks the spot in the file:

```text
<<<<<<< HEAD
      - run: npm test
=======
      - run: npm test -- --test-reporter=spec
>>>>>>> main
```

The `-` in these lines is part of the file, not a diff's minus. The part above `=======` is your branch, and the part below is the branch you are merging in. Someone must decide what the lines should say, remove the markers, and commit. Ask the agent to show both sides and explain each before it proposes how to resolve the conflict, and read the result like any other diff. A conflict in a test file, or in a file that runs the checks, needs the most care, because the quickest way to resolve it is often the wrong one.

![A conflict in .github/workflows/ci.yml after git merge main, with each line labeled. The labels are the start marker with HEAD, the current branch's version, the divider, the incoming version from main, and the end marker. Four steps below: understand both versions, resolve by editing and removing the markers, verify with the diff and the checks, then stage, review and commit. A note says the agent can propose a resolution, and you verify the intended behavior is kept.](img/merge-conflict.png)

*Figure 15.5. Reading a merge conflict. Git marks both versions. A person decides, removes the markers and commits.*

### Which commands need a pause?

The ones that rewrite or throw away work. Most git commands are safe to approve, because git keeps every commit. A few can lose work, and those need a reason you understand before you say yes: `git reset --hard`, `git push --force`, `git clean`, and `git checkout -- .` or `git restore .` on uncommitted work. Chapter 12's permission rules apply: ask first for anything that is hard to undo. `git revert` is the safe undo for a commit others already have, because it adds a commit instead of erasing one.

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

**The operating rule:** let the agent type git commands, read each one before you approve it, and never approve a command that rewrites history or throws away work without knowing exactly what it removes.

**Practice it.** [Practice: git through the agent](both-ai-vendors.md#practice-git-through-the-agent), in your own tool, fifteen minutes.