git-commit

When to Use

• Committing changes to the repository
• Writing or reviewing commit messages
• Staging files for commit
• Amending commits (with caution)

---

Conventional Commits Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Type	Description	Example
feat	New feature	feat: add user authentication
fix	Bug fix	fix: resolve login timeout issue
docs	Documentation only	docs: update API reference
style	Code style (formatting, semicolons)	style: format with prettier
refactor	Code change that neither fixes nor adds	refactor: extract validation logic
perf	Performance improvement	perf: optimize database queries
test	Adding or fixing tests	test: add unit tests for auth
chore	Maintenance tasks	chore: update dependencies
ci	CI/CD changes	ci: add GitHub Actions workflow
build	Build system changes	build: upgrade webpack to v5

Scope (Optional)

Indicates the section of the codebase:

feat(auth): add OAuth2 support
fix(api): handle null response
docs(readme): add installation steps

---

Commit Message Guidelines

Good Commit Messages

feat: add password strength indicator

- Show visual feedback for password strength
- Validate minimum requirements
- Display helpful suggestions

Closes #123

fix: prevent duplicate form submissions

Add debounce to submit button to prevent
multiple API calls when user clicks rapidly.

Bad Commit Messages

# Too vague
fix: fix bug

# Not descriptive
update code

# Too long for subject
feat: add new feature that allows users to reset their password by clicking a link sent to their email

Rules

Rule	Example
Subject line max 50 chars	feat: add login page
Use imperative mood	add not added or adds
No period at end of subject	fix: resolve issue not fix: resolve issue.
Blank line between subject and body	See examples above
Body wraps at 72 chars	For readability in terminals
Explain what and why, not how	Code shows how

---

Workflow

Before Committing

# Check status
git status

# Review changes
git diff

# Review staged changes
git diff --staged

Staging Files

# Stage specific files
git add path/to/file.js

# Stage all changes in directory
git add src/

# Stage all tracked files
git add -u

# Interactive staging (select hunks)
git add -p

Creating the Commit

# Commit with message
git commit -m "feat: add user profile page"

# Commit with body (opens editor)
git commit

# Commit with multi-line message
git commit -m "feat: add user profile page" -m "Includes avatar upload and bio editing"

---

Atomic Commits — Granularity Rules

Each commit MUST represent one logical change. When the user asks to commit, analyze git diff and split into multiple commits if the changes span different concerns.

How to Decide

Ask: "If I needed to revert this, would I want to revert ALL of these changes together?" If the answer is no, split them.

Signal	Action
Changes touch different domains/features	Split by domain
Mix of infra + feature code	Separate commits
New dependency + feature using it	Can be one commit (dependency serves the feature)
Tests + implementation they test	Same commit (they're one logical unit)
Formatting/linting + feature changes	Separate commits
Migration + repository + domain changes	Split if they're independently meaningful

Commit Order

When splitting, commits MUST be ordered so the repo compiles and passes tests at every point:

1. Infrastructure/config changes first (dependencies, migrations, configs)
2. Domain/core logic second
3. Application/service layer third
4. Transport/handler layer last
5. Documentation/chore changes independently

Example — What NOT to Do

# BAD: One giant commit mixing everything
git add -A
git commit -m "feat(auth): add multi-role support, postgres, gateway proxy, docker-compose"

Example — Correct Granularity

# 1. Domain change
git add api/auth/internal/auth/domain/
git commit -m "feat(auth): refactor user entity from single role to multi-role

- Change Role field to []Role with HasRole/AddRole/RemoveRole
- Add NewRoles validator with dedup and ErrNoRoles
- Update domain tests for multi-role scenarios"

# 2. Infrastructure adapters
git add api/auth/internal/auth/infrastructure/ api/auth/migrations/ api/auth/go.*
git commit -m "feat(auth): add PostgreSQL repository with pgx and sqlc

- Add user_roles migration and sqlc-generated queries
- Implement PostgresUserRepository and PostgresTokenBlacklist
- Add DB_PROVIDER switch in main.go (memory/postgres)"

# 3. Independent service change
git add api/gateway/
git commit -m "feat(gateway): add reverse proxy forwarding to auth service"

# 4. DevOps/tooling
git add docker-compose.yml Makefile skills/
git commit -m "chore: add docker-compose and local dev workflow"

When a Single Commit Is Fine

• All changes serve ONE purpose (e.g., a bug fix touching 5 files)
• A small feature fully contained in one layer
• Pure refactoring with no behavior change

---

Safety Rules

Never Do

Action	Risk
git commit --amend after push	Rewrites public history
git push --force to shared branches	Overwrites others' work
Commit secrets/credentials	Security breach
Commit large binary files	Bloats repository

Amend Safely

Only amend if ALL conditions are met:

1. Commit has NOT been pushed
2. You are the author
3. No one else has based work on it

# Safe: amend unpushed commit
git commit --amend -m "feat: corrected message"

# Check if pushed
git status  # Shows "Your branch is ahead of..."

---

Files to Never Commit

# Secrets
.env
.env.local
*.pem
credentials.json
secrets.yaml

# IDE
.idea/
.vscode/
*.swp

# Dependencies
node_modules/
vendor/
__pycache__/

# Build artifacts
dist/
build/
*.pyc

---

Commands Reference

# View recent commits
git log --oneline -10

# View commit details
git show <commit-hash>

# Undo last commit (keep changes staged)
git reset --soft HEAD~1

# Undo last commit (keep changes unstaged)
git reset HEAD~1

# Discard last commit entirely (DANGEROUS)
git reset --hard HEAD~1

# Create commit with sign-off
git commit -s -m "feat: add feature"

# Create commit skipping hooks (use sparingly)
git commit --no-verify -m "wip: work in progress"

---

Checklist

• Changes are related and atomic (one logical change)
• Commit message follows conventional format
• Subject line is under 50 characters
• No secrets or credentials included
• Tests pass (if applicable)
• Linting passes (if applicable)