Version Control

Pattern: A named solution to a recurring problem.

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

Complements: Pinning — Pinning without version control is wishful thinking; a pin is a VCS-tracked statement that something has been fixed.

Depended on by: Pipeline as Code — Pipeline as Code depends on this.

Depends on: Environment — Version control repositories exist within development environments.

Documented by: Runbook — Runbooks are version-controlled alongside the systems they describe.

Enables: Continuous Integration — CI is triggered by version control events.

Enables: Git Checkpoint — A deliberate commit before or after risky work.

Enables: Migration — Schema migrations are tracked in version control alongside code.

Enables: Rollback — Version control makes returning to a previous state possible.

Extended by: Worktree Isolation — Worktrees are a Git feature that extends version control to concurrent agents.

Used by: GitOps — GitOps relies on this pattern.

Sources

• In practice, version control today means Git, which Linus Torvalds wrote in 2005 for the Linux kernel after the project lost free access to the proprietary BitKeeper tool. Git’s distributed design gives every clone a full repository carrying the complete history, so committing, branching, and reverting are local and cheap. That is what makes the “commit before you let an agent loose” discipline this article recommends practically free.

• The practice is a generation older than Git. Marc Rochkind built the Source Code Control System (SCCS) at Bell Labs in 1972, the first system to track successive revisions of source files. SCCS established the founding idea underneath every pattern here: a project’s history is an asset worth storing, not a byproduct to discard.

• Walter Tichy’s Revision Control System (RCS), first released in 1982 and described in “RCS: A System for Version Control” (Software: Practice and Experience, 1985), refined the delta-based storage and per-file revision model that the later centralized systems, CVS and Subversion, built on before the distributed generation arrived.

• The branching conventions the Solution names were codified by Vincent Driessen’s “A successful Git branching model” (2010), the post that defined and popularized Git Flow. Its influence is why teams now treat branching as a deliberate strategy (trunk-based development, feature branches, or Git Flow) rather than an accident of habit.