Commit

Git Commit

Creates git commits following Conventional Commits format with proper type, scope, and subject.

Quick Start

# 1. Stage changes
git add <files>  # or: git add -A

# 2. Create commit (branch commit format)
git commit -m "type(scope): subject

Body explaining HOW and WHY.
Reference: Task X.Y, Req N"

Commit Types

Regular Branch Commits (During Development)

Format: type(scope): subject

Scope (Required, kebab-case)

Examples: validation, auth, cookie-service, template, config, tests, api

Subject Line Rules

• Max 50 characters after colon
• Present tense imperative: add, implement, fix, improve, enhance, refactor, remove, prevent
• NO period at the end
• Specific and descriptive - state WHAT, not WHY

Core Workflow

1. Review Changes

git status
git diff --staged  # if already staged
git diff           # if not staged

2. Stage Files

git add <specific-files>  # preferred
# or
git add -A  # all changes

NEVER commit:

• .env, credentials.json, secrets
• node_modules/, __pycache__/, .venv/
• Large binary files without explicit approval

3. Create Commit

Simple change:

git commit -m "fix(auth): use hmac.compare_digest for secure comparison"

Complex change (with body):

git commit -m "$(cat <<'EOF'
feat(validation): add URLValidator with domain whitelist

Implement URLValidator class supporting:
- Domain whitelist enforcement (youtube.com, youtu.be)
- Dangerous scheme blocking (javascript, data, file)
- URL parsing with embedded credentials handling

Addresses Requirement 31: Input validation
Part of Task 5.1: Input Validation Utilities
EOF
)"

4. Verify Commit

git log -1 --format="%h %s"
git show --stat HEAD

Body Format (Recommended for Complex Changes)

Subject line should be business-friendly — describe the user-facing impact, not implementation details. Use a Technical: section in the body for implementation specifics.

fix(chat): allow retrying assistant responses in chat

Users can now retry an assistant response when the chat
stalls or produces an incomplete answer.

Technical: replace ensureStreamRegistered with
streamManager.register/reopenStream, validate assistant
continuations against last user message state.

For simple/infra-only changes where there is no user-facing impact, a technical subject is fine.

Git Trailers

Place trailers at end of body after blank line. See references/commit_examples.md for examples.

NEVER add Co-Authored-By trailers.

Breaking Changes

For incompatible API/behavior changes, use ! after scope OR BREAKING CHANGE: footer:

feat(api)!: change response format to JSON:API

BREAKING CHANGE: Response envelope changed from `{ data }` to `{ data: { type, id, attributes } }`.

Triggers major version bump in semantic-release.

Merge Commits (PR Closure)

For PRs, use extended description with sections:

gh pr create --title "feat(security): implement input validation (Task 5)" --body "$(cat <<'EOF'
## Summary
- Input validation utilities (URLValidator, FormatValidator)
- Secure template processor with path traversal prevention
- API key authentication middleware

## Task Breakdown
Task 5.1: Input Validation - URLValidator, FormatValidator
Task 5.2: Template Processing - Path traversal prevention
Task 5.3: API Key Auth - Multi-key support, excluded paths
Task 5.4: Security Tests - 102 path traversal tests

## Requirements Covered
Req 7, Req 9, Req 31, Req 33

## Test Coverage
- All 473 tests passing
- Coverage: 93%
- Pre-commit checks: passing
EOF
)"

Integration with Other Skills

From github-pr-review

When fixing review comments, use this format:

git commit -m "fix(scope): address review comment #ID

Brief explanation of what was wrong and how it's fixed.
Addresses review comment #123456789."

From github-pr-creation

Before creating PR, ensure all commits follow this format. The PR skill will:

1. Analyze commits for proper format
2. Extract types for PR labels
3. Build PR description from commit bodies

Important Rules

• ALWAYS include scope in parentheses
• ALWAYS use present tense imperative verb
• ALWAYS ask to split when staged changes span unrelated concerns
• ALWAYS write subject lines that are business-friendly (user-facing impact) when there is a user-facing change; use Technical: section in body for implementation details
• NEVER end subject with period
• NEVER commit secrets or credentials
• NEVER use generic messages ("update code", "fix bug", "changes")
• NEVER exceed 50 chars in subject line
• NEVER add Co-Authored-By trailers
• Use --no-verify when pre-commit hooks fail due to staging conflicts (e.g., AD file status causing lint-staged merge errors), not to skip linting
• Group related changes -> single focused commit

Examples

Good:

feat(validation): add URLValidator with domain whitelist
fix(auth): use hmac.compare_digest for secure key comparison
refactor(template): consolidate filename sanitization logic
test(security): add 102 path traversal prevention tests

Bad:

update validation code           # no type, no scope, vague
feat: add stuff                  # missing scope, too vague
fix(auth): fix bug               # circular, not specific
chore: make changes              # missing scope, vague
feat(security): improve things.  # has period, vague

References

• references/commit_examples.md - Extended examples by type