git-next

git-next

Coach a user who is lost or unsure in git. Figure out exactly where they are and give the single best next move — the literal command, why it works, and how to undo it. Stay read-only and suggest-only: run the diagnostic commands below, but never run destructive recovery (reset --hard, clean, --abort, --skip, force-push, branch -D). Show those and let the user run them.

Transparency contract (every action)

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

Never show a recommendation without its undo.

0. Gather state (read-only battery)

Run these to read the situation. They are all safe. Don't guess — measure.

git status --short --branch
git branch -vv
git stash list
git log --oneline -10
git reflog -15

In-progress operation markers (check for these files/conditions):

• .git/MERGE_HEAD → a merge is in progress
• .git/rebase-merge or .git/rebase-apply → a rebase is stopped
• .git/CHERRY_PICK_HEAD → a cherry-pick is in progress
• .git/REVERT_HEAD → a revert is in progress
• git symbolic-ref -q HEAD returns non-zero (no symbolic ref) → detached HEAD

Also note: is an upstream set for the current branch? ahead/behind counts?

If this isn't a git repo at all (git rev-parse --git-dir fails), say so and offer git init or cd to the right directory — stop here.

1. Classify into ONE situation

Match the signals to exactly one row. The full table with detection + recommended command + undo per row is in reference/situations.md — read it and use it.

Priority order when several seem to match: in-progress operation (merge / rebase / cherry-pick / revert) > detached HEAD > diverged / behind / ahead > dirty working tree > clean. An interrupted operation always wins — finish or abort it before anything else.

2. Emit ONE recommendation block

Situation:   <plain-language name>
Why you're here: <one line — how they got into this state>

Do this:
  $ <the literal command(s)>
Because:     <what it does, plainly>
If it goes wrong:
  $ <rollback / --abort / undo>
Then:        <the likely next step once this works>

Give one recommendation, not a menu. If two paths are genuinely valid (e.g. diverged → rebase vs merge), name the trade-off in one line each and recommend the safer default.

3. Suggest, don't surprise

• Safe / idempotent commands (status, log, switch, add, commit, stash, fetch, pull --ff-only, switch -c, push/push -u): offer to run them, after showing the command.
• Destructive / history-rewriting commands (reset --hard, clean, force-push, branch -D, rebase, --abort, --skip): show the command and hand it to the user to run. Explain what it will do and what it costs. Never run these for them.

Always show the command before doing anything.

When to use

• The user is lost, stuck, or unsure what to do next in git.
• Mid-operation: a stopped rebase, an in-progress merge/cherry-pick, detached HEAD, or a conflict they don't know how to clear.
• They ask "what's my next git command?" or "where am I?"

When NOT to use

• Knows what they want to do? "Stage and commit this", "make a branch" → that's git-guide-me (guide the operation), not diagnosis.
• Wants the concept, not their state? "What is a rebase?" → git-explain.
• Wants to practice, not fix real work? "Give me a conflict to practice on" → git-drill.

References

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

• reference/situations.md — the full situation → detection → command → undo table.
• reference/recovery.md — "I did X, how do I undo it?" recipes. Use this for any rescue (bad reset, lost commit, dropped stash, deleted branch, wrong-branch commit).
• reference/sources.md — authoritative sources. When explaining why, ground in git help <cmd> and Pro Git, not memory.
• reference/git-best-practices.md — safety habits (--force-with-lease, commit before risky ops, don't rewrite published history).