git-stinger

# git Stinger The procedural arsenal for `git-wasp-drone`. This stinger encodes the opinionated playbooks for every Git mastery surface: interactive rebase, conflict resolution, history rewriting, reflog recovery, worktrees, hooks, large-file storage, and submodule/subtree architecture. **When invoked, read `SKILL.md` first, then the relevant guide(s) for the task at hand. Research files confirm every factual claim; cite them when answering questions.** --- ## Scope and non-scope **In scope:** - Beginner status/diff/stage/commit/branch/restore/reflog exercises in a task-created disposable repository - Branching strategy advisory (trunk-based, Git Flow, GitHub Flow) - Interactive rebase: squash, fixup, reword, drop, reorder, exec, autosquash - Conflict resolution: merge conflicts, rebase conflicts, rerere, mergetool config - History rewriting: `git filter-repo`, BFG Repo Cleaner, removing secrets/large files - Reset/reflog recovery: all three reset types, recovering deleted branches and commits - Git worktrees: parallel branch work without stashing - Hooks: client-side (pre-commit, commit-msg, pre-push) and server-side hand-off - Submodules vs subtrees decision matrix and lifecycle - Git LFS: setup, `.gitattributes`, selective fetch, CI patterns - Partial clone (`--filter=blob:none`) and sparse checkout v2 (`--cone` mode) - Commit signing: GPG and SSH signature verification **Not in scope:** - CI/CD pipeline configuration using Git events -> ci-release-wasp-drone - Server-side hook configuration in CI/CD runners -> ci-release-wasp-drone - Credential rotation after a secrets-in-history incident -> security-wasp-drone - Secret scanning policies and repository security tooling -> security-wasp-drone - GitHub/GitLab REST API usage beyond the Git protocol itself --- ## Action playbook The Drone selects the matching action, including beginner practice. Each maps to a guide: | Action | Guide | |---|---| | Beginner disposable Git practice | `guides/09-beginner-disposable-practice.md` | | Interactive rebase (squash, fixup, autosquash) | `guides/01-interactive-rebase.md` | | History rewriting (filter-repo, BFG, secrets removal) | `guides/02-history-rewriting.md` | | Conflict resolution (merge, rebase, rerere) | `guides/03-conflict-resolution.md` | | Reset/reflog recovery | `guides/04-reflog-recovery.md` | | Worktrees for parallel branches | `guides/05-worktrees.md` | | Hooks (pre-commit, commit-msg, pre-push) | `guides/06-hooks.md` | | Large files (Git LFS, partial clone, sparse checkout) | `guides/07-lfs-and-large-files.md` | | Submodules vs subtrees decision | `guides/08-submodules-vs-subtrees.md` | --- ## Critical directives (from Command Brief) These are non-negotiables. Full justifications in `guides/00-principles.md`. 1. **Always offer the escape hatch before a destructive operation.** For a real repository, first establish exact action/path/ref authorization, active ownership, dirty/ignored/untracked state, and approved byte/history backup coverage. Reflog is not an unlimited backup; a bundle does not include all dirty or ignored file bytes. Beginner practice uses only a newly created synthetic repository and does not authorize real-project commits. Before `git reset --hard`, show `git reflog`. Before `filter-repo`, show `git bundle create backup.bundle --all`. Before any force-push, show the rollback command. The escape hatch must precede the operation. 2. **Prefer `--force-with-lease` over `--force`.** `--force` overwrites without checking whether a teammate pushed since your last fetch. `--force-with-lease` aborts if the remote was updated, preventing silent overwrites. Use `--force-with-lease=<refname>` for the strictest variant. 3. **Never recommend `git filter-branch`.** It is officially deprecated (Git 2.36+) in favor of `git filter-repo`. It is an order of magnitude slower, has known correctness bugs, and the manpage now opens with a deprecation warning. Always use `filter-repo` or BFG. 4. **Confirm the Git version before recommending advanced features.** Worktrees stabilized in Git 2.15. Sparse checkout v2 (cone mode) arrived in 2.25. Partial clone landed in 2.22. `--rebase-merges` in 2.22. `--autosquash` has been available since 1.7.4 but autosquash fixup commits with a comment require 2.32. 5. **Escalate to security-wasp-drone for secrets-in-history scenarios.** Removing a secret from history requires force-push coordination AND credential rotation - the secret must be treated as compromised even after removal. That coordination (rotating keys, auditing access logs, notifying stakeholders) is security-wasp-drone's domain. 6. **Escalate to ci-release-wasp-drone for server-side hooks and CI Git configuration.** Server-side hooks (`pre-receive`, `update`, `post-receive`) run in CI contexts with different Git versions, file system constraints, and network policies. --- ## Beginner practice entry Read `guides/09-beginner-disposable-practice.md` and `templates/beginner-git-worksheet.md`. `references/research/beginner-practice/distillation.md` is source-repository research that is not shipped with the plugin; do not require it, because guide `09` carries its conclusions. Run `python <checked-skill-root>/scripts/practice-git.py --run` only for the requested synthetic exercise. It accepts no repository path, creates its own temporary repository, isolates inherited Git routing/global configuration/hooks, supplies identity per command for fixtures, records actual state transitions, and cleans only its created directory. No install, credential configuration, remote operation, hard reset, history rewrite, or real-project commit is part of this lesson. If the tools are unavailable, mark the exercise unexecuted. `scripts/test-practice-git.py` verifies runtime ownership boundaries. Successful fixture results do not prove learner comprehension or real-recovery correctness. ## Git version requirements matrix | Feature | Minimum Git version | |---|---| | `git worktree` (stable) | 2.15 | | Partial clone (`--filter`) | 2.22 | | `--rebase-merges` | 2.22 | | Sparse checkout v2 (`--cone`) | 2.25 | | `git switch` / `git restore` | 2.23 | | `filter-branch` deprecated warning | 2.36 | | `git bundle --filter` | 2.41 | Check with `git --version` before using any of the above. --- ## Quick reference: recovery operations | Scenario | Command | |---|---| | Undo last commit (keep changes staged) | `git reset --soft HEAD~1` | | Undo last commit (keep changes unstaged) | `git reset HEAD~1` | | Undo last commit (discard changes) | `git reset --hard HEAD~1` + verify with reflog first | | Recover deleted branch | `git checkout -b <branch> <sha>` (sha from `git reflog`) | | Recover dropped stash | `git stash apply <sha>` (sha from `git fsck --lost-found`) | | Undo a merge | `git reset --hard ORIG_HEAD` | | Undo a rebase | `git reset --hard ORIG_HEAD` or find pre-rebase sha in reflog | | Recover file deleted in past commit | `git checkout <sha>^ -- <path>` | --- ## Quick reference: interactive rebase commands | Command | Effect | |---|---| | `pick` | Keep commit as-is | | `reword` | Keep commit, edit message | | `edit` | Keep commit, pause to amend | | `squash` | Meld into previous commit, combine messages | | `fixup` | Meld into previous commit, discard message | | `drop` | Delete commit entirely | | `exec` | Run shell command between commits | | `break` | Pause rebase at this point | --- ## Folder layout ```text git-stinger/ ├── SKILL.md (this file - master index) ├── README.md (human overview) ├── guides/ │ ├── 00-principles.md (escape-hatch-first, force-with-lease, filter-branch deprecation, version matrix, public-branch rule) │ ├── 01-interactive-rebase.md (squash, fixup, autosquash, rebase -i conflict resolution) │ ├── 02-history-rewriting.md (filter-repo, BFG, backup procedure, force-push protocol) │ ├── 03-conflict-resolution.md (merge conflicts, rerere, mergetool, cherry-pick conflicts) │ ├── 04-reflog-recovery.md (reset types, recovering deleted branches/commits, ORIG_HEAD) │ ├── 05-worktrees.md (worktree commands, bare clone pattern, AI agent use cases) │ ├── 06-hooks.md (pre-commit, commit-msg, pre-push; Husky/lefthook setup) │ ├── 07-lfs-and-large-files.md (LFS setup, .gitattributes, partial clone, sparse checkout) │ └── 08-submodules-vs-subtrees.md (decision matrix, lifecycle commands, alternatives) ├── examples/ │ ├── secrets-removal.md (end-to-end: discovered secret → backup → filter-repo → force-push → escalate) │ └── worktree-parallel-features.md (two features in progress without stash context-switch) ├── templates/ │ ├── gitattributes-starter.md (.gitattributes with LFS patterns + line-ending normalization) │ ├── hooks-collection.md (pre-commit, commit-msg, pre-push hook scripts) │ └── rebase-cheatsheet.md (quick-reference card for rebase -i commands) ├── reports/ │ └── README.md (past run summaries accumulate here) └── research/ (authored by scripture-historian - DO NOT MODIFY) ├── research-plan.md ├── research-summary.md ├── index.md ├── internal/ └── external/ ``` --- *Part of The Wasp Nest, curated by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*