safe-git-operations

name	safe-git-operations
description	Use before running git reset, git add -A/./-a, editing .gitignore when it's not excluding expected paths, or cleaning up committed files. Prevents four common operational failure modes that cascade into long recovery sessions: reset without state check, catchall staging of build artifacts, gitignore pattern trial-and-error, and per-file iteration when a single bulk command suffices.

Safe Git Operations

Operational safety rules for common git commands where mistakes cascade. Complements git-workflow (which covers branching, commits, PR/CI workflow) by addressing what not to do in specific risky situations.

Rule 1: Always check state before git reset

Before any git reset command — hard, soft, or mixed — run a state check first. Guessing HEAD~N is the single most common cause of multi-minute recovery cycles.

Check first:

git log --oneline | head -10

Then:

• Reset to a specific SHA (copy from the log output), or
• Use HEAD~N only after confirming the branch has at least N+1 commits

Never do this:

git reset HEAD~3       # ❌ did you verify there are 3+ commits?
git reset --hard HEAD~N  # ❌ doubly dangerous — discards working tree too

If reset already went wrong: git reflog shows every HEAD move and lets you recover. Don't panic-try more resets.

Rule 2: Never stage catchall without verifying

git add -A, git add ., git commit -a are anti-patterns when the working tree is not clean. They pick up whatever is dirty — build artifacts, editor backup files, IDE caches, accidental files — and put them in the commit.

Always verify first:

git status --short

Read every line. If anything unintended is staged or modified:

1. Fix .gitignore first (see Rule 3)
2. Then stage deliberately: git add <specific files> or git add -p for interactive staging
3. Only use catchall staging once git status --short shows only intended changes

Exception: For tiny repos with a known-clean tree (e.g., a fresh clone, working on a brand-new branch with zero build artifacts), catchall staging is fine. In any real project with builds, tests, or generated files, it is a trap.

Rule 3: Use git check-ignore to debug .gitignore

When a .gitignore isn't excluding expected paths, DO NOT iterate by trial and error on trailing slashes, glob patterns, or negation rules. git has a debug command specifically for this:

git check-ignore -v <path>

Output shows exactly which rule (file, line number) matches — or nothing if no rule matches.

Example:

$ git check-ignore -v build/output.o
.gitignore:3:build/   build/output.o

This tells you: line 3 of .gitignore contains build/ and it matches this file. Done in one command.

Common mistake: Toggling .build vs .build/ in the gitignore. Both work — .build matches both files named .build and directories named .build; the trailing slash only narrows to directories. The real issue is almost always path placement: a .gitignore inside OllamaStatusMenu/ containing OllamaStatusMenu/.build/ is doubly-prefixed and never matches anything. git check-ignore -v surfaces this instantly.

Rule 4: Use bulk git commands for bulk situations

If hundreds of files were accidentally committed (e.g., a .build/ tree, node_modules/, an editor's cache), do NOT iterate git rm per file. A single recursive command suffices:

# Unstage a directory tree from the index (keeps working-tree files):
git rm -r --cached <dir>

# Also delete them from the working tree:
git rm -r <dir>

For build artifacts that are already in .gitignore but appear in the index (because they were added before the gitignore rule existed), the canonical fix is:

# Unstage everything, then re-add using current .gitignore rules
git rm -r --cached .
git add .

Never iterate per-file git rm 'foo/bar/baz' — this is O(n) in time, generates enormous log output, and tends to trigger inference timeouts or context exhaustion on agent systems.

When to invoke this skill

Ask yourself before any of these:

• Am I about to run git reset? → apply Rule 1
• Am I about to stage with -A / . / -a? → apply Rule 2
• Am I editing .gitignore because something isn't excluded? → apply Rule 3
• Am I about to unstage/remove many files? → apply Rule 4

If yes, follow the rule. These four are the "mistakes that cascade" pattern: a small error here turns a 30-second task into a 30-minute recovery.

What this skill is NOT

• Not a general git tutorial — see git-workflow-skill for branching, commits, PRs, CI/CD
• Not a security policy — force-push, credential leakage, etc. are out of scope
• Not a replacement for writing good .gitignore in the first place