Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Version Control

Pattern

A reusable solution you can apply to your work.

“The palest ink is better than the best memory.” — Chinese proverb

Also known as: Source Control, Revision Control, VCS

Understand This First

  • Environment – version control repositories exist within development environments.

Context

This is an operational pattern that underpins nearly every other practice in modern software development. Version control is the system of record for your source code, the single place where every change is tracked, attributed, and reversible. If your Application has more than one file or more than one contributor (human or agent), version control isn’t optional.

In agentic coding, version control is your safety net. An AI agent can generate, modify, or delete large amounts of code in a single operation. Without version control, a bad generation is a catastrophe. With it, a bad generation is trivially reversible.

Problem

Software changes constantly. Multiple people (and agents) contribute changes simultaneously. Bugs are introduced and must be traced to their origin. Working code must be preserved while experimental code is explored. How do you manage the ongoing evolution of a codebase so that nothing is lost, every change is traceable, and collaboration does not descend into chaos?

Forces

  • You need the freedom to experiment without fear of losing working code.
  • Multiple contributors must work simultaneously without overwriting each other’s changes.
  • Every change must be traceable (who changed what, when, and why) for debugging and accountability.
  • The history must be permanent and trustworthy, not something that can be silently altered.

Solution

Use a version control system (in practice, this means Git) to track every change to your source code. Commit frequently with meaningful messages that explain why a change was made, not just what changed. Use branches to isolate work in progress from stable code. Use pull requests or merge requests to review changes before they enter the main branch.

The fundamental unit is the commit: a snapshot of changes with a message, a timestamp, and an author. A good commit is atomic (one logical change), complete (the code works after the commit), and well-described (the message explains the intent). A repository full of good commits is a readable history of the project’s evolution.

Establish conventions for your team: a branching strategy (trunk-based development, feature branches, or Git Flow), commit message formats, and review requirements. These conventions matter more than the specific tool, because they determine how well the team can collaborate and how useful the history will be.

When working with AI agents, version control becomes even more important. Before asking an agent to make a large change, commit your current state, creating a Git Checkpoint. If the agent’s changes aren’t what you wanted, you can return to the checkpoint instantly.

How It Plays Out

A developer asks an agent to refactor a module. The agent rewrites 15 files, breaking several tests. Because the developer committed before the refactor, they run git diff to see exactly what changed, identify the problematic parts, and selectively revert the bad changes while keeping the good ones.

A team investigates a production bug and uses git log and git bisect to identify the exact commit that introduced it. The commit message reads “Optimize database query for user search,” and the diff shows a missing WHERE clause. The fix is obvious because the history is clear.

Tip

In agentic workflows, treat every significant agent interaction as a potential branch point. Commit before asking an agent to make large changes. If the changes are good, keep them. If not, reset to the checkpoint. This is cheap insurance.

Example Prompt

“Before you start the refactoring, commit the current state as a checkpoint. If the refactoring breaks something, I want to be able to diff against the checkpoint to see exactly what changed.”

Consequences

Version control gives you the ability to move forward with confidence. You can experiment freely because reverting is trivial. You can collaborate because merging is managed. You can debug effectively because the history is preserved. You can audit changes because every commit is attributed.

The cost is learning the tool and maintaining discipline. Git in particular has a steep learning curve, and bad habits (huge commits, meaningless messages, force-pushing shared branches) can make a repository’s history more confusing than helpful. The tool is only as good as the practices around it.

  • Enables: Git Checkpoint — a deliberate commit before or after risky work.
  • Enables: Continuous Integration — CI is triggered by version control events.
  • Enables: Rollback — version control makes returning to a previous state possible.
  • Enables: Migration — schema migrations are tracked in version control alongside code.
  • Depends on: Environment — version control repositories exist within development environments.