Imported from guanqiao/python_visio (
.opencode/skills/git-worktree/SKILL.md). Install upstream withnpx skills add guanqiao/python_visio --skill git-worktree. Copyright stays with the author (MIT).
Git Worktree 管理规则
核心原则
永远不要直接在主工作目录切换分支。 使用 git worktree 为每个分支/功能创建独立的工作目录。
为什么使用 Worktree？
- 并行开发: 同时在多个分支上工作，无需 stash/commit
- 避免污染: 主分支保持干净，不会被未完成的代码污染
- 快速切换: 在 IDE 中打开不同的 worktree 目录即可切换上下文
- 独立环境: 每个 worktree 有自己的 node_modules、虚拟环境等
目录结构
~/projects/
├── my-project/ # 主仓库 (main/master 分支)
│ ├── .git/
│ └── src/
├── my-project.wt/ # worktree 根目录
│ ├── feature-auth/ # feature/auth 分支
│ ├── bugfix-login/ # bugfix/login 分支
│ ├── refactor-core/ # refactor/core 分支
│ └── hotfix-urgent/ # hotfix/urgent 分支
工作流程
1. 创建 Worktree
为新分支创建 worktree：
# 进入主仓库
cd ~/projects/my-project
# 创建新分支并建立 worktree
git worktree add ../my-project.wt/feature-auth -b feature/auth
# 或者基于远程分支
git worktree add ../my-project.wt/bugfix-login -b bugfix/login origin/main为已有分支创建 worktree：
# 切换到主仓库
cd ~/projects/my-project
# 为已存在的分支创建 worktree
git worktree add ../my-project.wt/existing-branch existing-branch2. 使用 Worktree
进入 worktree 目录：
cd ~/projects/my-project.wt/feature-auth此时你可以：
- 独立安装依赖：
npm install/pip install -r requirements.txt - 独立运行服务：
npm run dev/python manage.py runserver - 独立运行测试：
npm test/pytest - 独立构建：
npm run build
3. 查看所有 Worktree
# 在主仓库或任意 worktree 中执行
git worktree list
# 输出示例：
# /home/user/projects/my-project 3a4b5c6d [main]
# /home/user/projects/my-project.wt/feature-auth 7e8f9g0h [feature/auth]
# /home/user/projects/my-project.wt/bugfix-login 1a2b3c4d [bugfix/login]4. 清理 Worktree
完成任务后清理：
# 1. 进入主仓库
cd ~/projects/my-project
# 2. 移除 worktree（保留分支）
git worktree remove ../my-project.wt/feature-auth
# 3. 如果分支已合并，删除分支
git branch -d feature/auth
# 4. 强制删除（如果有未提交的更改）
git worktree remove -f ../my-project.wt/feature-auth
# 5. 清理空的 worktree 根目录
rm -rf ../my-project.wt/feature-auth分支命名规范
功能分支 (feature/)
git worktree add ../my-project.wt/feature-user-auth -b feature/user-auth
git worktree add ../my-project.wt/feature-payment-gateway -b feature/payment-gateway修复分支 (bugfix/ 或 fix/)
git worktree add ../my-project.wt/bugfix-login-error -b bugfix/login-error
git worktree add ../my-project.wt/fix-memory-leak -b fix/memory-leak重构分支 (refactor/)
git worktree add ../my-project.wt/refactor-database-layer -b refactor/database-layer热修复分支 (hotfix/)
git worktree add ../my-project.wt/hotfix-security-patch -b hotfix/security-patch与 IDE 集成
VS Code
- 打开 worktree 目录作为独立窗口
- 或者在同一窗口中添加多个文件夹到工作区
- 使用 "Open Recent" 快速切换
PyCharm / IntelliJ
- File → Open → 选择 worktree 目录
- 或使用 "Recent Projects" 切换
Cursor
- File → Open Folder → 选择 worktree 目录
- 使用 Cmd/Ctrl + R 快速切换最近项目
依赖管理
Node.js 项目
cd ~/projects/my-project.wt/feature-auth
# 如果 package-lock.json 或 yarn.lock 存在，使用它们
npm ci
# 或者重新安装依赖
npm install
# 使用独立端口运行，避免冲突
npm run dev -- --port 3001Python 项目
cd ~/projects/my-project.wt/feature-auth
# 创建独立虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或 venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
# 使用独立端口运行
python manage.py runserver 8001数据库
- 使用独立的数据库实例或 schema
- 或者在连接字符串中加入分支名作为后缀
- 使用 Docker 为每个 worktree 启动独立的数据库容器
同步更新
从主分支更新
# 在 worktree 目录中
cd ~/projects/my-project.wt/feature-auth
# 获取最新 main 分支更新
git fetch origin
# rebase 到最新 main
git rebase origin/main
# 或者 merge
git merge origin/main主仓库获取 worktree 的更改
# 在主仓库中
cd ~/projects/my-project
# 直接获取，无需切换分支
git fetch ../my-project.wt/feature-auth
# 或者查看 worktree 分支
git log feature/auth --oneline -5最佳实践
1. 定期清理
- 合并完成后立即删除 worktree
- 使用
git worktree prune清理残留引用 - 每周检查一次是否有孤立的 worktree 目录
2. 命名一致性
- worktree 目录名与分支名保持一致
- 使用 kebab-case（短横线连接）
- 包含类型前缀：feature-, bugfix-, refactor-, hotfix-
3. 环境隔离
- 每个 worktree 使用独立的端口
- 独立的数据库连接
- 独立的日志文件位置
- 独立的缓存目录
4. 自动化脚本
创建 worktree 脚本：
#!/bin/bash
# create-worktree.sh
PROJECT_NAME="my-project"
BRANCH_TYPE=$1 # feature, bugfix, refactor, hotfix
BRANCH_NAME=$2
if [ -z "$BRANCH_TYPE" ] || [ -z "$BRANCH_NAME" ]; then
echo "Usage: $0 <type> <name>"
echo "Example: $0 feature user-auth"
exit 1
fi
cd ~/projects/$PROJECT_NAME
FULL_BRANCH="$BRANCH_TYPE/$BRANCH_NAME"
WT_PATH="../${PROJECT_NAME}.wt/$BRANCH_TYPE-$BRANCH_NAME"
git worktree add $WT_PATH -b $FULL_BRANCH
cd $WT_PATH
# 自动安装依赖（如果是 Node 项目）
if [ -f "package.json" ]; then
npm install
fi
echo "Worktree created at: $WT_PATH"
echo "Branch: $FULL_BRANCH"清理 worktree 脚本：
#!/bin/bash
# clean-worktree.sh
PROJECT_NAME="my-project"
BRANCH_TYPE=$1
BRANCH_NAME=$2
if [ -z "$BRANCH_TYPE" ] || [ -z "$BRANCH_NAME" ]; then
echo "Usage: $0 <type> <name>"
exit 1
fi
cd ~/projects/$PROJECT_NAME
FULL_BRANCH="$BRANCH_TYPE/$BRANCH_NAME"
WT_PATH="../${PROJECT_NAME}.wt/$BRANCH_TYPE-$BRANCH_NAME"
# 确认分支已合并到 main
if git branch --merged main | grep -q "$FULL_BRANCH"; then
git worktree remove $WT_PATH
git branch -d $FULL_BRANCH
echo "Cleaned up: $FULL_BRANCH"
else
echo "Warning: Branch $FULL_BRANCH not merged to main yet!"
echo "Use -f flag to force remove, or merge first."
fi常见问题
Q: worktree 和主仓库的 .git 目录关系？
A: worktree 共享主仓库的 .git 目录，通过 .git 文件指向主仓库。
Q: 可以在 worktree 中创建新分支吗？
A: 可以，git checkout -b new-branch 会基于当前 worktree 的分支创建新分支。
Q: 如何处理冲突的端口号？
A: 每个 worktree 使用不同的端口（3000, 3001, 3002...），在配置文件中指定或使用环境变量。
Q: worktree 中的 node_modules 是独立的吗？
A: 是的，完全独立。这既是优点（隔离）也是缺点（占用磁盘空间）。
Q: 如何查看哪个 worktree 最旧？
ls -lt ~/projects/my-project.wt/检查清单
创建 worktree 时检查：
- 分支名符合规范 (feature/, bugfix/, refactor/, hotfix/)
- worktree 目录名与分支名对应
- 安装了必要的依赖
- 配置了独立的端口/数据库
- 在 IDE 中打开了正确的目录
清理 worktree 时检查：
- 所有更改已提交或 stash
- 分支已合并到 main
- CI/CD 检查通过
- 相关 issue/PR 已关闭
- 本地和远程分支都已删除
相关 Skills
- @git-master: 提交管理、rebase、历史搜索
- @frontend-ui-ux: 界面美化和优化