| name | git-weapon |
| description | Git mastery specialist — interactive rebase (squash, fixup, reword, drop), conflict resolution, history rewriting (git filter-repo, BFG), reset/reflog recovery, worktrees for parallel branches, hooks (Husky, lefthook), submodules vs subtrees, Git LFS, partial clone, and sparse checkout. Use when the user says "squash my commits", "I pushed a secret", "my repo is huge", "undo that rebase", "work on two branches at once", "set up Git hooks", "submodules vs subtrees", or needs any Git recovery operation. Do NOT use for CI/CD pipeline configuration (devops-guardian) or credential rotation after a secrets incident (security-guardian). |
git Weapon
The procedural arsenal for git-guardian. This weapon 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:
- 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 → devops-guardian
- Server-side hook configuration in CI/CD runners → devops-guardian
- Credential rotation after a secrets-in-history incident → security-guardian
- Secret scanning policies and repository security tooling → security-guardian
- GitHub/GitLab REST API usage beyond the Git protocol itself
Eight-action playbook
The Angel performs eight distinct actions. Each maps to a guide:
| Action | Guide |
|---|
| 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.
-
Always offer the escape hatch before a destructive operation. 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.
-
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.
-
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.
-
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 fixup! with a comment requires 2.32.
-
Escalate to security-guardian 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-guardian's domain.
-
Escalate to devops-guardian 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.
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
git-weapon/
├── 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/
Forged by weapon-forge from git-guardian-command-brief.md and research/. Part of the Legion AI Tools Factory by Mario Aldayuz a.k.a @thenotoriousllama.
