git-commit

Git Commit Convention

Overview

All git commit messages MUST follow the Conventional Commits specification. This enables automatic semantic versioning, changelog generation, and clear project history.

When to Use

• Creating any git commit
• Reviewing commit messages in a PR
• Amending or rewording a commit message
• When a user asks about commit message best practices

Format

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

[optional body]

[optional footer(s)]

Types

Type	Description	SemVer Impact
feat	New feature	MINOR
fix	Bug fix	PATCH
docs	Documentation only	-
style	Formatting, missing semicolons, etc. (no code change)	-
refactor	Code change that neither fixes a bug nor adds a feature	-
perf	Performance improvement	PATCH
test	Adding or correcting tests	-
build	Changes to build system or external dependencies	-
ci	Changes to CI configuration files and scripts	-
chore	Other changes that don't modify src or test files	-
revert	Reverts a previous commit	-

Breaking Changes

A breaking change MUST be indicated by:

• ! after the type/scope: feat!: remove deprecated API
• Or a BREAKING CHANGE: footer in the commit body

Breaking changes trigger a MAJOR version bump.

Rules

0. Never commit directly on the default branch

Before committing, check the current branch:

git branch --show-current

If you are on the default branch (main or master), you MUST create and switch to a new branch before committing. The branch name MUST follow the convention:

<type>/<short-description>

Where <type> matches the Conventional Commits type of the work being done.

# BAD - committing on main
git commit -m "feat: add login page"

# GOOD - create branch first, then commit
git checkout -b feat/add-login-page
git commit -m "feat: add login page"

Branch naming rules

• Use the same type as the commit (feat, fix, perf, docs, refactor, ci, test, build, chore)
• Description is lowercase, words separated by hyphens
• Keep it short but descriptive (3-5 words max)

# Examples
feat/oauth2-login-flow
fix/null-response-payment
perf/optimize-query-cache
docs/add-installation-guide
refactor/extract-auth-middleware
ci/pin-actions-to-sha

Detecting the default branch

Use this command to determine the default branch:

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@refs/remotes/origin/@@' || echo "main"

1. Type is mandatory

# BAD
git commit -m "add login page"

# GOOD
git commit -m "feat: add login page"

2. Scope is optional but encouraged

Scope should be a noun describing the section of the codebase:

# GOOD
git commit -m "feat(auth): add OAuth2 login flow"
git commit -m "fix(api): handle null response from payment gateway"
git commit -m "ci(github-actions): upgrade checkout action to v4"

3. Description must be lowercase, imperative, no period

# BAD
git commit -m "feat: Added login page."
git commit -m "feat: Adds login page"

# GOOD
git commit -m "feat: add login page"

4. Breaking changes must be explicit

# With ! marker
git commit -m "feat(api)!: change authentication endpoint response format"

# With footer
git commit -m "feat(api): change authentication endpoint response format

BREAKING CHANGE: response now returns a JWT token instead of session ID"

5. Body should explain the why, not the what

# GOOD
git commit -m "fix(parser): handle edge case with empty arrays

The parser crashed when receiving an empty array from the API.
Root cause was a missing null check in the deserialization step."

Examples

# Feature
feat(dashboard): add real-time metrics widget

# Bug fix
fix(auth): prevent token refresh race condition

# Documentation
docs(readme): add installation instructions for OpenCode

# CI
ci(workflows): pin actions to SHA for supply chain security

# Breaking change
feat(api)!: migrate from REST to GraphQL endpoints

BREAKING CHANGE: all /api/v1/* endpoints are removed, use /graphql instead