Development | ShareChiWai Notes

Git Worktree Cleanup Guide

Wed, 18 Mar 2026 00:00:00 +0000

當你使用 GitHub Copilot 或者其他工具建立 git worktree 之後，隨著時間推移，worktree 會越積越多。呢篇文章會教你點樣檢查邊啲 worktree 已經合併，同埋點樣批量清理佢哋。

點解要清理 Worktree？

Worktree 唔會自動刪除，即使相關嘅 Pull Request 已經合併。如果你唔定期清理：

Worktree 會堆積，佔用磁碟空間
你會繼續遇到 “branch is already used by worktree” 錯誤
git worktree list 會變得越來越長，難以管理

檢查邊個 Worktree 已經合併

方法一：手動檢查

# 1. 列出所有 worktree
git worktree list

# 2. 檢查邊啲 branch 已經合併到 main
git branch --merged main

對比兩個輸出，你就可以知道邊個 worktree 係安全可以刪除嘅。

方法二：一覽表

用呢個命令顯示每個 worktree 嘅合併狀態：

git worktree list --porcelain | grep -E "^(worktree|branch)" | while read line; do
 if [[ $line == worktree* ]]; then
 path=${line#worktree }
 else
 branch=${line#branch }
 branch_name=${branch#refs/heads/}
 if git branch --merged main | grep -q "$branch_name"; then
 echo "✓ MERGED: $path ($branch_name)"
 else
 echo "✗ ACTIVE: $path ($branch_name)"
 fi
 fi
done

輸出會好似咁：

✓ MERGED: C:/Users/chi/Documents/git/copilot-worktrees/frontend/task-1 (sharechiwai-task-1)
✗ ACTIVE: C:/Users/chi/Documents/git/copilot-worktrees/frontend/task-2 (sharechiwai-task-2)
✓ MERGED: C:/Users/chi/Documents/git/copilot-worktrees/frontend/task-3 (sharechiwai-task-3)

標記 ✓ MERGED 嘅就係可以安全刪除嘅 worktree。

刪除 Worktree 同 Branch

重要概念

git worktree remove 只會刪除 worktree，唔會刪除 branch。你需要分開處理：

# 1. 刪除 worktree（刪除工作目錄）
git worktree remove C:/Users/chi/Documents/git/copilot-worktrees/frontend/sharechiwai-task-1

# 2. 刪除 branch（刪除 branch 引用）
git branch -d sharechiwai-task-1

# 如果 branch 未合併但你想強制刪除（小心使用）
git branch -D sharechiwai-task-1

批量清理腳本（Bash）

呢個腳本會自動刪除所有已合併嘅 worktree 同 branch：

#!/bin/bash
# 刪除所有已合併到 main 嘅 worktree

git worktree list --porcelain | awk '
/^worktree / { path=$2 }
/^branch / {
 branch=$2
 gsub("refs/heads/", "", branch)
 print path "|" branch
}' | while IFS='|' read -r wt_path wt_branch; do
 # 跳過 main/master branch
 if [[ "$wt_branch" == "main" || "$wt_branch" == "master" ]]; then
 continue
 fi

 # 檢查 branch 是否已合併
 if git branch --merged main | grep -q "$wt_branch"; then
 echo "Removing merged worktree: $wt_path ($wt_branch)"
 git worktree remove "$wt_path"
 git branch -d "$wt_branch"
 fi
done

# 清理 stale references
git worktree prune
echo "Cleanup complete!"

批量清理腳本（PowerShell）

Windows 用戶可以用呢個 PowerShell 版本：

# 刪除所有已合併到 main 嘅 worktree

$worktrees = git worktree list --porcelain
$currentPath = ""
$toRemove = @()

foreach ($line in $worktrees) {
 if ($line -match "^worktree (.+)") {
 $currentPath = $matches[1]
 }
 elseif ($line -match "^branch refs/heads/(.+)") {
 $branch = $matches[1]

 # 跳過 main/master
 if ($branch -eq "main" -or $branch -eq "master") { continue }

 # 檢查是否已合併
 $merged = git branch --merged main
 if ($merged -match $branch) {
 $toRemove += [PSCustomObject]@{
 Path = $currentPath
 Branch = $branch
 }
 }
 }
}

foreach ($item in $toRemove) {
 Write-Host "Removing: $($item.Path) ($($item.Branch))"
 git worktree remove $item.Path
 git branch -d $item.Branch
}

git worktree prune
Write-Host "Cleanup complete!"

最佳實踐

1. 定期清理

建議每次合併 PR 之後都檢查下同清理 worktree。你可以將呢個加入你嘅 post-merge routine。

2. 建立 Alias

喺 .gitconfig 加入 alias 方便清理：

[alias]
 wt-cleanup = "!f() { git worktree list --porcelain | awk '/^worktree/{p=$2}/^branch/{b=$2;gsub(\"refs/heads/\",\"\",b);print p\"|\"b}' | while IFS='|' read p b; do [[ \"$b\" != \"main\" && \"$b\" != \"master\" ]] && git branch --merged main | grep -q \"$b\" && echo \"Removing $p ($b)\" && git worktree remove \"$p\" && git branch -d \"$b\"; done && git worktree prune && echo \"Cleanup complete!\"; }; f"

之後只需要行 git wt-cleanup 就可以自動清理。

3. 清理前檢查

執行批量刪除之前，建議先 review 下個 list：

# 先睇下邊個會被刪除
git worktree list --porcelain | grep -E "^(worktree|branch)" | while read line; do
 if [[ $line == worktree* ]]; then
 path=${line#worktree }
 else
 branch=${line#branch }
 branch_name=${branch#refs/heads/}
 if git branch --merged main | grep -q "$branch_name"; then
 echo "Will remove: $path ($branch_name)"
 fi
 fi
done

確認無問題先至執行清理腳本。

總結

清理 git worktree 係保持 repository 整潔嘅重要步驟。用 git branch --merged 檢查邊個 worktree 已經合併，然後用 git worktree remove 同 git branch -d 分別刪除 worktree 同 branch。你可以用上面嘅腳本自動化呢個過程，節省時間同避免錯誤。

記住：worktree 唔會自動刪除，你需要手動清理。養成定期清理嘅習慣，可以避免好多不必要嘅問題。

fatal: branch is already used by worktree at

Mon, 16 Mar 2026 00:00:00 +0000

最近常常使用 GitHub Copilot App 去幫我執行 Hermes Agent 幫我 create 既 JIRA Task, 當Githut Copilot App 執行完, 建立了 Pull Request 之後我想係working folder 上試下個 pull request 時往往都係會出現這個 error message, 唔比我checkout 這個branch

fatal: 'sharechiwai-task-1' is already used by worktree at 'C:/Users/chi/Documents/git/copilot-worktrees/frontend/sharechiwai-super-fiesta'

點解會出現這個錯誤？

GitHub Copilot 使用 git worktree 功能嚟為每個 task 建立獨立嘅工作目錄。Git worktree 允許你同時 checkout 多個 branch 到唔同嘅目錄，但有一個限制：同一個 branch 唔可以同時被多個 worktree checkout。

當你嘗試喺 main working folder checkout 同一個 branch 時，Git 就會報呢個錯誤，因為個 branch 已經被 Copilot 建立嘅 worktree 佔用咗。

解決方案

方法一：刪除 Copilot 建立嘅 worktree

如果你唔再需要 Copilot 嘅 worktree，可以刪除佢：

# 列出所有 worktree
git worktree list

# 刪除特定 worktree
git worktree remove C:/Users/chi/Documents/git/copilot-worktrees/frontend/sharechiwai-super-fiesta

# 如果 worktree 目錄已經唔存在，用 prune 清理
git worktree prune

刪除 worktree 之後，你就可以正常 checkout 個 branch 啦。

方法二：直接喺 Copilot worktree 入面工作

如果你想在 Copilot 建立嘅環境繼續工作，可以直接 cd 入去個 worktree 目錄：

cd C:/Users/chi/Documents/git/copilot-worktrees/frontend/sharechiwai-super-fiesta

咁樣你就可以喺嗰度繼續開發，唔使 checkout branch。

方法三：Checkout 到另一個 branch

如果你只想喺 main working folder 做其他嘢，可以 checkout 去另一個 branch：

git checkout main
# 或者 checkout 去其他 branch
git checkout another-branch

方法四：使用 –ignore-other-worktrees 參數

如果你確實需要喺 main working folder checkout 個 branch，可以用 --ignore-other-worktrees 參數強制 checkout：

git checkout --ignore-other-worktrees sharechiwai-task-1

呢個方法會忽略其他 worktree 嘅衝突，直接 checkout 個 branch。不過要小心，因為咁樣會導致同一個 branch 同時被多個 worktree checkout，可能會引起衝突問題。建議只係短暫使用，完成工作後盡快清理 worktree。

預防方法

為咗避免呢個問題，建議：

完成 task 後清理 worktree：當 Copilot 完成 task 並且你已經 merge 咗 PR，記得刪除相關嘅 worktree
定期 prune worktree：用 git worktree prune 清理已經唔存在嘅 worktree 引用
用 git worktree list 檢查：checkout branch 之前先檢查下有冇其他 worktree 用緊個 branch

總結

呢個錯誤係因為 Git worktree 嘅限制做成嘅。GitHub Copilot 用 worktree 嚟隔離唔同 task 嘅工作環境，但當你想喺 main working folder 用同一個 branch 時就會衝突。最簡單嘅解決方法就係刪除唔再需要嘅 worktree，或者直接用 Copilot 建立嘅 worktree 目錄繼續工作。

延伸閱讀

如果你想了解點樣批量清理已合併嘅 worktree，同埋點樣用腳本自動化清理過程，可以參考。