Git

Git — Advanced CLI Mastery & Recovery

Overview

This skill is the power-user and recovery reference for the Git command line (targeting git 2.54+). It is not a beginner tutorial — it assumes the everyday add/commit/push loop is already understood and instead focuses on the parts of Git that are easy to get wrong, easy to forget, or costly to mess up:

• Getting back work that seems lost (reflog, fsck, dangling objects).
• Rewriting history safely and understanding what each operation actually moves.
• The mental models (object graph, HEAD/index/worktree, refspecs) that make confusing behavior obvious.
• Power features Claude tends to underuse: worktrees, bisect, rerere, sparse-checkout, partial clone, notes, bundles.
• Diagnosing cryptic error messages.

Core principle: In Git, commits are rarely truly lost until garbage collection runs (default ~90 days for reachable-from-reflog, ~30 for unreachable). Almost every "oh no" is recoverable via the reflog or fsck. Stay calm; diagnose before acting; avoid --hard/--force/clean until you understand the current state.

When to Use This Skill

• Recovering lost commits, branches, or stashes; undoing a reset/merge/rebase/amend.
• Interactive rebase, history surgery, squashing/splitting/reordering commits, removing a large file or secret from history.
• Merge strategy choices, conflict resolution, rerere, cherry-pick, revert (including reverting a merge).
• Inspecting history: log formats, pickaxe (-S/-G), line-log (-L), blame, range-diff, git grep.
• Remotes, refspecs, fetch/pull/push semantics, upstream tracking, safe force-pushing.
• Worktrees and stash management.
• Git internals / plumbing (cat-file, rev-parse, rev-list, object model, packfiles, gc).
• git config, .gitattributes, .gitignore, hooks, aliases.
• Submodules, subtree, sparse-checkout, partial/shallow clone, bundles, notes, bisect, signing.
• Any confusing git error or unexpected state.

When NOT to Use This Skill (defer to the specialist)

This skill covers core git itself; the workflows above have dedicated skills. Cross-reference them rather than reinventing.

Mental Models You Must Get Right

The object model

Git stores four object types, addressed by the hash of their content:

• blob — file contents (no name).
• tree — a directory listing: names → blobs/trees + modes.
• commit — a snapshot: one root tree + parent commit(s) + author/committer + message.
• tag (annotated) — a named, signed pointer to an object.

Branches and tags are just refs — files under .git/refs/ (or packed-refs) containing a commit hash. HEAD is a ref that usually points at a branch (ref: refs/heads/main); when it points directly at a commit you are in detached HEAD. A commit is "reachable" if you can walk to it from a ref; unreachable commits await gc. Deep dive: internals-plumbing.md.

HEAD, the index, and the working tree

Three states a file moves between:

working tree   --(git add)-->   index/staging   --(git commit)-->   HEAD (history)
   (edits)                         (staged)                          (committed)

• git status shows differences between all three. git diff = worktree vs index; git diff --staged = index vs HEAD.
• git restore <path> (worktree) / git restore --staged <path> (unstage) are the modern, scoped undo verbs; git switch changes branches. They replace the overloaded git checkout.

The three git reset modes (memorize this)

git reset [--soft|--mixed|--hard] <commit> moves the current branch to <commit>, differing only in what else it touches:

Two specialist modes: --merge and --keep reset while preserving local edits (and abort on conflict) — used to back out of a failed merge without losing work. Full treatment: recovery.md.

reset moves a branch pointer; revert makes a new commit that undoes another (safe on shared history); restore/checkout change file contents, not the branch.

Refspecs in one line

A refspec is [+]<src>:<dst> mapping refs between repos. git push origin main ≈ refs/heads/main:refs/heads/main; a leading + forces (non-fast-forward); an empty <src> deletes (git push origin :old-branch). Fetch config like +refs/heads/*:refs/remotes/origin/* is why remote branches land under origin/. Full treatment: refspecs-remotes.md.

"Oh No" — Recovery Quick Reference

Start here when something went wrong. Each row links to the deep guide. Diagnose with git status, git reflog, and git log --oneline --all --graph before destructive action.

Safety Rules (footguns)

• Never --force push a shared branch. Use git push --force-with-lease (refuses if the remote moved under you). See refspecs-remotes.md.
• Don't rewrite published history others have pulled. Rewrite only local/unshared commits; otherwise revert.
• git reset --hard and git clean -fd destroy uncommitted/untracked work with no reflog. Run git stash or git clean -nd (dry run) first.
• Prefer git switch/git restore over git checkout — narrower, less surprising.
• git filter-repo rewrites every commit hash (invalidates clones); git filter-branch is discouraged by upstream. See history-rewriting.md.
• After any rewrite, collaborators must re-clone or hard-reset to the new history — communicate it.

Where to Look — Reference Map

Read the focused file for the task at hand (progressive disclosure — don't load them all):

Common Workflows (compact)

Undo the last commit, keep the changes

git reset --soft HEAD~1      # keep changes staged
git reset HEAD~1             # (--mixed) keep changes, unstaged
# Pushed already? Don't rewrite — invert it:
git revert HEAD              # new commit undoing the last one

Clean up local commits before pushing

git rebase -i @{upstream}    # reorder/squash/fixup/reword/drop/edit
# Mark fixup commits and let git slot them automatically:
git commit --fixup=<hash> && git rebase -i --autosquash @{upstream}

Full todo-command reference and --update-refs (keeps stacked branches aligned): history-rewriting.md. For dedicated stacked-branch tooling use the git-chain skill; for auto-fixup use git-absorb.

Find the commit that introduced a bug (bisect)

git bisect start
git bisect bad                 # current is broken
git bisect good v1.2.0         # known-good point
git bisect run ./test.sh       # automated; git checks out the culprit
git bisect reset               # restore HEAD when done

Details, skip, and custom terms: advanced-features.md.

Work on two branches at once (no stashing)

git worktree add ../hotfix main     # second working tree on a new path
# ...fix, commit, push from ../hotfix...
git worktree remove ../hotfix

Gotchas (a branch checks out in only one worktree, shared object store): worktrees-stash.md.

Stash, switch context, come back

git stash push -u -m "wip: parser"   # include untracked (-u)
git switch other-branch
git switch -                          # back
git stash pop                         # reapply + drop (apply keeps it)

Partial stashing (-p), keeping the index (-k), recovering a dropped stash: worktrees-stash.md.

Bring one fix to another branch

git switch release-1.x
git cherry-pick -x <hash>     # -x records "cherry picked from ..."
# Conflict? resolve, then:
git cherry-pick --continue    # or --abort / --skip

Ranges, picking a merge (-m), and rerere to auto-reuse resolutions: branching-merging.md.

Resolve a merge conflict

git merge feature             # conflict reported
git status                    # see "Unmerged paths"
git diff                      # ours (HEAD) vs theirs in markers <<<<<<< ======= >>>>>>>
# edit files, then:
git add <resolved> && git merge --continue
git merge --abort             # bail out entirely

-X ours/theirs, choosing a strategy, and reusing resolutions with rerere: branching-merging.md. Backing out a committed merge: recovery.md.

Search history for where/when something changed

git log -S "functionName" --oneline      # commits that add/remove the string (pickaxe)
git log -L :funcName:file.c              # evolution of a function
git log --oneline --follow -- path       # history across renames
git blame -w -C file.c                   # who/why, ignoring whitespace & copies

More in inspection.md.

Git Version Awareness

This skill is documented against git 2.54, but most of it works on far older git. Features that need a specific minimum version are tagged inline as (git X.Y+); default changes and removals are noted where they matter. When no tag is present, assume the feature is long-standing. For a consolidated lookup, see version-features.md.

High-impact cutoffs worth remembering:

Always confirm against the installed git: git version, then git <cmd> --help.

Conventions & Notes

• Verify exact flags against the installed git (git <cmd> --help); flag behavior evolves across releases (see Git Version Awareness).
• Prefer non-destructive diagnosis first (status, reflog, log --graph, --dry-run, --no- variants) before any command that rewrites or deletes.
• Quote/escape revisions and pathspecs in shells ('HEAD^', -- to separate paths from revs).
• When in doubt about a destructive op, create a throwaway branch or tag at the current commit first: git branch backup-$(date +%s).