Git Commit

Workflow

IMPORTANT: Follow these steps in order. Do not skip or reorder unless a step explicitly says to.

1. Check what is staged and what isn't:

   git status --short
   

   • If nothing to commit at all, stop and tell the user.
   • If nothing is staged → run git add -A to stage everything.

2. Read the staged diff and analyze per the Splitting commits rules:

   git diff --cached
   

   • If there is one group → proceed to step 3.
   • If there are multiple groups → tell the user how many commits will be made, then unstage everything and stage only the first group's files:

     git reset HEAD
     git add <file1> <file2> ...
     

3. Generate a commit message per the Commit message rules and commit:

   git commit -m "<generated message>"
   

   If unstaged changes remain, repeat from step 1.

Guidelines

Commit message

• Format: <type>(<scope>): <description> where type is one of:
  • feat: A new capability or behavior the project didn't have before
  • fix: Correcting broken or incorrect behavior
  • docs: Changes to documentation only
  • refactor: Restructuring code without changing behavior
  • perf: Performance improvements
  • chore: Routine upkeep (e.g. versions, lockfiles, renaming, linting, formatting)
  • test: Adding or updating tests
  • ci: Changes to CI/CD pipelines or workflow files
  • revert: Undoing a previous commit
• Scope: ALWAYS include in parentheses (e.g. feat(auth):)
• Description: Present tense imperative, no period, ≤50 chars
• Breaking changes: Add ! after type/scope (e.g. feat!(scope):)
• No generic messages: Never use "update code", "fix bug", "changes"
• No attribution: Never add Co-Authored-By trailers or footers
• Examples:
  • feat(auth): add OAuth2 login flow
  • fix(api): handle null response from payment gateway
  • docs(readme): add setup instructions
  • refactor(db): extract query builder into separate module
  • chore(deps): bump express to v5
  • chore(lint): apply prettier formatting
  • perf(search): add index on users.email column
  • test(auth): add unit tests for token refresh
  • ci(deploy): add staging environment workflow
  • feat!(api): change response format to JSON:API

Splitting commits

• Atomic commits: Each commit must contain only related changes that serve a single purpose
• Split large changes: If changes touch different concerns, different types (feat vs fix vs refactor), different file categories (source vs docs), or are large enough that breaking them down aids review

Git safety

• No bypassing hooks: Never use --no-verify or --force
• No config changes: Never modify git config
• Sensitive files: Never stage .env, credentials, or private keys
• Pre-commit failures: Stop and report the error — do not attempt to fix or bypass it
• Empty staging: If nothing is staged after git add, stop and tell the user