local-branches-status

Local Branches Status Report

You are helping the user get a comprehensive overview of all local git branches in their repository. The report shows each branch's sync state, divergence from main, worktree usage, last activity, and a brief description of what the branch contains.

When to Use

• Before deciding which branches to clean up or delete
• When resuming work after time away from a project
• Before pushing or rebasing to understand the current state
• When onboarding to a repository with multiple active branches
• When reviewing worktree usage across branches

Report Process

Step 1: Gather Branch Data

Collect all branch information in a single shell invocation using the batch loop in Step 3. Do not make N separate tool calls per branch — one loop gathers every column for every branch.

Data collected per branch:

• Remote sync state (ahead/behind upstream)
• Divergence from the main branch (ahead/behind)
• Worktree association (with path)
• Last activity date
• Unique commits (commits not on main)
• Whether this is the current branch (HEAD)

Step 2: Determine the Main Branch

Identify the main branch automatically:

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

If that fails, fall back to checking for main or master.

Step 3: Batch Data Collection

Gather all per-branch data in a single shell loop rather than making separate tool calls for each branch and column. This is critical for efficiency — one invocation collects everything:

main_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
worktree_list=$(git worktree list)

for branch in $(git for-each-ref --format='%(refname:short)' refs/heads/); do
  # Remote sync state
  upstream=$(git for-each-ref --format='%(upstream:short)' "refs/heads/$branch")
  if [ -n "$upstream" ] && git rev-parse --verify "refs/remotes/$upstream" &>/dev/null; then
    counts=$(git rev-list --left-right --count "$upstream...$branch" 2>/dev/null || echo "0 0")
  else
    upstream=""
    counts="no_upstream"
  fi

  # Main branch diff
  if [ "$branch" = "$main_branch" ]; then
    main_diff="—"
  else
    main_diff=$(git rev-list --left-right --count "$main_branch...$branch" 2>/dev/null || echo "0 0")
  fi

  # Last activity
  last_activity=$(git log -1 --format='%cr' "$branch" 2>/dev/null || echo "unknown")

  # Worktree path
  wt_path=$(echo "$worktree_list" | grep "\[$branch\]" | awk '{print $1}')

  # Unique commits summary
  unique=$(git log "$main_branch..$branch" --oneline 2>/dev/null)

  echo "BRANCH:$branch|UPSTREAM:$upstream|COUNTS:$counts|MAIN_DIFF:$main_diff|LAST:$last_activity|WT:$wt_path|CURRENT:$([ "$branch" = "$current_branch" ] && echo yes || echo no)"
  echo "COMMITS:$unique"
  echo "---"
done