SKILL.md

$27

Determine comparison targets (worktrees to compare):

a. If user provided worktree paths: Use those as comparison targets

b. If user specified branch names: Find the worktrees for those branches from git worktree list

c. If only one worktree exists besides current: Use current and that one as comparison targets

d. If multiple worktrees exist and none specified: Present list and ask user which to compare

e. If no other worktrees exist: Offer to compare with a branch using git diff

Determine what to compare (files/directories within worktrees):

a. If user specified file(s) or directory(ies) paths: Compare ALL of them

b. If no specific paths given: Ask user:

"Compare entire worktree?" or

"Compare specific files/directories? (enter paths)"

Execute comparison:

For specific files between worktrees:

diff <worktree1>/<path> <worktree2>/<path>

# Or for unified diff format:

diff -u <worktree1>/<path> <worktree2>/<path>

For directories between worktrees:

diff -r <worktree1>/<directory> <worktree2>/<directory>

# Or for summary only:

diff -rq <worktree1>/<directory> <worktree2>/<directory>

For branch-level comparison (using git diff):

git diff <branch1>..<branch2> -- <path>

# Or for stat summary:

git diff --stat <branch1>..<branch2>

For comparing with current working directory:

diff <current-file> <other-worktree>/<file>

Format and present results:

Show clear header indicating what's being compared

For large diffs, offer to show summary first

Highlight significant changes (new files, deleted files, renamed files)

Provide context about the branches each worktree contains

Comparison Modes

Mode

Description

Command Pattern

File diff

Compare single file between worktrees

diff -u <wt1>/file <wt2>/file

Directory diff

Compare directories recursively

diff -r <wt1>/dir <wt2>/dir

Summary only

Show which files differ (no content)

diff -rq <wt1>/ <wt2>/

Git diff

Use git's diff (branch-based)

git diff branch1..branch2 -- path

Stat view

Show change statistics

git diff --stat branch1..branch2

Worktree Detection

The command finds worktrees using git worktree list:

/home/user/project           abc1234 [main]

/home/user/project-feature   def5678 [feature-x]

/home/user/project-hotfix    ghi9012 [hotfix-123]

From this output, the command extracts:

Path: The absolute path to the worktree directory

Branch: The branch name in brackets (used when user specifies branch name)

Examples

Compare specific file between worktrees:

> /git:compare-worktrees src/app.js

# Prompts to select which worktree to compare with

# Shows diff of src/app.js between current and selected worktree

Compare between two specific worktrees:

> /git:compare-worktrees ../project-main ../project-feature src/module.js

# Compares src/module.js between the two specified worktrees

Compare multiple files/directories:

> /git:compare-worktrees src/app.js src/utils/ package.json

# Shows diffs for all three paths between worktrees

Compare entire directories:

> /git:compare-worktrees src/

# Shows all differences in src/ directory between worktrees

Get summary statistics:

> /git:compare-worktrees --stat

# Shows which files differ and line counts

Interactive mode:

> /git:compare-worktrees

# Lists available worktrees

# Asks which to compare

# Asks for specific paths or entire worktree

Compare with branch worktree by branch name:

> /git:compare-worktrees feature-x

# Finds worktree for feature-x branch and compares

Compare specific paths between branch worktrees:

> /git:compare-worktrees main feature-x src/ tests/

# Compares src/ and tests/ directories between main and feature-x worktrees

Output Format

File Comparison Header:

Comparing: src/app.js

  From: /home/user/project (main)

  To:   /home/user/project-feature (feature-x)

---

[diff output]

Summary Output:

Worktree Comparison Summary

===========================

From: /home/user/project (main)

To:   /home/user/project-feature (feature-x)

Files only in main:

  - src/deprecated.js

Files only in feature-x:

  + src/new-feature.js

  + src/new-feature.test.js

Files that differ:

  ~ src/app.js

  ~ src/utils/helpers.js

  ~ package.json

Statistics:

  3 files changed

  2 files added

  1 file removed

Common Workflows

Review Feature Changes

# See what changed in a feature branch

> /git:compare-worktrees --stat

> /git:compare-worktrees src/components/

Compare Implementations

# Compare how two features implemented similar functionality

> /git:compare-worktrees ../project-feature-1 ../project-feature-2 src/auth/

Quick File Check

# Check if a specific file differs

> /git:compare-worktrees package.json

Pre-Merge Review

# Review all changes before merging (compare src and tests together)

> /git:compare-worktrees --stat

> /git:compare-worktrees src/ tests/

# Both src/ and tests/ directories will be compared

Important Notes

Argument detection: The command auto-detects argument types by comparing them against git worktree list output:

Paths matching worktree roots → treated as worktrees to compare

Names matching branches in worktrees → treated as worktrees to compare

Other paths → treated as files/directories to compare within worktrees

Multiple paths: When multiple file/directory paths are provided, ALL of them are compared between the selected worktrees (not just the first one).

Worktree paths: When specifying worktrees, use the full path or relative path from current directory (e.g., ../project-feature)

Branch vs Worktree: If you specify a branch name, the command looks for a worktree with that branch checked out. If no worktree exists for that branch, it suggests using git diff instead.

Large diffs: For large directories, the command will offer to show a summary first before displaying full diff output.

Binary files: Binary files are detected and reported as "Binary files differ" without showing actual diff.

File permissions: The diff will also show changes in file permissions if they differ.

No worktrees: If no other worktrees exist, the command will explain how to create one and offer to use git diff for branch comparison instead.

Integration with Create Worktree

Use /git:create-worktree first to set up worktrees for comparison:

# Create worktrees for comparison

> /git:create-worktree feature-x, main

# Created: ../project-feature-x and ../project-main

# Now compare

> /git:compare-worktrees src/

Troubleshooting

"No other worktrees found"

Create a worktree first with /git:create-worktree <branch>

Or use git diff for branch-only comparison without worktrees

"Worktree for branch not found"

The branch may not have a worktree created

Run git worktree list to see available worktrees

Create the worktree with /git:create-worktree <branch>

"Path does not exist in worktree"

The specified file/directory may not exist in one of the worktrees

This could indicate the file was added/deleted in one branch

The command will report this in the comparison output

git:compare-worktrees