Claude Code Git Workflow

Claude Code deeply integrates Git functionality, allowing you to perform almost all Git operations using natural language, including creating commits, managing branches, handling merge conflicts, and leveraging Git Worktree for parallel workflows. This chapter provides a detailed introduction to using Git efficiently in Claude Code.

Basic Git Operations

1. Viewing Changes

Simply ask in natural language to get the Git status:

Which files did I change?

What does this change include?

最近 10 次提交都改了什么？

检查一下当前的 git 状态

Claude will automatically execute the corresponding Git commands and display the results.

2. Committing Code

Simple commit:

Commit this change.

Submit this modification.

Commit with description:

把这次的修改提交，commit 信息说明修复了登录验证的 bug

Claude will automatically generate a well-formed commit message based on the actual changes.

3. Branch Management

新建一个 feature/user-profile 分支

切换到 develop 分支

把 main 分支的最新改动合并进来

View all branches.

Delete merged branches.

Handling Merge Conflicts

1. Automatically Resolving Simple Conflicts

Help me resolve merge conflicts.

This file has conflicts, help me check which version is correct.

Claude will analyze the conflicting content and select the appropriate version based on the project context, or propose a solution.

2. Manual Intervention for Complex Conflicts

When the conflict is too complex, Claude will explain to you the pros and cons of each option:

这个冲突涉及架构设计，你来决定保留哪个方案：
A. 保留我们的实现...
B. 保留引入的优化...

Claude Code will display the changes and request your confirmation before making any file modifications. For high-risk operations like merge conflicts, it is especially important to carefully review each change.

Git Worktree Parallel Workflow

Git Worktree allows you to work on different branches in different directories simultaneously without switching branches or cloning the repository. This is one of the most powerful parallel working methods in Claude Code.

1. Creating a Worktree with Claude

Specifying a worktree when starting Claude:

claude --worktree feature-auth

This will automatically:

• In.claude/worktrees/feature-auth/Create a new directory
• Based onorigin/HEADCreate a new branch from (remote default branch)
• Start an independent Claude session in the new directory

Open multiple worktrees simultaneously:

claude --worktree bugfix-123

claude --worktree

When no name is specified, Claude will automatically generate interesting names (such asbright-running-fox）。

2. Worktree Properties

3. Worktree Lifecycle

4. Copying .gitignore to Worktree

Create in the project root directory.worktreeincludefile, specifying the gitignore files to copy to the worktree:

.env
.env.local
config/secrets.json

Only those matching a patternandFiles ignored by gitignore will be copied.

5. Manually Managing Worktree

If you need more control, you can manage manually:

# 创建 worktree 并指定分支
git worktree add ../project-feature-a -b feature-a

# 使用已有分支创建 worktree
git worktree add ../project-bugfix bugfix-123

# 在 worktree 中启动 Claude
cd ../project-feature-a && claude

# 完成后清理
git worktree list
git worktree remove ../project-feature-a

It is recommended to add.claude/worktrees/add to.gitignore, to avoid worktree contents showing as untracked files in the main repository.

Subagent Worktree Isolation

Subagents can use the worktree isolation feature to achieve fully independent parallel work:

Method 1: Let Claude handle it automatically

让子代理使用 worktree 来并行处理这些任务

Method 2: Specify in the subagent configuration

Subagent Worktree Features

• Each subagent automatically gets an independent worktree
• Worktree is automatically cleaned up after task completion
• Changes do not affect the main repository
• Suitable for exploratory tasks and comparing approaches

Pull Request Workflow

1. Steps to Create a PR

Step 1: Have Claude summarize changes

Summarize the changes I made to the authentication module.

Step 2: Generate PR

创建一个 PR

Step 3: Refine the PR description

在 PR 描述中补充更多关于安全改进的内容

2. PR Session Association

Usinggh pr createWhen creating a PR, Claude sessions are automatically linked to that PR:

• After a session is linked to a PR, you can resume the conversation from the PR
• Usingclaude --from-pr <number>Resume the linked session

3. Using GitHub CLI

Claude knows how to useghCLI tool. If not installedgh, Claude can read and write to the GitHub API, but with limited functionality.

# Claude 可以执行的操作
gh pr create --title "Fix login bug"
gh pr view --comments
gh pr diff
gh issue create --title "Bug report"

Session Management and Git Integration

1. Resuming a Previous Session

2. Session Selector Git Features

3. Session Metadata Display

The session picker displays the following information:

• Session name or initial prompt
• Time since last activity
• Number of messages
• Git branch (if any)

4. Branch Sessions

Using/branch、/rewindor--fork-sessionSessions created are grouped under the root session for easier management.

Plan Mode and Security Analysis

Plan Mode uses read-only operations to safely analyze the codebase without performing any write operations.

Starting Plan Mode

claude --permission-mode plan

Or run a one-time query in a session:

claude --permission-mode plan -p "分析认证系统并提出改进建议"

Configuring Default Mode in settings.json

Typical Workflow Examples

Workflow 1: Parallel Development of Multiple Tasks

# 场景：同时开发三个功能，但不想切换分支

> 启动三个 worktree，分别处理登录重构、支付集成和性能优化
> 在每个 worktree 中独立工作，完成后合并到主分支

Workflow 2: Bug Fix Process

# 第一步：描述问题
> 用户反馈：用户登出后刷新页面仍然显示已登录

# 第二步：创建修复分支
> 创建一个 bugfix/session-cookie 分支来修复这个问题

# 第三步：分析与修复
> 先分析可能的原因，在 bugfix 分支中修复

# 第四步：提交并创建 PR
> 提交修复并创建一个 PR

Workflow 3: Code Review

# 审查特定文件
> 帮我审查 src/payment/processor.ts，重点关注错误处理

# 审查 git 改动
> 审查我这次的所有改动，看看有没有明显的问题

# 在独立分支中审查
> 创建一个 worktree 来审查这个重构方案

Workflow 4: Feature Development and Verification

# 主会话：实现新功能
> 实现用户资料编辑功能

# 子代理：并行运行测试
> 在子代理中运行所有测试，只返回失败的测试和根因

# 子代理：检查代码规范
> 使用子代理审查代码是否符合项目规范

# 完成后：创建 PR
> 创建一个 PR 并添加详细的描述

Non-Git Version Control Systems

For SVN, Perforce, or Mercurial users, Claude Code supports extension through hooks:

Configuring Custom Hooks

In.claude/settings.jsonConfigure in:

These hooks replace default git behavior. When using hook scripts, copy local config files inside the script rather than using.worktreeinclude。

Best Practices from Anthropic's Internal Team

• Use multiple worktrees: Run 3-5 git worktrees simultaneously, each with an independent session — this is a recognized team best practice for improving efficiency
• Plan complex tasks first: Useplanmode to have one Claude write the plan and another act as an advisor to review it
• Update CLAUDE.md after errors: After each error correction, add a note saying "update your CLAUDE.md, don't make the same mistake again"
• Enter planning mode specifically for the verification phase: Ensure the verification process is safe and controllable

Frequently Asked Questions

Q: What is the difference between Worktree and branches?

Worktree is an independent directory that lets you work in different directories simultaneously; a branch is a different commit history within the same directory. Worktree is better suited for scenarios where you need to handle multiple complex tasks at the same time.

Q: Will the Worktree created by Claude affect the main repository?

No. Worktree has an independent directory, and its contents will not affect uncommitted changes in the main repository.

Q: How can I get Claude to work on a specific branch?

Switch branches before starting Claude, or useclaude --worktree <name>to automatically create a branch.

Q: Will having too many Worktrees take up too much space?

Git Worktree shares repository history; the new directory only contains branch differences, so it takes up very little space.

Q: When will the subagent's Worktree be cleaned up?

On normal completion, Claude will prompt you to choose whether to keep or delete it. Worktrees orphaned due to crashes will be automatically deleted after more thancleanupPeriodDaysthe configured number of days.