Guides

A safe git workflow with Claude Code

Git is your undo button when an AI agent edits your code. With a few habits, any change Claude makes is easy to review, easy to revert, and never mixed up with your own uncommitted work.

1. Start every task on a clean branch

git status                      # commit or stash your own work first
git switch -c fix/login-timeout # one branch per task

A clean tree means git diff shows only Claude's changes. You can tell Claude to do this itself: "Before starting, make sure the tree is clean and create a branch named fix/<short-name>."

2. Commit in small, reviewable steps

Ask for a commit after each working step rather than one giant commit at the end:

Implement this in small steps. After each step passes the tests,
commit with a message in our usual format (see git log --oneline -20).
Don't mix refactors with behavior changes in the same commit.

Small commits make git revert and git bisect useful later.

3. Review the diff yourself

git diff              # unstaged changes
git diff --staged     # what's about to be committed
git diff main...HEAD  # everything on this branch

Look for things Claude does when it's unsure: debug prints left behind, commented-out code, tests that were loosened to make them pass, and edits to files unrelated to the task. For a second opinion, see using Claude Code for code review.

4. Run parallel sessions with worktrees

Two Claude sessions editing the same checkout will trample each other. git worktree gives each session its own directory and branch, sharing one repository:

git worktree add ../myapp-feature-a -b feature-a
git worktree add ../myapp-bugfix-b  -b bugfix-b

cd ../myapp-feature-a && claude   # session 1
cd ../myapp-bugfix-b  && claude   # session 2, in another terminal

git worktree list
git worktree remove ../myapp-feature-a   # when merged

Each worktree needs its own dependency install (node_modules, virtualenv), and may need a different dev-server port.

5. Never force-push shared branches

Rewriting main breaks everyone else's clones. If history on your own branch must be rewritten, use git push --force-with-lease, which refuses if someone else pushed in the meantime. Add a hook so Claude can't force-push to main even by accident. See blocking dangerous commands.

6. Scan for secrets before every commit

Agents sometimes paste a key into a config file "temporarily". A PreToolUse hook that checks git diff --cached for key patterns and blocks the commit catches this before it reaches history. Once pushed, a secret has to be rotated. See hook example 4.

7. Recovering from mistakes

• Undo uncommitted edits to one file: git restore path/to/file
• Undo the last commit but keep the changes: git reset --soft HEAD~1
• Undo a pushed commit safely: git revert <sha>
• Find "lost" commits: git reflog

Claude Code also has /rewind for rolling back its own edits within a session, but git remains the reliable record.

PR checklist

• The branch contains only this task's changes (git diff main...HEAD --stat).
• Lint, type checks and tests pass locally.
• No debug output, focused tests (.only) or commented-out code.
• New behavior has tests, and bug fixes have a regression test.
• The PR description says what changed, why, and how it was tested.