Skip to content

Latest commit

 

History

History
183 lines (130 loc) · 5.53 KB

2. Writing Good Commit Messages.md

File metadata and controls

183 lines (130 loc) · 5.53 KB
Raw

Writing Good Commit Messages

A well-written commit message is essential for maintaining a clear and understandable project history. This page provides guidelines, examples, and best practices for writing effective commit messages.

1. Why Are Good Commit Messages Important?

  • Improve Collaboration: Help team members understand the purpose of changes.
  • Simplify Debugging: Provide context for troubleshooting and identifying issues.
  • Enhance Documentation: Serve as a log of project evolution.
  • Enable Automation: Facilitate release notes, changelogs, and versioning tools.

2. Anatomy of a Good Commit Message

A typical commit message has two parts:

  1. Subject Line: A concise summary of the changes.
  2. Body (Optional): A detailed explanation of the changes, reasons, and any relevant context.

Example:

Add user authentication to the login page

- Implement password hashing using bcrypt.
- Add user login and logout functionality.
- Update tests to cover new authentication flows.

Fixes issue #42.

3. Rules for Writing Good Commit Messages

1. Keep the Subject Line Short

  • Limit it to 50 characters or less.
  • Summarize the change in a way that’s easy to understand.

2. Use Imperative Mood

Write the subject line as if giving a command:

  • ✅ Add user authentication
  • ❌ Added user authentication
  • ❌ Adding user authentication

3. Provide Context in the Body

Explain:

  • What changes were made.
  • Why the changes were necessary.
  • How they solve the problem.

4. Separate Subject and Body

Leave a blank line between the subject and the body to improve readability.

5. Reference Issues or Tickets

Mention related issue IDs or task numbers:

Fix login bug for admin users (#123)

6. Avoid Ambiguity

Be precise and descriptive to ensure the message is clear.

4. Common Commit Message Types

Type Description Example
Feature Introduces a new feature. Add search functionality to the navbar
Bug Fix Fixes an issue or defect. Fix crash on login page when email is null
Refactor Improves code without changing functionality. Refactor user authentication module
Docs Updates documentation. Add usage examples to the README
Style Changes formatting or code style. Format code to match project style guide
Chore Miscellaneous tasks like dependency updates. Update npm packages to latest versions

5. Commit Message Examples

Example 1: Simple Fix

Fix typo in error message

Example 2: Adding a Feature

Add user profile page

- Create a new UserProfile component.
- Fetch and display user data from the API.
- Add tests for the UserProfile component.

Closes #98.

Example 3: Refactoring Code

Refactor database connection logic

- Extract database connection into a separate module.
- Ensure all services use the shared connection module.
- Improve error handling during database initialization.

6. Best Practices

  • Commit Often: Make small, logical commits instead of large, all-encompassing ones.
  • Avoid WIP Commits: Avoid vague messages like WIP (Work in Progress) or Fix stuff.
  • Use Templates: Establish a standard commit message format for your team.

7. Automating Commit Message Standards

Use Git Hooks

Set up a commit-msg hook to validate commit messages:

#!/bin/bash
# Example commit-msg hook
MESSAGE=$(cat $1)
if ! [[ $MESSAGE =~ ^(Fix|Add|Refactor|Update|Remove|Docs): ]]; then
  echo "Commit message must start with a valid type (e.g., Fix, Add, Refactor)."
  exit 1
fi

Use Commit Message Tools

  • Conventional Commits: Standardizes commit messages for automation.
  • Linting Tools: Use tools like commitlint to enforce rules.

8. Common Git Commands for Commit Messages

Command Description
git commit -m "message" Commit with a single-line message.
git commit Open the default editor for writing a message.
git commit --amend Edit the most recent commit message.

9. Frequently Asked Questions

How Do I Edit the Last Commit Message?

Use the --amend option:

git commit --amend

Can I Enforce Commit Message Standards?

Yes, use Git hooks or tools like commitlint to validate messages.

10. Example Workflow

Step 1: Make Changes

Modify files in your working directory.

Step 2: Stage Changes

git add .

Step 3: Write a Commit Message

git commit -m "Add password hashing for user authentication"

Conclusion

Good commit messages are a cornerstone of effective collaboration and project maintenance. By following best practices and writing clear, concise messages, you ensure that your project history is understandable and useful to all contributors.

Next Steps: Maintaining a Clean History