# Git Commit Message Guidelines for Production A well-written commit message is just as important as writing clean code. It helps your team understand **what changed**, **why it changed**, and makes debugging, code reviews, and release management significantly easier. --- # Commit Message Format Follow this structure for every commit: ```text (): ``` Example: ```text feat(auth): add Google OAuth login Implemented Google OAuth authentication using Passport.js. Added automatic account linking for existing users. Closes #123 ``` --- # Subject Line Rules The subject (first line) should follow these rules: - Maximum **50 characters** (recommended) - Start with a lowercase commit type - Use the imperative mood - Do not end with a period (`.`) - Be specific - Describe **what the commit does**, not what you did ✅ Good ```text feat(auth): add password reset flow ``` ```text fix(api): validate email before saving ``` ```text docs: update Docker deployment guide ``` ❌ Bad ```text Fixed bug ``` ```text changes ``` ```text Update ``` ```text working ``` --- # Body Rules The body is optional but highly recommended for medium or large changes. Explain: - Why the change was needed - What was changed - Any side effects - Any migration steps Wrap lines around **72 characters**. Example: ```text fix(cache): prevent duplicate cache writes The cache layer was writing duplicate entries whenever multiple requests hit the endpoint simultaneously. Added a distributed lock before cache writes to ensure only one request populates the cache. ``` --- # Footer Rules Use the footer for: - Issue references - Breaking changes - Pull requests - Security notes Example ```text Closes #42 ``` ```text Fixes #18 ``` ```text BREAKING CHANGE: API now requires authentication ``` --- # Commit Types ## feat A new feature. ```text feat(auth): add GitHub login ``` --- ## fix Bug fixes. ```text fix(api): prevent duplicate user creation ``` --- ## docs Documentation only. ```text docs: update installation guide ``` --- ## style Formatting changes only. No logic changes. ```text style: format code with Prettier ``` --- ## refactor Code improvements without changing behavior. ```text refactor(database): simplify query builder ``` --- ## perf Performance improvements. ```text perf(api): reduce database queries ``` --- ## test Adding or updating tests. ```text test(auth): add login integration tests ``` --- ## build Changes affecting build tools or dependencies. ```text build: upgrade Node.js to v24 ``` --- ## ci Changes to CI/CD pipelines. ```text ci: add Docker image publishing ``` --- ## chore Maintenance tasks. ```text chore: remove unused dependencies ``` --- ## revert Revert a previous commit. ```text revert: revert OAuth implementation ``` --- ## security Security-related fixes. ```text security(auth): sanitize JWT payload ``` --- # Scope The scope tells which part of the project changed. Examples: ```text auth ``` ```text api ``` ```text database ``` ```text docker ``` ```text ui ``` ```text payment ``` ```text email ``` ```text admin ``` ```text config ``` ```text ci ``` Example: ```text feat(payment): add Stripe webhook ``` --- # Good Examples Small feature ```text feat(user): add profile picture upload ``` Bug fix ```text fix(auth): prevent expired token reuse ``` Documentation ```text docs: add environment setup guide ``` Docker ```text build(docker): reduce image size ``` CI ```text ci(github): deploy Docker image after merge ``` Refactor ```text refactor(api): split validation logic ``` Performance ```text perf(database): add index to users table ``` Security ```text security(api): validate JWT issuer ``` --- # Large Commit Example ```text feat(payment): integrate Stripe subscriptions Added subscription creation and cancellation endpoints. Implemented Stripe webhook verification. Stored subscription status in the database. Added retry logic for failed webhook events. Closes #245 ``` --- # What NOT to Write Avoid messages like: ```text update ``` ```text changes ``` ```text working ``` ```text bug fixed ``` ```text done ``` ```text final ``` ```text temp ``` ```text misc ``` ```text test ``` These provide no useful information. --- # Production Commit Checklist Before committing, verify: - Subject is under 50 characters - Uses the correct commit type - Includes a scope when appropriate - Uses imperative mood - No period at the end of the subject - Explains **what** the change does - Body explains **why** for non-trivial changes - References related issues if applicable --- # Recommended Commit Workflow ```text 1. Make one logical change 2. Review the diff 3. Write a meaningful commit message 4. Commit 5. Push 6. Open a Pull Request ``` --- # Conventional Commit Cheat Sheet | Type | Purpose | |------|----------| | feat | New feature | | fix | Bug fix | | docs | Documentation | | style | Formatting only | | refactor | Code restructuring without behavior changes | | perf | Performance improvement | | test | Tests | | build | Build system or dependencies | | ci | CI/CD changes | | chore | Maintenance tasks | | revert | Revert previous commit | | security | Security improvements | --- # Final Example ```text feat(notification): add email queue support Implemented asynchronous email delivery using RabbitMQ. Added retry handling for failed jobs. Improved delivery reliability during high traffic. Closes #321 ``` This style follows the **Conventional Commits** specification and is widely used in production environments. It improves collaboration, enables automated changelog generation, semantic versioning, and makes project history easier to understand.