Version Control

Version control keeps a record of every change outside the agent conversation. Git is the standard tool. For agent work it supplies a fixed starting point and a reviewable diff, plus a way back when an implementation goes wrong.

Understanding Version Control

A version control system records snapshots of a project over time. Each snapshot stores the change with its author and a message that explains it. You can compare any two snapshots or return to an earlier one. Several people can work on the same files and combine their changes without overwriting each other.

Without it, a project exists only in its current state. A bad edit overwrites good work and the only backup is whatever someone copied by hand. Agents make many edits quickly, which raises the cost of losing that record.

A Short History

The first version control tools tracked changes to single files on one machine. SCCS appeared at Bell Labs in 1972 and RCS followed in 1982. CVS arrived in 1990 and let a team share a whole project through a central server.

Subversion, usually called SVN, launched in 2000 as a replacement for CVS. It kept the central server model. Developers checked out files from that server and committed changes back to it, and each commit received the next number in a single sequence. Some long-running projects still use it.

Linus Torvalds wrote Git in 2005 to manage development of the Linux kernel after the project lost free use of BitKeeper, the proprietary tool it relied on. Git made every copy of a repository a full copy with the entire history. Developers could commit and branch offline and share work between any two copies. GitHub launched in 2008 to host Git repositories, and Git has since become the default for most software projects.

How Git Works

Git rests on a few core ideas.

• A repository holds the project files and their full history.
• A commit is one saved snapshot with a message and a unique hash.
• A branch is a movable pointer to a line of commits, which lets feature work proceed apart from the main line.
• A merge combines the work of two branches.
• A remote is another copy of the repository, often hosted on GitHub, that you push to and pull from.

Git is two decades old and its command set is large. Many commands take options that change their behavior in surprising ways, and some of them discard work. Start with the everyday commands: status, diff, add, commit, switch, and log. The rest of this page builds on them.

A Fixed Starting Point

An agent run should begin from a known revision. Commit or set aside pending work first. The diff after the session then shows only what the agent changed. Existing edits may belong to another task or another person, so identify them before assigning work. Switching to a new branch does not remove uncommitted changes from the working directory.

Record the revision each run used, along with any uncommitted patch. A commit hash alone cannot identify changes that lived only in the working tree.

The Diff Is The Record

An agent's summary describes what it meant to do. The diff shows what it did. Read the diff of each file before committing. Review test changes and generated files alongside the source, plus any change to dependencies or instruction files. A weakened assertion or a new mock shows up here even when the summary calls the work complete.

Stage files by name and confirm the staged diff. One broad command that stages the whole tree can sweep in stray files and secrets. A passing test run applies only to the state you tested, so later edits require the affected checks to run again.

Git Worktrees For Parallel Work

Two agents in one working directory can overwrite each other or test a mixture of changes. Git worktrees give each task its own directory attached to the same repository. Create one with git worktree add and give it a branch of its own. One agent then works on the editor while another works on the runner.

Define shared interfaces before parallel work begins. Integrate each branch after review, then run the checks again on the combined result. Patches that pass alone can still conflict in behavior once merged.

Compare Variants Side By Side

Worktrees also let several agents attempt the same task at once, each from a different angle. Each variant runs on its own local port for review in the browser. You keep the strongest or merge the best parts of several. The cost grows with every variant, so this pattern suits work where taste decides the outcome, such as page copy or a layout.

Commits That Explain Themselves

A commit message should name the change, such as a fix that preserves saved pipeline step order. Conventional Commit prefixes label the kind of change. A feat commit adds behavior and a fix commit repairs it. The docs prefix covers documentation and refactor covers structural changes that keep behavior. Projects can add types such as chore or test.

These prefixes live in commit messages. A Git tag is different and names one revision, commonly a release such as v1.0.0. Branch names such as feat/pipeline-editor follow their own convention.

Let The Engine Own Git

When Claude Code or Codex runs inside an automated pipeline, the runner should handle branching and commits. A deterministic engine applies the same rules on every run. An agent under pressure to finish might commit a broken state. The engine can also revert edits an agent made outside its lane before the gate runs, such as changes to a test file it was told to leave alone.

Recover Without Erasing Other Work

A revert creates a new commit that undoes a chosen one and leaves history intact. Restoring a file or resetting a branch can discard work, so inspect the current state and save what you need first. Never let an automated repair reset a shared workspace. Block hard resets with a hook where agents run unattended.

Exercise 7: Run Two Agents Without Collision

In a project under Git, run git worktree add twice to create two directories, each on its own branch from the same commit. Give one agent a change in one module and a second agent a change in another. Read each diff before committing, and stage files by name rather than all at once.

Merge both branches and run the project's checks on the combined code, since two changes that pass alone can still break together. Then undo one of the commits with git revert and confirm the other change is still there with its history intact. Write down the commit each agent started from.

September, 2026