SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsworktree

worktree

General & other

View repository

Updated 10-15 19:58

About this skill

/worktree — Git Worktree lifecycle management

Manage worktree creation, status queries, and cleanup. The unified storage location is ~/Documents/<repo>-<name>。

Subcommand parsing

From $ARGUMENTS determine the subcommand:

Input Subcommand
(empty) or status status
create <name> create
cleanup cleanup
prune prune

Shared: Detect Repo information

Before starting any subcommand, first obtain repo information:

REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")

If not in a git repo, prompt the user to switch to a git repo directory.

status (default)

List all worktrees and their status.

Steps:

  1. git worktree list --porcelain Get all worktrees

  2. Exclude the main worktree (i.e. REPO_ROOT itself)

  3. For each worktree:

    • Get the path and branch name
    • gh pr list --head <branch> --state all --json number,state,mergedAt --limit 1 Check PR status
    • du -sh <path> Get disk usage
    • Determine the path type:
      • ~/Documents/<repo>-* → standard path (no marker)
      • .claude/worktrees/ → [legacy]
      • /tmp/ or /private/tmp/ → [non-standard]
      • Other → [non-standard]

  4. Consistency check(set difference between manifest and actual directory):

    • For each path returned by git worktree list , run test -d <path> to confirm the directory actually exists
    • If a path is in the git list but the directory does not exist → mark [orphan], and show a warning at the end of the output: 
      警告：偵測到 N 個孤立 worktree metadata（目錄已不存在但 git 仍有紀錄）
執行 `/worktree prune` 清理孤立 metadata。

Output format:

Repo: <repo-name>  |  Base: <current-branch>  |  N worktrees (+ main)

Path                                    Branch                          PR      State    Disk
─────────────────────────────────────────────────────────────────────────────────────────────
~/Documents/<repo>-<name>               worktree-<name>                 —       no PR    196M
~/Documents/<repo>-<name2>              feat/<name2>                    #1234   MERGED   1.8G
.claude/worktrees/<name3>               worktree-<name3>                #5678   OPEN     800M  [legacy]

Tip: 有 MERGED/CLOSED 的 PR → `/worktree cleanup`

The Tip line is shown only when there are worktrees that can be cleaned up.

create

Create a new worktree.

Steps:

  1. From $ARGUMENTS parse the name (the part aftercreate )

  2. Compute the path:~/Documents/<repo>-<name>

  3. Compute the branch name:worktree-<name>

  4. Check whether the path already exists (test -d) → if it exists, prompt and abort

  5. Check whether the branch already exists (git branch --list) → if it exists, prompt and abort

  6. Use AskUserQuestion to ask for the base branch:

    Which branch should the worktree be created from?

    1. (current branch)
    2. master
    3. Other(please specify)

  7. Create the worktree:

    git worktree add -b worktree-<name> ~/Documents/<repo>-<name> <base-branch>

  8. Output the result:

    Worktree 已建立：
- 路徑：~/Documents/<repo>-<name>
- 分支：worktree-<name>
- Base：<base-branch>

開新 Claude Code session 在該目錄開發：
cd ~/Documents/<repo>-<name> && claude

cleanup

Automatically detect and clean up worktrees with merged/closed PRs.

Single repo (interactive): executed by the skill according to the following steps; Cross-repo batch: directly call ~/Documents/agent-skills/scripts/worktree-cleanup.sh(the script is in the root directory of the agent-skills repo, not under this skill directory; dry-run by default; only--fetch --apply takes action;--du also calculates disk usage;--kill-blockers cleans up the occupying process as well;--root overrides the scan root directory). In addition to PR status and a clean worktree, the script also verifies "whether there are unpushed commits" and "whether any process has that worktree as its cwd", andnever deletes the branch; see the script header comments for usage and hard rules.

Steps:

  1. git worktree list --porcelain List all non-main worktrees

  2. For each worktree, determine whether it meets the cleanup conditions:

    • First run gh pr list --head <branch> --state all --json number,state,mergedAt --limit 1 Query PR status
    • If gh command fails (non-zero exit code) or returns empty result → PR status marked as [unknown]，Do not silently skip, still include in cleanup candidates and show in the table [unknown](Basis: ITIL CMDB Reconciliation — query failures must be explicitly marked, not implicitly ignored)
    • PR status is MERGED or CLOSED → meets cleanup criteria
    • PR status is [unknown] → include in cleanup candidates, mark in table [unknown], let the user decide
    • or no PR and branch already merged into base (git branch --merged <base> | grep <branch>）

  3. For worktrees meeting the criteria, check for dirty directories:

    • git -C <path> status --porcelain If there is output → mark [dirty] and warn

  4. If there are no worktrees to clean up → prompt "No worktrees need cleanup" and exit

  5. Display cleanup list, use AskUserQuestion to confirm:

    The following worktrees meet cleanup criteria:

    Path Branch PR State Disk Note
    ~/Documents/- worktree- #1234 MERGED 800M
    .claude/worktrees/ worktree- — merged 200M [legacy]
    ~/Documents/- worktree- #5678 CLOSED 1.2G [dirty] ⚠️

    Confirm cleanup? (dirty worktrees will be skipped)

    1. Confirm — clean up the above worktrees (skip dirty)
    2. Clean up all — include dirty worktrees (uncommitted changes will be lost)
    3. Cancel

  6. Execute according to user's choice:

    git worktree remove <path>

    Only remove the worktree directory, do not delete the branch(consistent with scripts/worktree-cleanup.sh hard rule 1): when a worktree is accidentally deleted, the branch ref is the only lifeline,git worktree remove itself does not touch the branch. Only when the user explicitly requests cleaning the branch, additionally list branch names one by one for confirmation, and only use git branch -d(not -D), and skip long-lived branches (hotfix / develop* / dev* / release-*）。

  7. Operation verification（expected vs. actual count）：

    • After deletion, re-run git worktree list --porcelain, confirm that the deleted paths no longer appear in the list

    • Compare item by item against the cleanup list (manifest):

      Path Expected result Actual result
      ~/Documents/- Removed PASS / FAIL

    • If any path is still in the list → output [FAIL] and prompt to manually run git worktree prune

  8. Report results:

    已清理 N 個 worktree，回收 X 磁碟空間。
驗證：N/N 個 worktree 已從 git 列表移除。

prune

Clean up orphaned worktree metadata (worktree directory has been manually deleted but the git record remains).

Steps:

  1. git worktree list --porcelain Check whether each worktree path exists
  2. If there is orphaned metadata, display the list
  3. Run git worktree prune
  4. Report cleanup results