git-best-practices

name	git-best-practices
description	Safe-by-default git workflow and Conventional Commits. Use for git operations (diffs, staging, commits, branches, merges, conflict resolution, rebase/cherry-pick), PR review, and releases (tagging). Prevent destructive operations without consent.

Git Best Practices

Safety Rules

• Read-only by default: Prefer git status, git diff, git log, git show, git blame before making changes
• Push requires explicit request: Never push unless user asks
• Checkout allowed for: PR review, explicit user request
• Branch changes require consent: Ask before creating/switching branches
• History rewriting requires consent: Ask before commit --amend, interactive rebase, or force push (especially if anything may be shared)
• Destructive ops require explicit user consent:
  • Allow previews like git clean -n (no deletion); do not run git clean -fd without consent
  • Do not discard worktree changes with git reset --hard or git restore . without consent
  • Do not delete branches/tags or force push without consent

Preferred Commands

• Prefer modern porcelain: git switch (branches) and git restore (undo) when appropriate
• git restore --staged <path> is usually safe; discarding worktree changes (e.g., git restore .) requires explicit consent

Conventional Commits

Format: <type>[optional scope][optional !]: <description>

Subject Line

• Use imperative mood (“add”, “fix”, “remove”)
• Keep it short and specific; avoid trailing periods

Types

Type	Use for
feat	New features
fix	Bug fixes
docs	Documentation only
style	Formatting, whitespace (no code change)
refactor	Code change that neither fixes nor adds
perf	Performance improvements
test	Adding or correcting tests
build	Build system or dependencies
ci	CI configuration
chore	Other changes (tooling, config)
revert	Reverting a previous commit

Scope

• Use the smallest sensible scope
• Omit scope if unclear or too broad
• Examples: feat(auth):, fix(api):, docs(readme):

Breaking Changes

Mark with ! before the colon OR add a BREAKING CHANGE: footer:

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: /v1/users endpoint removed, use /v2/users

Body and Footers

• Use body only when the subject line needs elaboration
• Footers follow git-trailer style: Token: value
• Common footers: BREAKING CHANGE:, Fixes:, Refs:, Co-authored-by:

Examples

feat(auth): add OAuth2 login flow

fix: prevent race condition in queue processing

docs: update API authentication examples

refactor(db)!: migrate from MySQL to PostgreSQL

BREAKING CHANGE: database connection config format changed

Pre-Commit Checklist

• Review git status
• Review git diff and git diff --staged
• Run the smallest relevant checks if known (or ask what to run)
• Scan for secrets (tokens, keys, credentials) and unintended debug logs
• Prefer small, logical commits; use git add -p when changes are mixed
• Propose a commit split and draft commit messages before staging/committing

Workflow

After reviewing changes, end with:

1. Short summary of proposed commits
2. Clear question for next steps (stage/commit/push)

If anything is ambiguous, ask short, direct questions with options.