Lesson 15.215.2 Git through the agent

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.

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.

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). 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, waits for you (12.3). 15.11 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.

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:

-    .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:

<<<<<<< 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.

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, in your own tool, fifteen minutes.