git-explain-branch

Explains what a git branch changes relative to the default branch, including risks and collisions.

Updated Dec 18, 2025
One-click install
npx skills add https://github.com/l0lxl0lw/dotfiles --skill git-explain-branch-l0lxl0lw
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: git-explain-branch
Source: https://github.com/l0lxl0lw/dotfiles/tree/main/ai/shared/skills/git/git-explain-branch
Command: npx skills add https://github.com/l0lxl0lw/dotfiles --skill git-explain-branch-l0lxl0lw

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Before opening a pull request, developers often cannot clearly articulate what their branch actually changes relative to main, which behaviors differ, and what might break. This Skill produces a structured before/after explanation of a branch against the default branch, surfacing silent behavior changes, contract breaks, unupdated callers, and semantic conflicts with commits that landed on main meanwhile. ## Core Features & Use Cases - Behavioral change explanation: Groups the three-dot diff into behavioral changes (not per-file or per-commit), each carried down to an observable consequence, with before/after statements against main. - Risk pass: Detects silent behavior changes, contract breaks (API, schema, config, signatures), irreversible migrations, and callers left unupdated via repo-wide grep. - Collision detection: Lists commits that landed on the default branch since the merge-base touching the same files, distinguishing textual conflicts from semantic ones that merge cleanly but break behavior. - Use Case: Before opening a PR, ask what your feature branch does; you receive an eight-section report covering scope, changes, call-flow deltas, contracts and risk, collisions with main, gaps, and verification commands. ## Quick Start Ask the assistant to explain what your current branch changes compared to main before you open a pull request.

Frequently Asked Questions about git-explain-branch

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I explain what my git branch changes before opening a PR?

Run the branch explanation workflow, which collects the merge-base, commit log, and three-dot diff against the default branch, then groups changes by behavior with before/after statements. It also flags risky changes and collisions with main.

What is the difference between git diff main..HEAD and main...HEAD?

Two-dot diff compares branch tips directly, so commits main gained appear as your deletions. Three-dot diff compares against the merge-base, showing only your branch's work, which is the correct form for explaining a branch.

Does this skill work on uncommitted working tree changes?

No, the branch diff covers committed work only, and uncommitted changes are explicitly listed as excluded from scope. For working-tree changes, use the companion git-explain-diff skill instead.

Can this skill modify my repository or push commits?

No, it is read-only apart from git fetch, which only updates remote-tracking refs and never touches your branch or working tree. It never commits, merges, rebases, or pushes anything.

How does it detect conflicts with changes that landed on main?

It runs git log over commits the default branch gained since the merge-base, restricted to files your branch also changed. Each hit is classified as a textual conflict or a semantic conflict that merges cleanly but breaks behavior.

When should I use this instead of a code review?

Use it when you want an explanation of what changed and what is risky, not an approve/block verdict. For a review verdict before landing, the documentation points to a dedicated /review skill instead.