git-worktree-manager

git-worktree-manager skill 概覽

git-worktree-manager 的用途

git-worktree-manager 是一個工程向 skill，用來管理多個本機 Git worktree，避免分支、連接埠、環境檔與清理流程互相衝突。它結合操作指引與 Python 輔助腳本，可建立已準備好的 worktree、分配可預期的連接埠、複製本機環境檔、視需要安裝依賴套件，並在移除前檢查過期的 worktree。

當一般 git worktree 指令不夠用、而每個分支都需要像獨立可執行的應用程式一樣運作時，就適合使用這個 skill。

最適合平行 Git 工作流程

最適合的使用者，是會同時開著兩個以上分支的開發者、技術負責人，或 coding-agent 操作者：例如功能開發、hotfix、PR review、遷移測試，或多 agent 協作實作。git-worktree-manager for Git Workflows 特別適合每個 agent 或 terminal session 都應該擁有自己的分支與隔離 runtime，而不是共用同一份 checkout 的情境。

如果你只是偶爾切換分支、不需要跑本機服務，或團隊已經有成熟的內部 worktree wrapper，這個 skill 的價值就相對有限。

安裝前必看的關鍵差異

它的實務價值不只是「建立一個 worktree」。這個 skill 會補上一套可重複執行的約定，包括：

• 可預期的 worktree 命名與分支建立方式
• 不互相重疊的 app、database、Redis 連接埠分配
• .env、.env.local、.env.development 與 .envrc 同步
• 依常見 lockfile 偵測是否需要安裝依賴套件
• 檢查過期、dirty，以及已合併分支的清理條件
• 針對每個 worktree 隔離服務的 Docker Compose 模式

因此，git-worktree-manager skill 比一般只談 Git worktree 的 prompt 更偏向實際營運與落地流程。

如何使用 git-worktree-manager skill

git-worktree-manager 安裝選項

如果你使用 Claude 風格的 skills 設定，且你的 skill manager 支援，可直接從 repository 安裝：

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

若要手動安裝，請從以下位置複製 skill 目錄：

engineering/skills/git-worktree-manager

放到你的本機 skills 資料夾，例如 ~/.claude/skills/git-worktree-manager、~/.codex/skills/git-worktree-manager，或其他相容的 agent skill 目錄。安裝後，確認這些檔案都存在：SKILL.md、README.md、scripts/worktree_manager.py、scripts/worktree_cleanup.py，以及 references/ 底下的兩個檔案。

先閱讀這些檔案

若想快速導入，建議依照以下順序閱讀：

1. README.md：了解指令形式與工具清單。
2. SKILL.md：了解預期工作流程與適用情境。
3. references/port-allocation-strategy.md：在調整服務連接埠前先看。
4. references/docker-compose-patterns.md：如果你的應用程式使用 Compose，請先閱讀。
5. scripts/worktree_manager.py 與 scripts/worktree_cleanup.py：在 production repository 信任自動化前，先檢查腳本內容。

這很重要，因為這些腳本會操作真實 checkout、複製 env 檔，也可能安裝依賴套件。在大型 monorepo 或含有敏感本機設定的 repo 上執行前，務必先審查預設行為。

git-worktree-manager 實務用法

典型的建立與準備流程如下：

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/api-hardening \
  --name wt-api-hardening \
  --base-branch main \
  --install-deps \
  --format text

清理前的檢查流程如下：

python scripts/worktree_cleanup.py \
  --repo . \
  --stale-days 14 \
  --format text

兩個工具都支援透過 --input <json-file> 或 stdin 提供 JSON input，適合用於自動化。建議先要求 agent 產出 command plan，並在你確認 repo path、branch name、base branch、依賴安裝行為與清理政策後，再執行腳本。

讓輸出更好的 prompt 寫法

較弱的 prompt：

Set up a worktree for my feature.

較好的 prompt：

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.

這樣能提供 skill 足夠資訊來選擇分支策略、避免 port collision、維持 .env* 檔案操作的安全性，並把規劃與執行分開。

git-worktree-manager skill 常見問題

git-worktree-manager 只適合 AI agents 嗎？

不是。這個 skill 針對 multi-agent 工作流程做了最佳化，但其中的腳本與約定對人類開發者也很實用。主要好處是可重複性：每個 worktree 都有可預期的 branch、directory、ports、複製好的 env files，以及 cleanup review，而不是靠臨時的 shell history。

這和單純使用 git worktree 有什麼不同？

單純的 git worktree add 只會建立另一份 checkout，並不會解決本機 app 衝突。git-worktree-manager 補上周邊工作流程：port blocks、.worktree-ports.json、環境檔複製、可選的依賴安裝、Docker Compose 隔離建議，以及針對過期或已合併分支的清理檢查。

初學者可以安全使用嗎？

可以，前提是把它當作有引導的工作流程，而不是盲目執行指令的工具。初學者應先執行 list/review 類操作、使用 --format text、避免自動移除，並在執行前檢查產生的指令。cleanup script 會檢查 dirty worktrees，但你仍然需要理解哪些分支可以安全刪除。

什麼情況不應該使用這個 skill？

如果你的 repository 有特殊環境處理方式、絕不能被複製的 secrets、非標準依賴安裝流程，或服務連接埠由內部平台管理，就不要直接照原樣使用。在這些情況下，應把 git-worktree-manager guide 當作起始模式，先客製腳本或 prompts 再導入。

如何改進 git-worktree-manager skill

提供更完整的 git-worktree-manager repo 脈絡

輸入越完整，產出的 worktree plan 越安全。請包含：

• 絕對 repo path
• 目標 branch 與 base branch
• 希望使用的 worktree directory name
• package manager 或 lockfile 預期
• 需要連接埠的服務
• 是否允許複製 .env* files
• 是否允許安裝依賴套件
• cleanup age threshold，以及用於 merge checks 的 base branch

這可以減少猜測，避免 agent 套用不符合你 app 的預設值。

調整 port 與 Docker Compose 約定

參考策略使用 app 3000、Postgres 5432、Redis 6379 等預設 base，並以每個 worktree 10 的 stride 遞增。如果你的 stack 有更多服務，請保留更大的連續區段。如果你在 worktree 外也有本機基礎服務，請調整 base ports 以避免全域衝突。

在 Docker Compose 方面，建議使用每個 worktree 專屬的 overrides、由 .env 驅動的 ports，以及唯一的 project names，例如：

docker compose -p myapp_wt_auth up -d

這能避免不同分支之間發生 container、network、volume 與 database 衝突。

留意常見失敗模式

最常見的問題包括：複製到 secrets、重複使用預設 database ports、不相容 migrations 卻共用 Docker volumes、在錯誤 runtime 中安裝依賴，以及刪除仍有未提交工作的 worktree。每次執行後，請要求 agent 回報 dirty status、已複製的 env files、選定的 ports，以及 install actions。

清理時，先從 review-only output 開始。只有在確認某個 worktree 已過期、乾淨，且已合併到預期的 base branch 後，才啟用移除。

根據第一次輸出迭代

拿到第一版 plan 或 command 後，與其從頭開始，不如要求一次聚焦修正：

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

這樣可以讓 skill 持續貼近 repository 的真實限制，同時提升安全性與可重現性。