branch-compare - SKILL.md Agent Skill

name: branch-compare description: >- Compare two git branches side-by-side using a configurable diff tool (defaults to Beyond Compare) and temporary worktrees. Use when the user wants to visually diff branches, compare branch contents, or open a folder comparison between two git refs. Defaults to comparing the current branch against develop. argument-hint: "[--filter=] [branch1] [branch2]" allowed-tools: - "Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/branch-compare.sh:)" - "Bash(git branch:)" - "Bash(git worktree:)" - "Bash(git rev-parse:)" - "Bash(git fetch:*)"

Compare two git branches using a configurable diff tool and worktrees.

Usage: /branch-compare [--filter=<preset|raw|none>] [branch1] [branch2]

Arguments are optional and passed via $ARGUMENTS:

No arguments: compare the current branch against develop
One argument: compare the current branch against that branch
Two arguments: compare branch1 (left) against branch2 (right)

Filter Options

The --filter flag controls which files/folders are shown in the comparison:

Preset name: --filter=unity, --filter=web, --filter=python, --filter=godot
Raw filter string: --filter="*.cs;*.shader" (passed directly to the diff tool)
Disable auto-detection: --filter=none
Omitted: auto-detects the project type based on directory markers

Available Presets

Preset	Detects	Excludes
`unity`	`ProjectSettings/` + `Assets/`	Library, Temp, Logs, Build, obj, .vs, UserSettings, etc.
`web`	`package.json`	node_modules, dist, build, .next, .nuxt, coverage, etc.
`python`	`pyproject.toml` or `setup.py`	__pycache__, .venv, .mypy_cache, .pytest_cache, etc.
`godot`	`project.godot`	.godot, .import, addons

Auto-detection runs on the git repo root and prints a message when a project type is recognized.

Configuration

The comparison tool and filters are resolved in priority order:

Tool

Environment variable: BRANCH_COMPARE_TOOL=meld
Settings file: .claude/branch-compare.local.md with compare_tool: meld in frontmatter
Default: bcomp (Beyond Compare)

Filters

CLI flag: --filter=<value>
Settings file: .claude/branch-compare.local.md with filters: unity in frontmatter
Auto-detection: based on project directory markers
None: no filters applied

Execution

Run the script with --no-prompt to suppress interactive prompts:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/branch-compare.sh --no-prompt $ARGUMENTS

The script will:

Resolve the comparison tool from env var, settings file, or default (bcomp)
Resolve filters from CLI flag, settings file, auto-detection, or none
Validate that the tool is installed and the current directory is a git repo
Resolve each branch (checking local refs, remote-tracking refs, and fetching from origin)
Reuse existing worktrees when available; create temporary detached worktrees otherwise
Open the diff tool with the two worktree root directories (with filters if applicable)
Clean up any temporary worktrees after the tool exits

After running

Report to the user which two branches are being compared, which tool was used, and which filters are active (if any). If the script exits with an error, relay the error message verbatim.

Error cases

"not found on PATH" — the configured comparison tool is not installed. If using the default (bcomp), suggest installing Beyond Compare from https://www.scootersoftware.com/
"not inside a git repository" — the working directory is not a git repo.
"branch not found" — the specified branch does not exist locally or on the remote.