Git Conventions

These conventions MUST be followed when performing any Git operations in this project.

Commit Messages

Use Conventional Commits format:

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

[optional body]

[optional footer(s)]

Types

Rules

• Write commit messages in English
• Use the imperative mood in the description (e.g., "add feature" not "added feature")
• Keep the first line under 72 characters
• Minimize use of the optional body — most commits should be a single subject line
• When a body is used, describe only why the change was made, not what was changed. The "what" is already visible in the diff — do not repeat it
• When an AI agent authors or co-authors the commit, include a Co-Authored-By footer with the agent's name and model identifier (e.g., Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>)

Command

Stage specific files and commit using a HEREDOC for the message:

bash
1git add <file1> <file2> ...
2git commit -m "$(cat <<'EOF'
3<type>(<optional scope>): <description>
4
5[optional body]
6
7Co-Authored-By: <Agent Name> <email>
8EOF
9)"

Examples

feat: add monthly expense summary view

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: handle empty input gracefully

Co-Authored-By: GPT-4o <noreply@openai.com>

fix: correct date parsing for transaction import

refactor: extract validation logic into shared module

Previous approach duplicated validation across three endpoints,
making it easy to introduce inconsistent behavior when rules change.

Branch Naming

Use the format: <type>/<description>

• Use kebab-case for the description
• Keep it concise but descriptive
• Use the same type prefixes as commit messages

Examples

feat/add-expense-categories
fix/date-parsing-error
docs/update-api-reference
chore/upgrade-dependencies
refactor/simplify-transaction-model

Pull Requests

Merge Strategy

Use merge commits (not squash or rebase). This preserves the full commit history of the branch.

PR Guidelines

• PR title should follow Conventional Commits format
• PR description should summarize what changed and why
• Keep PRs focused on a single concern
• Do not include information that is already visible elsewhere on the PR or that becomes stale when the branch is updated. Specifically:
  • CI-verifiable facts (e.g., "all tests pass", "no clippy warnings") — visible in CI status checks
  • Lists of changed files — visible in the "Files changed" tab
  • Task checklists or test plans — tracked in CI

Command

Push and create PR using gh:

bash
1git push -u origin <branch-name>
2gh pr create --title "<type>(<optional scope>): <description>" --body "$(cat <<'EOF'
3<summary of what changed and why>
4
5🤖 Generated with <agent name and link>
6EOF
7)"

Protected Operations

• NEVER force push (git push --force or --force-with-lease) to main or master
• NEVER use git reset --hard on shared branches
• Always confirm with the user before performing destructive Git operations

References

• How to Write a Git Commit Message — Chris Beams. The "why not what" principle in this project's commit rules is based on this article.