When should I use smith-git?

smith-git is useful in the following scenarios: • Securing the development pipeline by enforcing GPG-signed commits and preventing accidental direct pushes to the main branch. • Maintaining a clean and navigable project history through the implementation of atomic commits and linear rebase strategies. • Executing safe remote updates on personal branches using advanced flags like --force-with-lease to prevent overwriting peer contributions. • Streamlining repository maintenance by automating branch cleanup and generating standardized commit messages via Claude integration.

When & Why to Use This Skill

This Claude skill optimizes Git workflows by enforcing best practices for commit security, branch management, and history integrity. It provides expert guidance on GPG signing, atomic commits, and safe rebasing to ensure a professional, secure, and maintainable version control process while preventing common 'gotchas' in collaborative environments.

Use Cases

Securing the development pipeline by enforcing GPG-signed commits and preventing accidental direct pushes to the main branch.
Maintaining a clean and navigable project history through the implementation of atomic commits and linear rebase strategies.
Executing safe remote updates on personal branches using advanced flags like --force-with-lease to prevent overwriting peer contributions.
Streamlining repository maintenance by automating branch cleanup and generating standardized commit messages via Claude integration.

name	smith-git
description	Git workflow gotchas and non-obvious practices. Use when performing Git commits, merges, branch management, or rebasing. Covers GPG signing, atomic commits, and safety flags.

name

smith-git

description

Git workflow gotchas and non-obvious practices. Use when performing Git commits, merges, branch management, or rebasing. Covers GPG signing, atomic commits, and safety flags.

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

NEVER force push to main or shared branches
NEVER commit directly to main branch
NEVER rebase shared branches (only personal feature branches)

Branch Naming

See @smith-style/SKILL.md for naming conventions.

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

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