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

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.