git-worktree-tidy

git-worktree-tidy

ベアリポジトリ＋ワークツリー構成を定期的に整理します。origin をフェッチし、消失したブランチと孤立したワークツリーをプルーニングして、重要なローカルブランチをファストフォワードします。

使用する状況

ワークツリーベースのリポジトリで、ユーザーから「フェッチしてプルーニング」「古いブランチ／ワークツリーを整理」「main/dev を最新の状態に更新」と依頼された場合に使用します。

絶対ルール

• 破壊的な操作（ワークツリーの削除、ブランチの削除）には、すべてユーザーの確認が必要です。対象の一覧をすべて提示し、返答を待ってください。
• 未コミットの変更があるワークツリーを、明示的な承認なしに強制削除してはいけません。変更があるワークツリーは別に明示してください。
• ブランチの更新には --ff-only を使用してください。ff-only が失敗した場合は停止し、ユーザーに確認してください。
• ブランチ／ワークツリーの管理コマンドは、.bare ディレクトリ（またはリポジトリのルート）から実行してください。
• git rev-list origin/main..<branch> や git merge-base --is-ancestor だけを根拠に、「マージ済み／出荷済み」と判断してはいけません。スカッシュマージやリベースマージでは、作業内容が新しい SHA のもとに取り込まれるため、完全に出荷済みのブランチでも「main に含まれない」コミットや祖先でない tip が表示されます。消失したブランチを未マージと分類する前に、フォージの PR マージ状態（手順 3a）で出荷状況を確認してください。

ワークフロー

1) ベアリポジトリのルートを特定する

ベアリポジトリのディレクトリを特定します。

• cwd に .bare/ が含まれている場合は、そこを使用します
• それ以外の場合：git rev-parse --git-common-dir

ブランチとワークツリーの管理コマンドはすべて、このディレクトリから実行します。

2) フェッチ＋プルーニング

git fetch --prune origin

プルーニングされた内容（削除されたリモート追跡ブランチ、更新された ref）を報告します。

3) 古いブランチを見つける

git branch -vv | grep ': gone]'

上流ブランチが消失しているブランチ名を収集します。

3a) 出荷状況を確認する（上流の消失 ≠ マージ済み）

上流ブランチが削除されていても（「gone」）、作業が出荷された証拠にはなりません。また、ここでは Git の祖先関係は信頼できません。スカッシュマージやリベースマージでは、作業内容が新しい SHA のもとに取り込まれるため、完全に出荷済みのブランチでも「main に含まれない」コミットや祖先でない tip が表示されます。削除する前にフォージで確認してください。実際の作業が失われるのは、消失していて未マージのブランチだけです。

上流が消失したブランチごとに確認します（GitHub の例です。使用しているフォージの CLI に置き換えてください）。

# Was there a merged PR from this head?
gh pr list --state all --head <branch> \
  --json number,state,mergedAt,mergeCommit \
  --jq '.[] | "#\(.number) \(.state) merged=\(.mergedAt // "no")"'

# If merged, confirm nothing was added to the branch AFTER the merge:
# the local tip should equal the PR head at merge.
gh pr view <pr> --json commits --jq '.commits[-1].oid'   # vs: git rev-parse <branch>

消失した各ブランチを分類します。

• マージ済み（確認済み） — MERGED 状態の PR が存在し、その head == ローカルの tip → 出荷済みなので、安全に削除できます。
• 要注意 — マージ済み PR がない、または tip にマージ後の日付のコミットがある（git show -s --format=%ci <tip>）→ 実際に未出荷の作業があります。明示し、明確な承認なしに削除しないでください。

gh／フォージの CLI が利用できない場合は、その旨を伝え、確認できないブランチはマージ済みと推測せず、要注意として扱ってください。

4) 古いワークツリーを見つける

git worktree list
git worktree prune --dry-run

ワークツリーを消失ブランチの一覧と照合します。古いワークツリーそれぞれの変更状態を確認します。

cd <worktree-path> && git status --short

分類します。

• クリーン＋消失：安全に削除できます
• 変更あり＋消失：ユーザーの確認が必要です
• プルーニング可能なメタデータ：孤立したワークツリーのエントリ（ディレクトリはすでに存在しません）

5) 削除を確認する

次の形式で概要テーブルを提示します。

Stale worktrees to remove:
  <path> (<branch>) [clean]
  <path> (<branch>) [dirty — N uncommitted changes]

Stale branches:
  <branch>  [merged — PR #N, safe to delete]
  <branch>  [AT RISK — no merged PR / commits after merge; review first]

Prunable worktree metadata:
  <entry>

ユーザーが出荷状況を確認したうえで判断できるよう、要注意のブランチを明確に示してください。続行する前にユーザーの確認を待ってください。

6) 古いワークツリーを削除する

確認されたワークツリーごとに、次を実行します。

git worktree remove <name>

削除に失敗した場合（変更がある場合）は報告し、ユーザーが強制削除を承認していない限りスキップしてください。

7) 古いブランチを削除する

git branch -D <branch1> <branch2> ...

8) ワークツリーのメタデータをプルーニングする

git worktree prune -v

9) 重要なブランチを更新する

main、dev、またはその他の重要なブランチ用に専用のワークツリーがあるブランチを特定します（ユーザーが指定する場合もあります）。それぞれについて、次を実行します。

cd <worktree-path> && git pull --ff-only origin <branch>

ff-only が失敗した場合は、ブランチの分岐を報告して、対応をユーザーに確認してください。

10) 最終ステータス

削除したもの、更新したもの、スキップしたものがあれば、その概要を示します。