How to Write a Proper Git Commit

In software development, Git commits are essential for tracking changes and collaborating effectively. Crafting a well-written Git commit message enhances code maintainability, aids in project management, and ensures smooth teamwork. Here’s a guide on how to write proper Git commit messages.

1. Start with a Subject Line

The subject line is a brief summary of the change. It should be concise and to the point, ideally 50 characters or less. Use the imperative mood, which conveys a sense of command and action, like a note to oneself or others. For example:

• Good: Add user authentication

• Bad: Added user authentication

2. Separate Subject from Body with a Blank Line

A blank line between the subject and the body improves readability and ensures that tools processing commit messages can distinguish between the two parts.

3. Write a Detailed Body

The body provides more context about the change. Explain what was done and why it was done, including any relevant background information. If applicable, mention any side effects, dependencies, or references to issues and pull requests. The body should be wrapped at 72 characters to make it easier to read in various interfaces.

4. Reference Relevant Issues or Pull Requests

If the commit relates to a specific issue or pull request, include references to them using keywords like Closes, Fixes, or Related to. This helps in automatically linking the commit to the corresponding issue or pull request, providing context and traceability.

5. Use Bullet Points for Multiple Changes

If the commit involves several changes, use bullet points to list them. This structure helps in breaking down complex commits into easily digestible pieces of information.

Commit Types

To further categorize and understand the nature of changes, you can use specific commit types:

• feat: A new feature is introduced with the changes.

• fix: A bug fix has occurred.

• chore: Changes that do not relate to a fix or feature and don't modify src or test files (e.g., updating dependencies).

• refactor: Refactored code that neither fixes a bug nor adds a feature.

• docs: Updates to documentation such as the README or other markdown files.

• style: Changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on.

• test: Including new or correcting previous tests.

• perf: Performance improvements.

• revert: Reverts a previous commit.

Example of a Well-Written Commit Message

feat: Add user authentication

This commit introduces user authentication using JWT tokens. Users can now sign up, log in, and access protected routes.

- Implement JWT token generation and validation - Add middleware for protected routes - Update user model and routes to handle authentication

Fixes #123

Best Practices for Pull Request Titles

When creating a Pull Request (PR), the title is crucial for summarizing the changes and facilitating reviews. Here are some tips for writing effective PR titles:

1. Be Descriptive and Specific: Clearly convey the purpose and scope of the changes.

   • Good: Add JWT-based user authentication

   • Bad: Update code

2. Use the Imperative Mood: Similar to commit messages, use commands to describe what the PR does.

   • Good: Fix user login bug

   • Bad: Fixed the login bug

3. Include Relevant Tags or Prefixes: If your project uses tags or prefixes (like feat, fix, chore), include them for consistency.

   • Good: feat: Add user profile page

   • Bad: Adding user profile page

4. Reference Issues or Tasks: If applicable, reference the issue number or task ID that the PR addresses.

   • Good: fix: Resolve issue #456

   • Bad: Bug fix

Best Practices

1. Commit Often: Make small, frequent commits to track progress and facilitate easier debugging.

2. Avoid WIP Commits: Avoid commits labeled "WIP" (Work in Progress). Instead, use branches for incomplete work.

3. Review Before Committing: Double-check the changes and the commit message before finalizing the commit.