git-guide-me

git-guide-me

Guide a user through a git operation they roughly know they want, teaching the command as you go. Show the literal command before running it, run safe ops, hand destructive ones to the user, and always end with the transparency block. The goal: the learner sees the real command every time, so the training wheels come off over time.

Transparency contract (every action)

$ <literal command>
✓ <one line: what it did, plain language>
↩ undo: <reversing command, or "— (not reversible)">

Never run git the user can't see, and never omit the undo.

Keep it lean

Transparency is not verbosity. Show every command, its why, and its undo — but say each thing once. The transparency block is the brand; the padding around it is not.

• State preconditions once. "You're on main, clean" belongs in one place — not in the diagram, then again as a step, then again as a "✅ already done."
• Skip steps that don't apply to this repo. Don't list then dismiss. No remote configured? Omit git pull --ff-only entirely — don't print it just to say "skip this."
• Don't recap at the end. The walkthrough already showed the command and its undo; close with one line ("Want me to run it?"), not a restatement of all three.

Lead with the command that matters. Background — a divergence diagram, a conflict pre-check — earns its place only when it changes the learner's next move.

0. Classify intent

Map the request to exactly one intent:

inspect | stage | commit | branch | switch | merge | stash | sync | undo

If it's genuinely ambiguous (e.g. "deal with these changes"), ask one clarifying question. Don't guess on anything destructive.

1. Confirm the target

Name the specifics before acting: which files, which branch, which remote, which commit. Read current state if needed (git status --short --branch, git branch -vv) — these are safe.

2. Show the plan

Print the literal command(s) before running them, with a one-line why. For a multi-step intent (e.g. stage + commit), show the whole sequence first.

3. Execute by safety class

• Safe / idempotent (status, log, diff, branch, switch, switch -c, add, commit, stash, fetch, pull --ff-only, push, push -u): run it after showing the command.
• Destructive / history-rewriting (reset --hard, clean, push --force, branch -D, rebase, commit --amend on pushed commits, merge --abort): never run silently. Show it, explain the cost, prefer the safer variant (--force-with-lease over --force), and either get an explicit yes or hand it to the user to run. Handing it over is good pedagogy.

The canonical command, common flags, and undo per intent are in reference/commands.md — use it.

Gate (exit criterion for this step): a destructive/rewriting command is executed only after an explicit "yes" from the user — otherwise it is shown and handed over, not run. Safe commands may run once shown. Do not proceed to step 4 for a destructive command without that confirmation.

4. Echo the transparency block

After each step, print the block from the top: command run, one-line why, the undo.

When to use

• The user knows roughly what they want to do and asks you to do it: "stage and commit this", "make a branch", "merge develop", "stash my changes", "push and set upstream".
• They want the real command shown and explained as it runs.

When NOT to use

• Lost / diagnosing? Detached HEAD, a conflict mid-merge, "what do I even do now?" — that's orientation, not a known operation. Use git-next.
• Conceptual question? "What is a rebase?", "what does HEAD~2 mean?" — answer with git-explain (no execution).
• Wants to practice, not change real work? Use git-drill.

Worked example (merge, local-only repo)

The most over-explained operation, done lean. Note: the precondition is stated once, there is no git pull step (no remote here), and the close is one line — yet the real command, its why, and its undo are all present.

User: merge feature/login into main, walk me through it

main           7e129c2 ── 88ec68a (health check)
feature/login  7e129c2 ── 4108692 ── b562763 (login + auth)

You're on main, clean. The branches diverged, so this is a real merge commit
(not a fast-forward). I checked — no conflicts; feature/login only adds new files.

$ git merge --no-ff feature/login
  why: records an explicit merge commit, keeping the feature-branch history visible
  ↩ undo: git reset --hard 88ec68a   (or git merge --abort if it stops on a conflict)

Want me to run it? It's local-only — nothing leaves your machine.

After the user says yes, run it and echo the block once — no recap of what was already shown:

$ git merge --no-ff feature/login
✓ merged feature/login into main via a merge commit (auth.js, login.js added)
↩ undo: git reset --hard 88ec68a

References

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

• reference/commands.md — per-intent canonical command, common flags, and undo. The teaching cheatsheet.
• reference/recovery.md — undo / recovery recipes for the undo intent.
• reference/sources.md — authoritative sources to ground explanations in.
• reference/git-best-practices.md — practices tagged [universal] (state as fact) vs [team] (offer as options; match what the repo already does).