PERSONAL BLOG

Write proper commit messages

xharlessnow's photo
xharlessnow
·

2 min read

Writing good commit messages is essential for maintaining a clean and understandable version control history. A well-written commit message helps you and your collaborators understand what changes were made and why.

Here’s a structured guide to writing effective commit messages:

1. Use the Proper Format

A common format for commit messages is:

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

[optional body]

Example:

feat(auth): add user login functionality

This adds support for user authentication via email and password. Includes error handling for invalid credentials.

2. Common Commit Types

Use conventional types to clarify the purpose of the commit:

  • feat: A new feature

  • fix: A bug fix

  • docs: Changes to documentation

  • style: Changes that do not affect the code's meaning (e.g., formatting)

  • refactor: Code changes that neither fix a bug nor add a feature

  • perf: Code changes to improve performance

  • test: Adding or fixing tests

  • chore: Maintenance or configuration tasks (e.g., updating dependencies)

3. Write Descriptive Commit Titles

The title should be concise and summarize the change:

  • Good: fix(navbar): resolve dropdown positioning issue

  • Bad: fixed bug

4. Use an Optional Body for Complex Changes

If your change requires additional context, include a body:

  • Explain what was changed.

  • Explain why it was changed.

  • Include any necessary information for reviewers.

Example:

fix(api): handle API error for invalid requests

Previously, the application crashed when an invalid request was sent to the API. 
This fix adds error handling to display a user-friendly message instead.

5. Keep Titles Short and Capitalize

  • Limit the title to 50 characters or fewer.

  • Capitalize the first word.

  • Don’t end with a period.

6. Avoid WIP (Work In Progress) Messages

Commits like WIP, stuff, or fixing bugs are unhelpful. Write meaningful messages even for incomplete work.

Example:

Instead of:

WIP

Use:

feat(homepage): implement layout for hero section (WIP)

7. Break Changes into Multiple Commits

If you’re working on multiple changes, don’t lump them into one commit. For instance:

  1. feat(header): add responsive navbar

  2. style(navbar): adjust padding and spacing

8. Example Commit Message Series

Here’s how commits might look for a feature:

  1. feat(homepage): create layout for hero section

  2. style(homepage): apply styles to hero section

  3. fix(homepage): correct alignment issue in hero text

9. Tools to Help You

  • Git Commitizen: Ensures standardized commit messages.

  • Linting tools (e.g., commitlint) to validate your commit format.

By practicing these techniques, you’ll improve over time, and your commit history will become much cleaner and easier to understand.

Web Developmentcommits