git-worktree-manager — git-worktree-管理器

Git Worktree 管理器

Tier: POWERFUL Category: Engineering DomAIn: Parallel Development & Branch Isolation

Overview

Use this 技能 to 运行 parallel feature work safely with Git worktrees. It standardizes branch isolation, port allocation, 环境 同步, and 清理up so each worktree behaves like an independent local 应用 without stepping on another branch.

This 技能 is 优化d for multi-代理 工作流s where each 代理 or terminal 会话 owns one worktree.

Core Capabilities 创建 worktrees from new or existing branches with deterministic naming Auto-allocate non-conflicting ports per worktree and persist as签名ments Copy local 环境 files (.env) from mAIn repo to new worktree Optionally 安装 dependencies based on lockfile 检测ion 检测 stale worktrees and uncommitted changes before 清理up Identify merged branches and safely 移除 outdated worktrees When to Use You need 2+ concurrent branches open locally You want isolated dev servers for feature, hotfix, and PR 验证 You are working with multiple 代理s that must not 分享 a branch Your current branch is blocked but you need to ship a quick fix now You want repeatable 清理up instead of ad-hoc rm -rf operations Key 工作流s

• 创建 a Fully-Prepared Worktree

Default strategy is base + (索引 stride) with collision 检查s:

应用: 3000 Postgres: 5432 Redis: 6379 Stride: 10

See port-allocation-strategy.md for the full strategy and edge cases.

Script Interfaces python scripts/worktree_管理器.py --help 创建/列出 worktrees Allocate/persist ports Copy .env* files Optional dependency 安装ation python scripts/worktree_清理up.py --help Stale 检测ion by age Dirty-状态 检测ion Merged-branch 检测ion Optional safe removal

机器人h 工具s support stdin JSON and --输入 file mode for 自动化 流水线s.

Common Pitfalls Creating worktrees inside the mAIn repo directory Reusing localhost:3000 across all branches Sharing one database URL across isolated feature branches Removing a worktree with uncommitted changes For获取ting to p运行e old metadata after branch deletion Assuming merged 状态 without 检查ing agAInst the tar获取 branch Best Practices One branch per worktree, one 代理 per worktree. Keep worktrees short-lived; 移除 after merge. Use a deterministic naming pattern (wt-). Persist port m应用ings in file, not memory or terminal notes. 运行 清理up 扫描 weekly in active repos. Use --格式化 json for machine flows and --格式化 text for human review. Never force-移除 dirty worktrees unless changes are intentionally discarded. 验证 检查列出

Before clAIming 设置up complete:

git worktree 列出 shows expected path + branch. .worktree-ports.json exists and contAIns unique ports. .env files copied 成功fully (if present in source repo). Dependency 安装 command exits with code 0 (if enabled). 清理up 扫描 报告s no unintended stale dirty trees. References port-allocation-strategy.md docker-compose-patterns.md README.md for quick 启动 and 安装ation detAIls Decision Matrix

Use this quick selector before creating a new worktree:

Need isolated dependencies and server ports -> 创建 a new worktree Need only a quick local diff review -> stay on current tree Need hotfix while feature branch is dirty -> 创建 dedicated hotfix worktree Need ephemeral reproduction branch for bug triage -> 创建 temporary worktree and 清理up same day Operational 检查列出 Before Creation Confirm mAIn repo has 清理 baseline or intentional WIP commits. Confirm tar获取 branch naming convention. Confirm required base branch exists (mAIn/develop). Confirm no reserved local ports are already occupied by non-repo 服务s. After Creation