# Compare Branches Report > Compare two git branches and produce a structured change report (no merge strategy). Includes file/commit summaries, key diffs, and risk hotspots. Use when this capability is needed. - Skill: `tomevault-io/compare-branches-report` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/compare-branches-report` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/compare-branches-report/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/compare-branches-report --- # Compare Branches Report (No Merge Strategy) ## Usage Run: - `/compare-branches-report ` Examples: - `/compare-branches-report main feature/login-refactor` - `/compare-branches-report develop release/1.9.0` ### If arguments are missing 1. List local branches. 2. Ask the user to re-run with two branch names. 3. Stop. --- ## 0) Resolve inputs Parse `$ARGUMENTS` into: - `BASE` - `TARGET` If `BASE` or `TARGET` is missing: - Show branches: - !`git branch --format="%(refname:short)" | head -n 40` - !`git branch -r --format="%(refname:short)" | head -n 40` - Ask: “Re-run: `/compare-branches-report `” - Stop. Verify branches exist (local or remote): - !`git show-ref --verify --quiet "refs/heads/$BASE" && echo "OK local: $BASE" || echo "Not local: $BASE"` - !`git show-ref --verify --quiet "refs/heads/$TARGET" && echo "OK local: $TARGET" || echo "Not local: $TARGET"` - !`git rev-parse --verify --quiet "$BASE" >/dev/null && echo "OK resolvable: $BASE" || echo "ERROR: cannot resolve $BASE"` - !`git rev-parse --verify --quiet "$TARGET" >/dev/null && echo "OK resolvable: $TARGET" || echo "ERROR: cannot resolve $TARGET"` If resolution fails: - Ask user to fetch or provide correct names. - Stop. Optional (safe) fetch: - !`git fetch --all --prune 2>/dev/null || true` Define comparison range as: - `RANGE = $BASE..$TARGET` and common ancestor: - !`git merge-base "$BASE" "$TARGET"` --- ## 1) Rules - Do not modify files. - Do not propose or discuss merge strategies (no merge/rebase/squash guidance). - Focus on “what changed”, “where”, “risk”, and “how to validate”. --- ## 2) High-level summary - Repo root: - !`git rev-parse --show-toplevel 2>/dev/null || pwd` - Current HEAD: - !`git rev-parse --abbrev-ref HEAD` - Compare: - Base: `$BASE` - Target: `$TARGET` --- ## 3) File-level impact ### 3.1 Diff stats - !`git diff --stat "$BASE..$TARGET"` - !`git diff --shortstat "$BASE..$TARGET"` - !`git diff --numstat "$BASE..$TARGET" | head -n 200` ### 3.2 Changed files (by status) - !`git diff --name-status "$BASE..$TARGET" | head -n 300` ### 3.3 Categorize by file type / area Generate a quick breakdown (frontend/backend/config/tests/docs): - !`git diff --name-only "$BASE..$TARGET" | awk -F/ '{print $1}' | sort | uniq -c | sort -nr | head -n 30` Also highlight common important folders if present: - !`git diff --name-only "$BASE..$TARGET" | rg -n "^(src|apps|libs|packages|server|backend|api|infra|.github|docker|k8s|helm|migrations|test|tests|docs)/" | head -n 200 || true` --- ## 4) Commit-level summary ### 4.1 Commits in target not in base - !`git log --oneline --decorate "$BASE..$TARGET" --max-count=80` ### 4.2 Grouped commit messages (optional signal) - !`git log --pretty=format:"%s" "$BASE..$TARGET" | head -n 120` ### 4.3 Authors (useful for coordination) - !`git log --format="%an" "$BASE..$TARGET" | sort | uniq -c | sort -nr | head -n 20` --- ## 5) Key diffs (content) Pick the most important files to open and summarize: - Prioritize: - config changes: package.json, lockfiles, tsconfig, eslint, env, CI - routing/auth/security layers - shared libraries/utilities - API contracts / DTOs / schemas - database migrations Helpful commands: - Show patch for a specific file: - `git diff "$BASE..$TARGET" -- ` - Show only function-level context: - `git diff "$BASE..$TARGET" -U3 -- ` If too large: - Focus on “what changed” bullets per file rather than full diff reproduction. --- ## 6) Hotspot detection (risk areas) Scan changed files for typical risky patterns (only within changed files list): 1. Collect changed file list: - !`git diff --name-only "$BASE..$TARGET" > /tmp/changed_files.txt && wc -l /tmp/changed_files.txt` 2. Search for risk keywords: - auth/security: - !`cat /tmp/changed_files.txt | xargs -I{} sh -c 'test -f "{}" && rg -n "(auth|token|jwt|csrf|cors|oauth|role|permission)" "{}" || true' | head -n 120 || true` - API/HTTP: - !`cat /tmp/changed_files.txt | xargs -I{} sh -c 'test -f "{}" && rg -n "(fetch\\(|axios\\.|HttpClient|http\\.(get|post|put|delete)|endpoint|route)" "{}" || true' | head -n 120 || true` - breaking change hints: - !`cat /tmp/changed_files.txt | xargs -I{} sh -c 'test -f "{}" && rg -n "(BREAKING|deprecated|remove|rename|migration)" "{}" || true' | head -n 120 || true` (If xargs fails due to spaces, re-run with a safer approach or summarize without it.) --- ## 7) Output format (final report) Produce a report with these sections: ### 1) Executive Summary - What changed overall (size, areas touched) - High-level intent (from commit messages + diffs) ### 2) Change Overview - Total files changed + shortstat - Top folders impacted - Notable file types (config, code, tests, docs) ### 3) Detailed Changes by Area For each area (e.g., Frontend, Backend, Shared, Infra/CI, Docs): - List key files and what changed - Note any API/contract changes - Note any behavior changes ### 4) Risk & Attention Points - Potential breaking changes - Security/auth implications - Config/dependency changes - Migration concerns ### 5) Suggested Validation Checklist (No merge strategy) - What to run / verify (tests, build, lint, e2e, smoke checks) - Any manual QA scenarios inferred from changes ### 6) Appendices - Commit list - Changed file list Important: Do not mention merge strategy. Do not recommend rebase/merge/squash. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/spatariurares) — claim your Tome and manage your conversions.