Version Control: Git Integration and PR Workflow

You have been working on a feature for two hours. The implementation spans seven files across three directories. Now you need to commit — but the changes are tangled. Some are the new feature, some are a bug fix you noticed along the way, and some are a refactor you could not resist. Manually staging hunks and writing a coherent commit message for each logical change would take fifteen minutes. With Claude Code, you describe what you want and it handles the git plumbing: staging the right files, writing commit messages based on the actual diff, splitting changes into logical commits, and opening a PR when you are ready.

This guide covers the git workflows that Claude Code handles best: committing, branching, conflict resolution, PR creation, and parallel development with worktrees.

What You’ll Walk Away With

• A workflow for clean, logical commits even when your changes are messy
• The claude commit and /commit-push-pr shortcuts that save minutes on every commit
• Prompts for merge conflict resolution that actually explain what is happening
• Worktree-based parallel development with multiple Claude instances
• PR creation workflow that links sessions to pull requests

How Claude Code Sees Your Git State

When you start a session, Claude automatically has access to your current branch, uncommitted changes, and recent commit history. You do not need to run git status first or paste diffs — Claude reads your git state directly. This means you can start with high-level requests like “commit my changes” and Claude will figure out the details.

Making Clean Commits

The One-Command Commit

The simplest workflow for committing:

claude commit

Claude reads the full diff of all staged and unstaged changes, generates a commit message based on what actually changed (not a generic description), and asks for your approval before committing. If nothing is staged, Claude stages everything first.

For more control, ask Claude interactively:

Commit my changes with a conventional commit message that explains
what was added and why.

Claude will:

1. Run git diff and git status to see all changes
2. Analyze the diff to understand the intent
3. Generate a descriptive commit message
4. Show you the message for approval
5. Run git commit after you approve

Splitting Tangled Changes

When your working directory has multiple unrelated changes, ask Claude to separate them:

Tip

Copy-paste prompt to split changes into logical commits:

I have changes across multiple files. Split them into logical commits:

1. Look at all the changes and group them by purpose
2. For each group, stage only the relevant files
3. Write a conventional commit message for each group
4. Show me the plan before committing anything

Do not commit until I approve the grouping.

Claude examines every modified file, identifies which changes belong together (the bug fix vs. the feature vs. the refactor), and proposes separate commits. You review the grouping and approve.

Commit Message Conventions

If your team uses a specific commit format, put it in your CLAUDE.md:

## Commit Standards
- Use conventional commits: feat, fix, docs, refactor, test, chore
- Include scope in parentheses: feat(auth): add OAuth flow
- Keep subject line under 72 characters
- Add body with bullet points for multi-file changes
- Reference issue numbers: Closes #123

Claude will follow these conventions automatically once they are in your project memory.

Branch Management

Creating and Switching Branches

Create a feature branch for the notification system based on main.
Use our branch naming convention.

Claude creates the branch, names it according to your conventions (if specified in CLAUDE.md), and switches to it. If you do not have a naming convention documented, Claude defaults to patterns like feature/notification-system or fix/auth-timeout.

Keeping Your Branch Updated

Rebase my branch on top of the latest main. If there are conflicts,
show me each one and explain what happened before resolving.

Claude fetches the latest changes, starts the rebase, and walks you through any conflicts rather than silently resolving them.

Cleaning Up Branches

Show me which local branches have already been merged to main
and can be safely deleted.

Claude runs the git commands to identify merged branches and presents a list. You approve before anything is deleted.

Resolving Merge Conflicts

Merge conflicts are where Claude provides the most value. Instead of staring at conflict markers and trying to understand two competing changes, you get a plain-language explanation.

Tip

Copy-paste prompt for merge conflict resolution:

I have merge conflicts after rebasing on main. For each conflict:

1. Explain what both sides of the conflict are trying to do
2. Identify if either side is clearly correct, or if both need
   to be combined
3. Show me the proposed resolution
4. Wait for my approval before resolving each file

Do not auto-resolve. I want to understand each conflict.

Claude reads the conflict markers, traces the history of both changes, and explains the situation. For a conflict in an authentication file, Claude might say: “The main branch added rate limiting to the login handler. Your branch restructured the handler into smaller functions. Both changes need to be kept — the rate limiting logic needs to move into your new validateLogin function.”

This is dramatically faster than reading the raw conflict markers yourself, especially in files you did not write.

Creating Pull Requests

The One-Step PR

Claude Code has a built-in skill that commits, pushes, and opens a PR in one step:

/commit-push-pr

This handles the entire flow: staging changes, generating a commit message, pushing the branch, and creating a PR with an auto-generated description based on the diff.

The Controlled PR Workflow

For more control over each step:

1. Review your changes

   Summarize all changes on this branch compared to main.
   Group them by area (database, API, UI, tests).

2. Commit with a descriptive message

   Commit these changes. The commit message should explain that
   we added cursor-based pagination to the search endpoint, including
   the database migration and updated tests.

3. Push and create the PR

   Push this branch and create a pull request against main. The PR
   description should include:
   - A summary of what changed and why
   - How to test the changes
   - Any migration steps required

Claude uses gh pr create under the hood. When you create a PR this way, the session is automatically linked to that pull request. You can resume the session later with:

claude --from-pr 142

This is useful when you get review feedback and want to pick up right where you left off with the same context.

Tip

Copy-paste prompt for a production-ready PR:

Create a pull request for this branch. Include:

1. A concise title under 70 characters
2. A summary section with 2-3 bullet points on what changed
3. A testing section describing how to verify the changes
4. A note about any breaking changes or migration steps
5. Link to the related issue if there is one

Push the branch first if it has not been pushed yet.

Parallel Development with Worktrees

When you need to work on multiple tasks simultaneously — say, implementing a feature while also fixing an urgent bug — git worktrees let you have separate working directories for each branch, with their own Claude Code session.

Setting Up a Worktree

# Create a new worktree with a new branch
git worktree add ../myproject-feature-a -b feature/notifications

# Or with an existing branch
git worktree add ../myproject-hotfix hotfix/auth-timeout

Each worktree is a separate directory with its own checkout. They share the same git history but have completely isolated file states.

Running Claude in Each Worktree

Open separate terminals for each worktree:

# Terminal 1: Feature work
cd ../myproject-feature-a
claude

# Terminal 2: Hotfix
cd ../myproject-hotfix
claude

Each Claude instance has its own session, its own context, and sees only the files in its worktree. There is no cross-contamination between tasks.

Cleaning Up Worktrees

When you are done with a worktree:

# Remove the worktree directory
git worktree remove ../myproject-feature-a

# Or if the branch was merged, clean up
git worktree prune

Note

Worktrees are the officially recommended way to run parallel Claude Code sessions. Running multiple Claude instances in the same directory is not supported and will cause conflicts. Each Claude instance needs its own working directory.

Continuing Sessions Across Git Operations

Claude Code sessions are tied to your directory, not your branch. When you switch branches, Claude still sees your conversation history but now reads the new branch’s files. This means you can:

• Start a session on a feature branch
• Switch to main to check something
• Switch back and continue where you left off

To explicitly continue your most recent session:

claude -c

To resume a specific session:

claude --resume

This opens a session picker where you can filter by branch using the B key.

Git History as a Debugging Tool

Claude can use git history to understand how code evolved and track down when bugs were introduced:

When was the authentication timeout behavior last changed?
Show me the commit and the diff.

Find the commit that introduced the regression in the payment
module. The bug was reported on January 15th, so check commits
from the week before that.

Show me all changes to @src/lib/auth.ts in the last month.
Summarize what each commit did.

Claude runs git log, git blame, and git diff to trace the history. This is especially useful when debugging issues in code you did not write.

When This Breaks

Claude commits files you did not intend — Be explicit about what to stage. Instead of “commit everything,” say “commit only the files in src/api/.” Or stage manually with git add first and then ask Claude to commit staged changes only.

Commit message does not match your conventions — Add your commit format to CLAUDE.md. Claude reads this before generating messages. If the format is still wrong, tell Claude: “That message does not follow our convention. Rewrite it as a conventional commit with scope.”

Merge conflict resolution loses important changes — Always ask Claude to explain each conflict before resolving. Review the proposed resolution before approving. If Claude gets it wrong, tell it: “That resolution dropped the rate limiting logic from main. Keep both the rate limiting and my refactored function structure.”

PR description is too generic — Give Claude specific instructions about what to include. “Create a PR” produces a generic description. “Create a PR that explains the pagination approach, lists the new endpoints, and describes the migration step” produces something useful.

Worktree sessions interfere with each other — Each worktree must be in a separate directory. If you accidentally run two Claude instances in the same directory, stop one of them. Use git worktree list to verify your worktrees are properly set up.

What’s Next

With version control workflows in place, learn how to handle failures gracefully when things go wrong during development.

Error Recovery Handling failures and recovering from mistakes

Development Workflow Build your first feature end to end