Git Workflow Gotchas

• Load if: Git commits, merges, branch management
• Prerequisites: @smith-principles/SKILL.md, @smith-standards/SKILL.md

CRITICAL (Primacy Zone)

• MUST use git mv for renames (preserves history)
• MUST GPG sign all commits: git commit -S -m "..."
• MUST keep branches linear (prefer rebase over merge) - essential for stacked PRs, see @smith-stacks/SKILL.md
• MUST verify current branch (git branch --show-current) before git commit, git push, or git rebase — confirm it matches the branch you intend to modify

• NEVER force push to main or shared branches
• NEVER commit directly to main branch
• NEVER rebase shared branches (only personal feature branches)
• NEVER use --no-verify to bypass git hooks
• NEVER use --no-gpg-sign to skip commit signing

Operation Boundaries

• NEVER interpret "list", "check", or "show" as permission to create or modify
• NEVER create branches or tags beyond what was requested

• Match action to request: list=list, create=create
• State planned operations before multi-step workflows
• For scope/approval rules, see @smith-guidance/SKILL.md
• For PR creation rules, see @smith-gh-pr/SKILL.md

Worktree Safety

• Before write operations (commits, pushes, dev servers, tests): verify git rev-parse --show-toplevel matches your intended working directory
• If multiple worktrees exist, use git worktree list to identify the correct one
• If in wrong worktree: stop, cd to the correct one before proceeding

Worktree Patterns

Git worktree basics:

git worktree add ../feature-branch feat/feature

git worktree list

git worktree remove ../feature-branch

Parallel branch work:

• Each worktree = independent working directory
• Share same .git — branches, stash, reflog shared
• Useful for: hotfix while mid-feature, parallel reviews

Claude Code integration:

• isolation: "worktree" in Agent tool — auto-creates worktree for subagent, cleaned up when done
• Manual worktree tools may be available depending on the agent platform (see platform docs for exact tool names)
• Worktree lifecycle hooks (create/remove) fire on worktree operations for custom automation
• Agent worktrees auto-cleanup; persistent ones need manual git worktree remove

• ALWAYS verify worktree path before write operations
• NEVER leave orphaned worktrees (check git worktree list)
• Clean up persistent worktrees after branch is merged

Branch Naming

Pattern: type/descriptive_name — type MUST match commit type

Separators (abbreviated quick-ref; see @smith-style/SKILL.md for full rules):

• Underscore (_): Multi-word single concept → fix/query_processor
• Hyphen (-): Hierarchy/variant/ticket → feat/auth-login, fix/JIRA-1234-query_processor

Commit Standards

Format: See @smith-style/SKILL.md for conventional commits.

Atomic commits: One logical change per commit, passes tests, reversible.

Non-Obvious Flags

• -u: Use on first push to set upstream tracking
• --force-with-lease: Safe force push for personal branches - required for stacked PRs after rebase, see @smith-stacks/SKILL.md
• --no-ff: Preserve merge commit for feature branches (maintains history)
• -S: GPG sign commits

Claude Code Plugin Integration

When commit-commands plugin is available:

• /commit: Auto-generates commit message, stages files, creates commit
• /clean_gone: Cleans up branches deleted from remote (including worktrees)

Manual commands still needed for:

• GPG signing (-S flag)
• Interactive rebase
• Force push with lease

Ralph Loop Commit Strategy

Atomic commits mark iteration boundaries. Include iteration number; enables git bisect for regressions.

See @smith-ralph/SKILL.md for full commit patterns.

• @smith-stacks/SKILL.md - Stacked PR workflows (uses linear history, force-with-lease)
• @smith-gh-pr/SKILL.md - PR creation, review cycles, merge strategies
• @smith-gh-cli/SKILL.md - GitHub CLI commands
• @smith-style/SKILL.md - Naming conventions, conventional commits
• @smith-ctx-claude/SKILL.md - Claude Code agent features and context management

ACTION (Recency Zone)

First push to new branch:

git push -u origin feat/my_feature

Safe force push (personal branches only):

git push --force-with-lease origin feat/my_feature

Feature merge (preserve history):

git merge --no-ff feat/my_feature

Interactive rebase (local commits only):

git rebase -i HEAD~3