Create Worktree

一个用于创建基于裸仓库的 Git 工作树的 CLI 工具，支持高效的并行开发工作流。

English | 中文

特性

• 创建裸仓库以实现高效的 Git 工作树管理
• 设置指向裸仓库的 .git 文件
• 配置裸仓库以实现正确的远程分支跟踪
• 支持并行特性开发的隔离环境

快速开始

有两种使用模式：

1. 全局安装（推荐作为 git 子命令使用）

npm i -g create-worktree
# 然后作为 git 子命令使用：
git create-worktree <repo-url>
# 或使用短别名：
git cwt <repo-url>

2. 无需安装

# 初始化工作树结构
npm create worktree https://github.com/user/repo.git

# 创建主分支工作树
git worktree add main

# 创建特性分支工作树
git worktree add -b "feature-auth" feature-auth

工作原理

1. 创建裸仓库：将仓库作为裸仓库克隆到 .bare 子文件夹中
2. 创建 .git 文件：使用 gitdir: ./.bare 指向裸仓库
3. 更新 .bare/config：确保正确的远程分支跟踪配置

工作树开发模式

传统开发 vs 工作树模式

传统开发：

• 单一工作目录
• 分支间上下文切换缓慢
• 未提交的更改可能阻塞分支切换
• 难以同时处理多个特性

工作树模式：

• 多个独立的工作目录
• 每个分支都有自己隔离的环境
• 零上下文切换开销
• 完美支持并行开发

设置工作流

# 1. 初始化工作树结构
npm create worktree https://github.com/your-org/your-project.git

# 2. 创建主分支工作树
git worktree add main

# 3. 创建特性工作树
git worktree add -b "feature-user-auth" feature-auth
git worktree add -b "feature-payment-gateway" feature-payment
git worktree add -b "bugfix-login-issue" bugfix-login

# 4. 导航到任何工作树
cd feature-auth
# 在认证功能上工作...

cd ../feature-payment
# 在支付功能上工作...

目录结构

my-project/
├── .bare/           # 裸仓库（git 历史记录）
├── .git             # Git 目录指针
├── main/            # 主分支工作树
├── feature-auth/    # 认证功能工作树
├── feature-payment/ # 支付功能工作树
└── bugfix-login/    # 错误修复工作树

AI 辅助编程的优势

1. 并行 AI 开发

AI 助手可以在隔离的工作树中同时处理多个功能：

# AI 在一个工作树中处理认证功能
cd feature-auth
# AI 实现认证逻辑

# 同时，另一个 AI 实例处理支付功能
cd ../feature-payment
# AI 实现支付处理

2. 上下文隔离

每个工作树提供完美的上下文隔离：

• AI 只看到当前功能的相关文件
• 不同功能之间没有交叉污染
• 更清晰的 AI 响应，专注于特定上下文

3. 安全实验

AI 可以安全地进行实验和迭代：

• AI 生成代码的无风险测试
• 如果 AI 建议不起作用，轻松回滚
• 每个 AI 任务的隔离测试环境

4. 并发开发

多个 AI 实例可以同时工作：

# 终端 1：AI 处理认证
cd feature-auth
claude "实现 JWT 认证"

# 终端 2：AI 处理支付
cd feature-payment
claude "实现 Stripe 集成"

# 终端 3：AI 处理 UI
cd feature-ui
claude "创建用户仪表板"

5. 高效代码审查

AI 可以跨工作树审查更改：

# 比较 AI 生成的更改
git diff main..feature-auth
git diff main..feature-payment

# 合并已完成的特性
git checkout main
git merge feature-auth
git merge feature-payment

高级工作树管理

列出工作树

git worktree list

清理工作树

# 合并后移除工作树
git worktree remove feature-auth

# 清理过期的工作树
git worktree prune

移动工作树

git worktree move feature-auth features/auth

最佳实践

1. 工作树命名约定

feature-<描述>        # 新功能
bugfix-<问题>        # 错误修复
hotfix-<问题>        # 紧急修复
experiment-<想法>     # 实验性功能

2. 工作树生命周期

# 创建
git worktree add -b "feature-new-api" feature-api

# 开发
cd feature-api
# 进行更改，提交

# 测试
# 在隔离环境中运行测试

# 合并
cd ../main
git merge feature-api

# 清理
git worktree remove feature-api
git branch -d feature-api

故障排除

常见问题

1. 工作树已存在

   git worktree remove <worktree-path>
   git worktree prune

2. 分支已被检出

   git worktree list
   git worktree remove <existing-worktree>

3. 清理失败的工作树

   git worktree prune

开发

# 安装依赖
bun install

# 构建
bun run build

# 运行测试
bun run test

# 类型检查
bun run typecheck

# 代码检查
bun run lint

贡献

1. Fork 仓库
2. 创建功能工作树：git worktree add -b "feature-your-feature" feature-your-feature
3. 进行您的更改

# 初始化工作树结构
npm create worktree https://github.com/user/repo.git


4. 运行测试和代码检查
5. 提交拉取请求

## 许可证

MIT