git

name	Git
description	Best practices for git usage, commits, and workflow
version	1.0.0

Commit Messages

Respect Existing Style

Before writing a commit message, inspect the recent history to understand the repo's conventions:

git log --oneline -20

Match the existing style — capitalization, use of scopes, prefix conventions, verbosity of bodies, etc. The Conventional Commits format below is a default; if the repo uses a different consistent style, follow that instead.

Format

Default format (Conventional Commits):

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types: feat, fix, refactor, test, docs, chore, perf, style, ci, build

Rules

• Write in imperative mood: "add feature" not "added feature"
• Keep the subject line to 50 characters or less
• Do not end the subject line with a period
• Separate subject from body with a blank line
• Use the body to explain what and why, not how
• Never mention Claude, AI, or any AI assistant in commit messages, PRs, or issues
• Never include Co-Authored-By: Claude or similar AI attribution lines
• Never include "Generated with Claude Code" or similar AI attribution in PR/issue descriptions

Good Examples

feat(auth): add OAuth2 login flow

Replaces the previous session-based auth with OAuth2 to support
third-party integrations. Token refresh is handled automatically.

fix(parser): handle empty input without panicking

refactor: extract validation logic into separate module

Bad Examples

# Bad: mentions AI
feat: add login (generated by Claude)

# Bad: vague
fix: stuff

# Bad: past tense
fixed: the bug in parser

# Bad: AI co-author
feat: add feature

Co-Authored-By: Claude <[e-mail]>

Staging

Prefer staging specific files over staging everything:

# Good: intentional
git add src/auth.rs tests/auth_test.rs

# Avoid: may include unintended files
git add -A
git add .

Always review staged changes before committing:

git diff --staged

Signing

• Never skip commit signing unless the user explicitly asks you to. Do not pass --no-gpg-sign, and do not disable commit.gpgsign to work around a signing problem.
• If signing fails because the hardware key is unavailable (not plugged in, not tapped, PIN/touch timeout, agent not running), stop and wait for the user. Surface the error and ask them to make the key available — do not retry silently, fall back to an unsigned commit, or disable signing.

Branches

• Use descriptive names: fix/null-pointer-login, feat/oauth2-flow
• Delete branches after merging
• Keep branches short-lived and focused on a single concern

Workflow

1. Pull latest changes before starting work
2. Make small, focused commits — one logical change per commit
3. Write tests before committing new features when applicable
4. Run linters and tests locally before pushing
5. Never push to upstream unless explicitly asked to do so

Amending and History

• Amend only unpushed commits: git commit --amend
• Never force-push to shared branches (main, master, develop)
• Use git rebase -i to clean up local history before pushing

Tags

Use annotated tags for releases:

git tag -a v1.2.3 -m "Release v1.2.3"

Pull Requests

Keep PR titles and bodies short, accurate, and neat.

• Title: a single concise line describing the change (same style as a commit subject).
• Body: a brief summary of what changed and why. A few sentences or a short bullet list is plenty.
• Do not add a "Test Plan" section with checkboxes unless the repo's existing PRs clearly use that convention. Most repos do not.
• Do not pad with boilerplate sections ("Summary", "Motivation", "Testing", "Checklist") when the change is small and self-explanatory.
• Never include AI attribution or "Generated with ..." footers.

Before opening a PR, check recent merged PRs to match the repo's tone and structure:

gh pr list --state merged --limit 10
gh pr view <number>