Git Weapon

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:

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. 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 fixup! with a comment requires 2.32.

5. 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.

6. 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

Check with git --version before using any of the above.

Quick reference: recovery operations

Quick reference: interactive rebase commands

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.