worktree-status

worktree-status

Report the status of every git worktree for the current project, covering dirty state and merge status.

When to use

• User asks "which worktrees can I clean up?"
• User asks "what's the status of my worktrees / branches?"
• Before batch-cleaning worktrees, to avoid losing uncommitted work

Procedure

1. Pull latest main (MANDATORY)

You MUST pull latest main before any status checks. Without this, merge detection (both ancestry and content diff) will produce stale results and you may mistakenly conclude a branch is not merged.

cd "$(git rev-parse --show-toplevel)" && git pull origin main

2. Collect worktree info

PROJECT_DIR="$(git rev-parse --show-toplevel)"

for wt in $(git worktree list --porcelain | grep "^worktree " | sed 's/^worktree //' | grep -v "$PROJECT_DIR$"); do
  branch=$(git -C "$wt" branch --show-current 2>/dev/null)
  [ -z "$branch" ] && branch="(detached)"
  name=$(basename "$wt")

  # dirty?
  if [ -z "$(git -C "$wt" status --short 2>/dev/null)" ]; then
    dirty="clean"
  else
    dirty="DIRTY"
  fi

  # merged into origin/main?
  # NOTE: This project uses squash merges exclusively. `git merge-base
  # --is-ancestor` does NOT detect squash-merged branches. Always follow
  # up with a content diff (step 3) for branches that appear "not merged".
  if [ "$branch" != "(detached)" ]; then
    if git merge-base --is-ancestor "$branch" origin/main 2>/dev/null; then
      merged="merged"
    else
      merged="not merged (verify with content diff)"
    fi
  else
    merged="n/a"
  fi

  echo ""
  echo "[$name]  branch=$branch  $dirty  $merged"
  if [ "$dirty" = "DIRTY" ]; then
    git -C "$wt" status --short 2>/dev/null | sed 's/^/  /'
  fi
done

3. Detect squash-merged branches (content diff)

For any branch that shows "not merged", check whether the branch's changes are already in main. The correct method is:

1. Find the files the branch actually changed (relative to merge-base).
2. For each changed file, compare the branch version with main. If all files are identical, the branch was squash-merged.

⚠️ Do NOT use git diff origin/main <branch> — that compares the two tips directly, so commits added to main after the branch diverged will show up as false differences.

BRANCH="<branch>"
BASE=$(git merge-base origin/main "$BRANCH")

# List files the branch touched
FILES=$(git diff --name-only "$BASE" "$BRANCH")

# Compare each file between branch and current main
for f in $FILES; do
  d=$(git diff "$BRANCH" origin/main -- "$f" | wc -l)
  if [ "$d" != "0" ]; then
    echo "❌ $f — differs"
  else
    echo "✅ $f — identical in main"
  fi
done
# All ✅ = squash-merged

4. (Optional) Check for associated tmux sessions

Only run this if tmux is available and relevant (e.g. worktrees were created by codex-worker or similar tooling). Skip if not applicable.

tmux ls 2>/dev/null | grep -E 'codex-worker|<other-pattern>' || true

5. Present results

Always present results as a Markdown table. Every worktree must appear as a row. Never use abbreviated or prose-only summaries.

Worktree	Branch	Dirty	Merged	Can clean?
example-wt	feat-foo	✅ clean	✅ squash-merged	✅
another-wt	fix-bar	⚠️ 3 files	❌ not merged	❌ dirty + not merged
detached-wt	(detached)	⚠️ 14 files	n/a	❌ has uncommitted changes

Column definitions:

• Dirty: ✅ clean or ⚠️ N files
• Merged: ✅ merged / ✅ squash-merged (confirmed via content diff) / ❌ not merged / n/a
• Can clean?: ✅ only when merged (or squash-merged) AND clean

Add extra columns (e.g. tmux session, notes) only when relevant.

6. Cleanup (only when asked)

Only clean worktrees the user explicitly approves. For each:

NAME="<worktree-name>"
git worktree remove "/path/to/$NAME"
git branch -D "<branch>"  # only if the branch is no longer needed