Git Conventions

Commit Format

<type>(<scope>): <description>

[optional footer(s) for breaking changes only]

Important:

• •Keep descriptions concise and complete - avoid optional body unless absolutely necessary
• •Breaking changes MUST include BREAKING CHANGE: footer explaining the impact
• •Prefer self-explanatory single-line commits
• •NEVER use emojis in commit messages

Types

Examples

feat(auth): add OAuth2 login flow
fix(api): handle null response from payment service
refactor(db): extract query builder into separate module
docs(readme): add installation instructions
revert: remove experimental feature

Refs: 676104e

Branch Naming

All work must happen on a branch (never on master/main).

With ticket:

• •feat/TICKET-123
• •fix/TICKET-123
• •refactor/TICKET-123

Optional (still keep it short):

• •feat/TICKET-123-short-kebab
• •fix/TICKET-123-short-kebab
• •refactor/TICKET-123-short-kebab

Without ticket:

• •feat/short-kebab
• •fix/short-kebab
• •refactor/short-kebab
• •docs/short-kebab
• •chore/short-kebab

Rules:

• •keep it minimal
• •lowercase + hyphens only
• •no essays

For worktrees + enforcement, see the git-workflow skill.

PR Conventions

Title format: <type>(<scope>): <concise description>

• •Remove redundant words (e.g., "streamline configuration and remove complexity" → "streamline configuration")
• •The description should be complete but minimal
• •NEVER use emojis in PR titles

Description format:

• •Simple bullet list of what changed (no verbose sections)
• •Direct, factual statements
• •No dramatic language or over-explanation
• •NEVER use emojis in PR descriptions
• •Link issues if relevant: Closes #123 or Fixes #123

Example:

refactor(api): simplify authentication flow

- removes legacy OAuth1 support
- consolidates token validation logic
- migrates to new session handler

Breaking Changes

Add an exclamation mark (!) after type and use BREAKING CHANGE: in footer:

feat(api)!: change authentication endpoint

BREAKING CHANGE: /auth/login now requires email instead of username

Revert Commits

Use the revert type and reference the commit SHA(s) being reverted in a footer:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Important:

• •Use revert: type (lowercase, following conventional commits)
• •Include Refs: footer with the commit SHA(s) being reverted
• •Description should briefly explain what is being reverted
• •Can revert multiple commits by listing multiple SHAs

Git History Best Practices

Clean git history is a key success metric. Follow these practices:

Atomic Commits

• •Every commit must be independently functional
• •All tests must pass after each commit
• •All linting must pass after each commit
• •No broken application logic at any commit
• •Each commit represents one logical unit of work

Maintaining Clean History

When iterating on features (especially in PRs), prefer amending/absorbing over fixup commits:

Available tools:

• •git commit --amend - Update the most recent commit
• •git absorb - Automatically distribute staged changes to relevant commits in your branch

Avoid interactive workflows:

• •Do NOT use git rebase -i (interactive commands are not supported in this environment/workflow)

Using git-absorb:

# Make changes to fix issues in previous commits
git add -A
git absorb
# Changes are automatically distributed to the right commits

When to Amend vs New Commit

Amend/absorb when:

• •Fixing issues found in code review
• •Addressing linting/test failures
• •Refining implementation details
• •Changes belong logically to existing commits

New commit when:

• •Adding genuinely new functionality
• •Changes represent a new logical unit of work
• •Commit has already been pushed to shared branch (unless explicitly rebasing)