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

Git Checkpoint

Pattern

A reusable solution you can apply to your work.

Understand This First

  • Version Control – checkpoints are a disciplined use of version control.

Context

This is an operational pattern, and one of the most practically important in agentic coding. A Git checkpoint is a deliberate commit (or branch, or tag) created specifically to mark a known-good state before or after risky work. It’s Version Control used not as a record of progress but as a safety net.

When you direct an AI agent to make large changes (refactoring a module, restructuring a database schema, rewriting a build system), you’re authorizing potentially sweeping modifications. A checkpoint ensures that if the result isn’t what you wanted, returning to safety is one command away.

Problem

You’re about to make a risky change, or you’ve just asked an agent to make one. If it goes wrong, you need to get back to where you were. But if you didn’t explicitly save your current state, “where you were” is gone, overwritten by the new changes. How do you create reliable rollback points around risky work without cluttering your history or slowing your workflow?

Forces

  • Creating checkpoints takes a moment of discipline that is easy to skip when you are in the flow of work.
  • Too many checkpoint commits can clutter the history if they are not cleaned up.
  • In agentic workflows, the scope of changes can be much larger and less predictable than manual edits.
  • You often don’t know in advance whether a change will be risky. Some of the worst breakages come from “simple” changes.

Solution

Before any risky operation, commit your current working state with a clear message indicating it’s a checkpoint. The message doesn’t need to be elaborate. “Checkpoint before agent refactor” or “save state before migration” is enough. The point is to create a named, reachable state you can return to.

For particularly risky work, create a branch:

git checkout -b checkpoint/before-schema-refactor
git checkout -b experiment/new-auth-flow

This preserves the checkpoint even if you later add more commits to your working branch.

After the risky work completes, evaluate the result. If it is good, continue working (and optionally squash the checkpoint commit during a later cleanup). If it is bad, reset:

git reset --hard HEAD~1  # Undo the last commit
# or
git checkout main         # Return to the stable branch

In agentic workflows, make checkpoints a habit. Not just before large changes, but before any agent interaction where you aren’t sure of the outcome. The cost is a few seconds. The benefit is the confidence to let the agent work freely.

How It Plays Out

A developer asks an agent to convert a JavaScript project from CommonJS to ES modules. The change touches every file in the project. Before starting, the developer commits with “checkpoint: before ESM conversion.” The agent’s changes mostly work, but the test runner configuration is broken. The developer resets to the checkpoint, asks the agent to also update the test configuration, and the second attempt succeeds.

A team adopts a rule: before any agent-directed refactoring session, run git add -A && git commit -m "checkpoint: before agent session". This takes five seconds and has saved the team from three significant rework episodes in their first month.

Tip

If your checkpoint commit is cluttering the history, use git commit --amend to fold the good changes into it, or squash during a rebase before merging. The checkpoint served its purpose; it doesn’t need to be permanent.

Example Prompt

“Commit everything as-is with the message ‘checkpoint: before ESM conversion.’ I want a clean restore point in case the module migration goes wrong.”

Consequences

Checkpoints give you the freedom to experiment boldly. When reverting is cheap and certain, you can let agents try ambitious changes without anxiety. This directly increases the value you get from agentic workflows, because the cost of a failed experiment drops to nearly zero.

The cost is minimal: a few extra commits in the log. If you’re disciplined about squashing or cleaning up checkpoint commits before merging, the long-term history stays clean. The real cost is the discipline to actually do it — the checkpoint you skip is always the one you needed.

  • Depends on: Version Control — checkpoints are a disciplined use of version control.
  • Enables: Rollback — a checkpoint provides a specific target for rolling back to.
  • Supports: Migration — checkpoints before and after migrations make them reversible.
  • Supports: Continuous Integration — CI verifies that the code at each checkpoint is valid.