Back to Details

worktree-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Worktree Manager

Worktree 管理器

Skill para gestionar git worktrees siguiendo la estrategia de carpeta 
.worktrees/
dentro del repositorio.
用于在仓库内按照
.worktrees/
目录策略管理Git worktree的Skill

Cuando usar esta Skill

何时使用此Skill

  • Usuario pide crear un nuevo worktree o branch de trabajo
  • Usuario pide listar worktrees activos
  • Usuario pide limpiar worktrees despues de merge
  • Usuario menciona "worktree", "nuevo branch", "feature branch"
  • Usuario pide podar referencias huerfanas
  • 用户请求创建新的worktree或工作分支
  • 用户请求列出活跃的worktree
  • 用户请求在合并后清理worktree
  • 用户提到“worktree”、“新分支”、“功能分支”
  • 用户请求清理孤立引用

Estructura de Worktrees

Worktree 结构

~/Projects/<github|gitlab>/<project>/
├── .worktrees/                     # ignorado por .gitignore
│   ├── feature-x/                  # worktree para branch feature-x
│   └── bugfix-123/                 # worktree para branch bugfix-123
├── src/                            # archivos del repo (master/main)
└── .gitignore                      # debe incluir .worktrees/
~/Projects/<github|gitlab>/<project>/
├── .worktrees/                     # 被.gitignore忽略
│   ├── feature-x/                  # 对应feature-x分支的worktree
│   └── bugfix-123/                 # 对应bugfix-123分支的worktree
├── src/                            # 仓库文件（master/main分支）
└── .gitignore                      # 需包含.worktrees/

Proceso

流程

Paso 0: Verificar contexto

步骤0：检查上下文

Antes de cualquier operacion, verificar que estamos en un repositorio git:
bash
undefined
在执行任何操作之前，检查当前是否处于Git仓库中：
bash
undefined

Verificar que es un repo git

检查是否为Git仓库

git rev-parse --is-inside-work-tree
git rev-parse --is-inside-work-tree

Verificar rama actual (debe ser main o master para operaciones desde root)

检查当前分支（从根目录执行操作时必须为main或master分支）

git branch --show-current

---
git branch --show-current

---

Comandos Disponibles

可用命令

1. Setup Inicial

1. 初始设置

Ejecutar una vez por proyecto para habilitar worktrees:
bash
undefined
每个项目只需执行一次以启用worktree：
bash
undefined

Verificar si .worktrees/ esta en .gitignore

检查.worktrees/是否在.gitignore中

grep -q "^.worktrees/$" .gitignore 2>/dev/null || echo ".worktrees/" >> .gitignore
grep -q "^.worktrees/$" .gitignore 2>/dev/null || echo ".worktrees/" >> .gitignore

Crear carpeta .worktrees si no existe

如果不存在则创建.worktrees目录

mkdir -p .worktrees
mkdir -p .worktrees

Verificar estado

检查状态

cat .gitignore | grep worktrees

Si `.worktrees/` no estaba en `.gitignore`, hacer commit:

```bash
git add .gitignore
git commit -m "chore: ignore worktrees folder"
cat .gitignore | grep worktrees

如果`.worktrees/`不在.gitignore中，则提交更改：

```bash
git add .gitignore
git commit -m "chore: ignore worktrees folder"

2. Crear Worktree

2. 创建Worktree

Para crear un nuevo worktree con branch nuevo:
bash
undefined
创建带有新分支的worktree：
bash
undefined

Sintaxis: git worktree add .worktrees/<nombre-branch> -b <nombre-branch>

语法：git worktree add .worktrees/<分支名称> -b <分支名称>

git worktree add .worktrees/feature-nueva-funcionalidad -b feature-nueva-funcionalidad

El branch debe seguir convenciones:
- `feature/<descripcion>` o `feature-<descripcion>` para nuevas features
- `bugfix/<descripcion>` o `bugfix-<descripcion>` para correcciones
- `hotfix/<descripcion>` para arreglos urgentes
- `chore/<descripcion>` para tareas de mantenimiento
git worktree add .worktrees/feature-nueva-funcionalidad -b feature-nueva-funcionalidad

分支需遵循命名规范：
- `feature/<描述>` 或 `feature-<描述>` 用于新功能
- `bugfix/<描述>` 或 `bugfix-<描述>` 用于修复bug
- `hotfix/<描述>` 用于紧急修复
- `chore/<描述>` 用于维护任务

3. Listar Worktrees

3. 列出Worktree

Ver todos los worktrees activos:
bash
git worktree list
Output esperado:
/Users/user/Projects/github/mi-proyecto        abc1234 [main]
/Users/user/Projects/github/mi-proyecto/.worktrees/feature-x  def5678 [feature-x]
查看所有活跃的worktree：
bash
git worktree list
预期输出：
/Users/user/Projects/github/mi-proyecto        abc1234 [main]
/Users/user/Projects/github/mi-proyecto/.worktrees/feature-x  def5678 [feature-x]

4. Trabajar en Worktree

4. 在Worktree中工作

Despues de crear, navegar al worktree:
bash
cd .worktrees/<nombre-branch>
创建完成后，进入对应的worktree：
bash
cd .worktrees/<分支名称>

Trabajar normalmente...

正常工作...

hacer cambios...

进行更改...

Commit y push

提交并推送

git add . git commit -m "feat: descripcion del cambio" git push -u origin <nombre-branch>
undefined
git add . git commit -m "feat: 变更描述" git push -u origin <分支名称>
undefined

5. Cleanup despues de Merge

5. 合并后清理

Una vez que el PR fue mergeado, limpiar:
bash
undefined
PR合并完成后，进行清理：
bash
undefined

Desde el directorio raiz del proyecto (no desde el worktree)

从项目根目录执行（不要在worktree内执行）

Paso 1: Remover worktree

步骤1：移除worktree

git worktree remove .worktrees/<nombre-branch>
git worktree remove .worktrees/<分支名称>

Paso 2: Eliminar branch remoto (si no se elimino con el PR)

步骤2：删除远程分支（如果PR合并时未自动删除）

git push origin --delete <nombre-branch>
git push origin --delete <分支名称>

Paso 3: Eliminar branch local si existe

步骤3：如果存在本地分支则删除

git branch -d <nombre-branch>
undefined
git branch -d <分支名称>
undefined

6. Podar Referencias Huerfanas

6. 清理孤立引用

Limpiar referencias a worktrees que fueron eliminados manualmente:
bash
git worktree prune
清理手动删除的worktree引用：
bash
git worktree prune

Flujo Completo de Trabajo

完整工作流程

Ejemplo: Nueva Feature

示例：新功能开发

bash
undefined
bash
undefined

1. Asegurar que estamos en main/master actualizado

1. 确保当前处于已更新的main/master分支

git checkout main git pull origin main
git checkout main git pull origin main

2. Verificar setup (primera vez)

2. 检查初始设置（首次使用时）

grep -q "^.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
grep -q "^.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore

3. Crear worktree para la feature

3. 为该功能创建worktree

git worktree add .worktrees/feature-auth -b feature-auth
git worktree add .worktrees/feature-auth -b feature-auth

4. Ir al worktree

4. 进入worktree

cd .worktrees/feature-auth
cd .worktrees/feature-auth

5. Desarrollar, commit, push

5. 开发、提交、推送

... hacer cambios ...

... 进行更改 ...

git add . git commit -m "feat: add authentication module" git push -u origin feature-auth
git add . git commit -m "feat: 添加认证模块" git push -u origin feature-auth

6. Crear PR (desde GitHub CLI o web)

6. 创建PR（通过GitHub CLI或网页）

gh pr create --title "feat: add authentication module" --body "..."
gh pr create --title "feat: add authentication module" --body "..."

7. Despues del merge, volver al root y limpiar

7. 合并完成后，返回根目录并清理

cd ../.. # volver a raiz del proyecto git worktree remove .worktrees/feature-auth git push origin --delete feature-auth
undefined
cd ../.. # 回到项目根目录 git worktree remove .worktrees/feature-auth git push origin --delete feature-auth
undefined

Ejemplo: Bugfix Rapido

示例：快速修复Bug

bash
undefined
bash
undefined

Desde main actualizado

从已更新的main分支开始

git pull origin main
git pull origin main

Crear worktree para el fix

为修复创建worktree

git worktree add .worktrees/bugfix-login-error -b bugfix-login-error
git worktree add .worktrees/bugfix-login-error -b bugfix-login-error

Trabajar en el fix

进行修复工作

cd .worktrees/bugfix-login-error
cd .worktrees/bugfix-login-error

... fix ...

... 修复 ...

git add . && git commit -m "fix: resolve login error on mobile" git push -u origin bugfix-login-error
git add . && git commit -m "fix: 解决移动端登录错误" git push -u origin bugfix-login-error

Crear PR

创建PR

gh pr create --title "fix: resolve login error" --body "..."
gh pr create --title "fix: resolve login error" --body "..."

Despues del merge

合并完成后

cd ../.. git worktree remove .worktrees/bugfix-login-error

---
cd ../.. git worktree remove .worktrees/bugfix-login-error

---

Principios Clave

核心原则

PrincipioDescripcion
Worktrees son temporalesNo son casas permanentes, se eliminan despues del merge
Main siempre limpioEl repo principal siempre esta en main/master
Nombres descriptivosCarpeta del worktree = nombre del branch
Cleanup obligatorioSiempre limpiar despues del merge del PR
原则描述
Worktree 是临时的不是永久存在的，合并后需删除
Main分支始终保持干净主仓库始终处于main/master分支
名称具有描述性Worktree目录名称 = 分支名称
必须执行清理PR合并后务必进行清理

Troubleshooting

故障排除

Error: "worktree already exists"

错误："worktree already exists"

El worktree ya existe. Listar y verificar:
bash
git worktree list
ls -la .worktrees/
该worktree已存在。列出并检查：
bash
git worktree list
ls -la .worktrees/

Error: "branch already exists"

错误："branch already exists"

El branch ya existe. Opciones:
bash
undefined
该分支已存在。可选方案：
bash
undefined

Opcion 1: Usar branch existente (sin -b)

方案1：使用已存在的分支（不加-b参数）

git worktree add .worktrees/feature-x feature-x
git worktree add .worktrees/feature-x feature-x

Opcion 2: Eliminar branch viejo primero

方案2：先删除旧分支

git branch -D feature-x git worktree add .worktrees/feature-x -b feature-x
undefined
git branch -D feature-x git worktree add .worktrees/feature-x -b feature-x
undefined

Error: "is already checked out"

错误："is already checked out"

El branch esta checked out en otro lugar:
bash
undefined
该分支已在其他位置被检出：
bash
undefined

Ver donde esta el branch

查看分支所在位置

git worktree list
git worktree list

Remover el worktree anterior primero

先移除之前的worktree

git worktree remove .worktrees/<branch-name>
undefined
git worktree remove .worktrees/<分支名称>
undefined

Limpiar worktrees huerfanos

清理孤立的worktree

Si se eliminaron carpetas manualmente sin 
git worktree remove
:
bash
git worktree prune
git worktree list  # verificar que se limpio
如果手动删除了目录但未执行
git worktree remove
：
bash
git worktree prune
git worktree list  # 检查是否已清理

Preguntas al Usuario

向用户确认的问题

Antes de crear un worktree, preguntar:
  1. Nombre del branch: "Como quieres llamar al branch?" (sugerir formato 
    feature-*
    o 
    bugfix-*
    )
  2. Confirmar estructura: Si es primera vez, confirmar que se agregara 
    .worktrees/
    a 
    .gitignore
Antes de cleanup, confirmar:
  1. PR mergeado?: "El PR ya fue mergeado? Confirmar antes de eliminar el worktree."
  2. Branch remoto: "Eliminar tambien el branch remoto?"
创建worktree之前，需询问：
  1. 分支名称：“你想给分支起什么名字？”（建议使用
    feature-*
    或
    bugfix-*
    格式）
  2. 确认结构：如果是首次使用，确认是否将
    .worktrees/
    添加到.gitignore中
清理之前，需确认：
  1. PR是否已合并？：“PR是否已完成合并？请确认后再删除worktree。”
  2. 远程分支：“是否同时删除远程分支？”