semantic-git

Semantic Git

Manage Git commits using conventional commit format with atomic commits and concise messages.

When to Use Committing changes to git Staging files for commit Creating commit messages Managing atomic commits Before pushing changes Core Principles Atomic commits: Stage and commit related changes together. Tests go with implementation code. User confirmation: Always confirm with user before committing and before moving to the next commit. Conventional format: Use conventional commit message format (feat, fix, etc.) unless directed otherwise. Concise messages: Keep messages brief and to the point. Omit description unless change is complicated. Commit Message Format [optional scope]:

[optional body]

[optional footer(s)]

Types feat: A new feature fix: A bug fix docs: Documentation only changes style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.) refactor: A code change that neither fixes a bug nor adds a feature perf: A code change that improves performance test: Adding missing tests or correcting existing tests build: Changes that affect the build system or external dependencies ci: Changes to CI configuration files and scripts chore: Maintenance tasks (updating build tasks, dependencies, etc.; no production code change) revert: Revert a previous commit Breaking Changes

Use ! after the type/scope to indicate breaking changes:

feat!: add new API fix(api)!: change response format Subject Line Use imperative mood: "add feature" not "added feature" or "adds feature" First letter lowercase (unless starting with proper noun) No period at the end Keep under 72 characters when possible Body and Footer Omit body unless change is complicated or requires explanation When needed, be concise and reference issues, PRs, or documentation Use footer for breaking changes: BREAKING CHANGE: Workflow Implement atomic change: Code + tests together Use test: for test only changes Run CI checks: Verify types, tests, and linting pass before staging Prefer single CI command if exists (e.g., pnpm ci, npm run ci, just ci) If no CI command, run checks individually (typecheck, test, lint) If any check fails, stop and report - do not proceed Stage atomic changes: Group related files together (implementation + tests) Suggest commit message: Generate conventional commit message based on changes Confirm with user: Always ask for confirmation before committing Commit: Execute commit only after user approval Next commit: Before staging next set of changes, confirm with user Automation Mode

If user requests "continue to X" or "automate until X":

Proceed with atomic commits automatically Resume asking for confirmation when X point reached X can be: specific file, feature completion, test passing, etc. Stop and Ask Protocols

Stop and ask user before:

Adding type ignores (@ts-ignore, # type: ignore, etc.) Adding suppressions (ESLint disable, pylint disable, etc.) Using any type or similar type escapes Uncertain how to proceed with implementation Requirements are unclear Examples

Simple feature or behaviour change:

feat: add user authentication

Feature with scope:

feat(api): add user endpoint

Bug fix:

fix: resolve memory leak in cache

Breaking change:

feat!: migrate to new API version

Test-only change:

test: improve unit tests for auth service

Refactor (no behavior change):

refactor: extract validation logic into separate function

Complex change (with body):

feat(api): add pagination support

Implements cursor-based pagination for large datasets. See docs/api/pagination.md for details.

References

For detailed guidance, see:

references/conventional-commits.md - Commit format and examples references/ci-verification.md - CI check patterns and verification