Overview

A well-structured commit message helps teams understand the history of changes in a project. The Conventional Commits format provides a consistent structure, making it easier to track changes, automate releases, and improve collaboration.

Commit Message Format

Each commit message should follow this format:

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

[optional longer description]
[optional references/issues]

1️⃣ Commit Types

Type	Description
feat	Introduces a new feature
fix	Fixes a bug
refactor	Code changes that do not fix a bug or add a feature
chore	Routine tasks like dependency updates
docs	Documentation updates
style	Code formatting (no logic changes)
test	Adding or updating tests
perf	Performance improvements
ci	CI/CD-related changes
build	Build-related changes (e.g., dependencies)
revert	Reverts a previous commit

2️⃣ Commit Scope (Optional but Recommended)

The <scope> helps specify which part of the project is affected by the commit. Some common examples:

• db → Changes in database models or migrations
• api → Backend API changes
• auth → Authentication logic
• ui → User interface updates
• tests → Unit or integration tests
• docs → Documentation files

Example:

git commit -m "fix(auth): resolve login issue with expired token"

3️⃣ Short Description (Required)

• Use present tense: "fix" not "fixed" or "fixes"
• Be concise but descriptive
• Avoid generic messages like "update code"

✅ Good Example:

git commit -m "feat(api): add OAuth login support"

❌ Bad Example:

git commit -m "updated something"

4️⃣ Longer Description (Optional, but Useful)

If a commit needs more context, add a description below the short summary. Separate it with a blank line.

Example:

fix(auth): resolve login issue with expired token

Previously, users were unable to refresh tokens after expiration. This fix ensures that the refresh token mechanism works correctly.

5️⃣ Reference Issues or Pull Requests (Optional, but Recommended)

If the commit is related to a GitHub/GitLab issue, include a reference.

Example:

git commit -m "fix(payment): resolve duplicate transactions (#123)"

For closing issues automatically:

git commit -m "fix(profile): fix avatar upload issue, closes #456"

---

Examples of Good Commit Messages

1️⃣ Feature Addition

git commit -m "feat(dashboard): add user analytics panel"

2️⃣ Bug Fix

git commit -m "fix(profile): resolve avatar upload issue"

3️⃣ Refactoring Code

git commit -m "refactor(api): optimize query for better performance"

4️⃣ Updating Documentation

git commit -m "docs(readme): update setup instructions"

5️⃣ Dependency Updates

git commit -m "chore(deps): update Laravel to 10.x"

---

Best Practices

✅ Use Present Tense:

• ❌ "Fixed login issue"
• ✅ "fix(auth): resolve login issue"

✅ Be Specific:

• ❌ "Updated something"
• ✅ "feat(ui): add dark mode toggle"

✅ Keep it Short & Clear:

• Ideal length: 50-72 characters for the short summary
• Use a longer description when necessary

✅ Use Scopes for Clarity:

• Helps understand which part of the project is affected

✅ Reference Issues & PRs:

• Helps track commits related to specific tickets

✅ Write Meaningful Messages:

• A commit should describe what changed and why

---

Automating Commit Messages

To ensure consistency, teams can use tools like:

• Commitizen (npx cz for guided commit messages)
• Husky (for enforcing commit linting)
• Lint-staged (to check staged files before committing)

Example setup for enforcing commit message rules:

npm install -g commitizen
commitizen init cz-conventional-changelog --save-dev --save-exact

Now, run:

npx cz

This will prompt you to enter a properly formatted commit message.

---

Conclusion

Following a structured commit convention improves project maintainability, collaboration, and automation. Using Conventional Commits, teams can easily understand the history of changes, automate releases, and integrate with CI/CD pipelines.

By adopting these practices, your Git commits will become clearer, more meaningful, and easier to track. 🚀