tomevault-io Git Conventions
A comprehensive reference for Git best practices. Use this skill when you need to follow or enforce Git conventions.
Conventional Commits
Format:
type(scope): subject
[optional body]
[optional footer]
Types
| Type | Emoji | Description | Example |
|---|---|---|---|
feat |
✨ | New feature | feat(auth): add password reset |
fix |
🐛 | Bug fix | fix(cart): prevent negative quantity |
docs |
📝 | Documentation | docs(readme): add installation steps |
style |
💄 | Formatting, no code change | style: fix indentation |
refactor |
♻️ | Code change, no behavior change | refactor(api): extract validation logic |
perf |
⚡ | Performance improvement | perf(query): add index on user_id |
test |
✅ | Adding/updating tests | test(auth): add login edge cases |
build |
📦 | Build system, dependencies | build: upgrade webpack to v5 |
ci |
👷 | CI configuration | ci: add GitHub Actions workflow |
chore |
🔧 | Maintenance tasks | chore: update .gitignore |
revert |
⏪ | Revert a commit | revert: feat(auth): add password reset |
security |
🔒 | Security fix | security(deps): patch vulnerable package |
Subject Rules
- Use imperative mood: "add" not "added" or "adds"
- Maximum 50 characters
- Lowercase (no capitalization)
- No period at the end
Body Rules
- Explain the "why", not the "what"
- Wrap at 72 characters
- Separate from subject with blank line
- Plain text only — no markdown, no bullets, no headers
- Use blank lines to separate paragraphs if needed
Footer Rules
- Reference issues:
Closes #123,Fixes #456,Refs #789 - Breaking changes:
BREAKING CHANGE: description
Breaking Changes
Two ways to indicate:
feat(api)!: change response format
BREAKING CHANGE: The API now returns data in a nested structure.
Or just the footer:
feat(api): change response format
BREAKING CHANGE: The API now returns data in a nested structure.
Branch Naming
Format: type/short-description
Patterns
| Type | Pattern | Example |
|---|---|---|
| Feature | feat/description |
feat/user-authentication |
| Bug fix | fix/description |
fix/login-redirect |
| Hotfix | hotfix/description |
hotfix/payment-crash |
| Release | release/version |
release/1.2.0 |
| Docs | docs/description |
docs/api-reference |
| Refactor | refactor/description |
refactor/database-layer |
| Test | test/description |
test/e2e-checkout |
Rules
- Lowercase only
- Use hyphens, not underscores
- Keep it short but descriptive
- Include ticket number if applicable:
feat/AUTH-123-password-reset
Pull Request Standards
Title
Same format as commits:
✨ feat(auth): add password reset flow
🐛 fix(orders): prevent duplicate submission
Description Structure
## What
[Brief description — what this PR does]
## Why
[Context — why is this change needed]
## Changes
- [Key change 1]
- [Key change 2]
## How to Test
1. [Step 1]
2. [Step 2]
3. [Expected result]
## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
## Related
Closes #123
Release Versioning (SemVer)
Format: MAJOR.MINOR.PATCH
| Increment | When | Example |
|---|---|---|
| MAJOR | Breaking changes | 1.0.0 → 2.0.0 |
| MINOR | New features (backward compatible) | 1.0.0 → 1.1.0 |
| PATCH | Bug fixes (backward compatible) | 1.0.0 → 1.0.1 |
Pre-release Tags
- Alpha:
1.0.0-alpha.1 - Beta:
1.0.0-beta.1 - Release candidate:
1.0.0-rc.1
Changelog Format (Keep a Changelog)
## [1.2.0] - 2025-01-10
### Added
- New feature description
### Changed
- Change description
### Deprecated
- Deprecated feature
### Removed
- Removed feature
### Fixed
- Bug fix description
### Security
- Security fix description
Mapping from Commits
| Commit Type | Changelog Section |
|---|---|
feat |
Added |
fix |
Fixed |
perf |
Changed |
refactor |
Changed (if notable) |
security |
Security |
deprecate |
Deprecated |
remove |
Removed |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.