git-explain

git-explain

Explain a git concept clearly and correctly to a user who wants to understand, not do. Ground the answer in the authoritative sources, then stop. Do not run git commands — this skill is pure reference.

How to answer

1. Answer the actual question first, in plain language, no jargon the learner hasn't met yet. Lead with the one-sentence mental model, then unpack it.
2. Use a concrete tiny example where it helps — a before/after of what HEAD or the tree looks like beats an abstract definition.
3. Ground it. Base the explanation on git help <cmd> and Pro Git rather than memory. Point the learner at the exact source so they can go deeper — see reference/sources.md for the topic → source map. When you're unsure, say so and cite where to look rather than guessing.
4. Name the command without running it. It's fine (and useful) to show the literal command a concept relates to — but as illustration, not execution. If the user then wants to do it, that's git-guide-me's job.
5. Stay honest on "should I?" questions. When an explanation shades into advice, separate near-objective safety facts (e.g. "rewriting published history breaks others' clones") from team conventions (e.g. rebase vs merge for integrating). State the facts plainly; present conventions as options with trade-offs, not rules.

Common concepts (mental models)

• Staging area / index — a drafting space between your working tree and history. You pick exactly what goes into the next commit with git add. (git help glossary)
• HEAD — a pointer to "where you are now," normally the tip of the current branch. HEAD~2 = two commits back along the first parent; HEAD^ = the immediate parent. (git help revisions)
• Detached HEAD — HEAD points straight at a commit instead of a branch. New commits there belong to no branch and can be lost; git switch -c <name> saves them.
• merge vs rebase — both integrate one branch into another. Merge keeps true history and adds a merge commit; rebase replays your commits onto a new base for a linear history but rewrites those commits (so never rebase shared/published history). (Pro Git 3.6)
• reset (--soft / --mixed / --hard) — moves the current branch pointer; the flag decides what happens to the index and working tree. --soft keeps both, --mixed (default) resets the index, --hard resets both (destructive). (Pro Git 7.7 is the clearest treatment.)
• reflog — git's log of where HEAD has been. It's the safety net: a "lost" commit after a bad reset or a deleted branch is usually still reachable via git reflog.
• fetch vs pull — fetch downloads remote changes without touching your branches; pull is fetch + integrate (merge or rebase).

When to use

• The user wants to understand a git concept: "what is the staging area?", "rebase vs merge?", "what does HEAD~2 / reset / the reflog do?"
• They want the why without changing anything in the repo.

When NOT to use

• Wants to do it? "Make a branch", "stage and commit", "merge this" → that's git-guide-me (show + run + explain as it goes).
• Stuck / lost / diagnose my state? "I'm in a weird state", a live conflict → git-next.
• Wants to practice the fix? → git-drill.

References

Bundled in this skill's reference/ directory (so it installs self-contained):

• reference/sources.md — the topic → source map (git help, Pro Git chapters). Ground every explanation here.