Conventional Git Commits With Best Practices.

This article is not a guide on how to push your code to Git. Instead, it focuses on best practices for writing effective Git commit messages. A Git commit is a critical part of the software development process. Poorly written commit messages can lead to confusion, hinder collaboration, and negatively impact the productivity of a development team.

Learning to write clear and meaningful commit messages is essential for maintaining a high-quality codebase. In this article, I will explore some of the best practices for creating well-structured commit messages, using the Conventional Commits standard as an example. This standard provides a structured approach to writing commit messages, making them more informative and easier to understand for everyone on the team.

By following these guidelines, you can improve the readability and maintainability of your project’s history, streamline collaboration, and even simplify automation tasks like versioning and changelog generation. Let's directly dive into the main point.

The Basic Convention of a Good Git Commit

A well-structured Git commit message typically follows this format:

<type> [optional scope] : <description>

[optional body]

[optional footer(s)]

Examples of commit types

Commit messages can vary depending on the task you are working on. Here are some common conventions for different scenarios:

1. feat : New Features

   1. Description: Introduces a new feature or enhancement.

      1. Example:

      feat(auth): add login functionality.
      feat(ui)  : improve button desing
      

2. fix: Bug Fixes

   1. Description: Fixe a bug in the codebase.

      1. Example:

      fix(api): resolve timeout issue
      fix(ui) : correct alignment of navbar
      
      

3. docs: Documentation

   1. Description: Updates or improvements to documents to documentation (README, code comments, etc.).

      1. Example:

      docs: update README with installation steps
      docs(api): add missing function descriptions
      

4. style: Code Styling

   1. Description: Changes that do not affect functionality (formatting, spacing, linting).

   style: fix ESLint warnings
   style: reformat code for consistency
   

5. perf: Performance Improvements

   1. Description: Enhances performance without changing functionality.

   perf: optimize database queries
   perf(ui): reduce image loading time
   

6. refactor: Code Refactoring

   1. Description: Improves code structure or readability without changing functionality.
      

      refactor: simplify user validation logic
      refactor(api): split large functions into smaller ones
      

7. test: Tests

   1. Description: Adds or updates test cases.

      1. Example:

      test: add unit tests for login service
      test(api): update integration tests for payment gateway
      

8. chore: Maintenance

   1. Description: Miscellaneous tasks like dependency updates or build changes.

      1. Example:

      chore: update dependencies to latest versions
      chore(ci): configure GitHub Actions for CI/CD
      

9. build: Build Changes

   1. Description: Changes to the build system or external dependencies.

      1. Example:

      build: upgrade webpack to v5
      build: add Babel support for modern JS features
      

10. ci: Continuous Integration

    1. Description: Updates related to CI/CD pipelines or automation scripts.

       1. Example:

       ci: fix Dockerfile for deployment
       ci: update GitHub Actions workflow
       

11. revert: Reverts

    1. Description: Reverts a previous commit.

       1. Example:

        revert: revert "feat(auth): add login functionality"
       

12. BREAKING CHANGE : Breaking API/Functionality

    1. Description: A commit introducing a breaking change in the codebase.

    2. Usage: Add ! to the type or include BREAKING CHANGE **** in the footer.

       1. Example:

       feat(api)!: rename `getUser` to `fetchUser`
       
       BREAKING CHANGE: `getUser` is replaced by `fetchUser` to improve naming consistency.
       

Combination commit messages

In some cases, you may combine multiple changes into one messages:

feat(auth): add forgot password feature and update login API
fix(auth): resolve token expiration issue

Multiline commit messages:

Method 1: Inline with the -m Option

You can provide multiple -m flags to add different lines to your commit message. For example:

git commit -m "feat(auth): add forgot password feature" -m "Added email verification for password resets." -m "Updated login API with enhanced security measures."

This approach is quick but not ideal for detailed or formatted commit messages since it can get cumbersome for longer descriptions.

Method 2: Use a Text Editor for the commit message

• Start the commit without a message: Run the git commit command without the -m flag:

git commit

• Edit the commit message in Your default text editor: Your default text editor (like vim, nano or another configured editor) will open, allowing you to write a detailed, multiline commit message. Example in the editor:

feat(auth): add forgot password feature

- Added email verification for password resets.
- Updated login API with enhanced security measures.

Save and close the editor:
After writing the message, save the file and close the editor. The commit will be created with your multiline message.

how to save and exit when writing a commit message in vim or nano:

Here’s how to save and exit when writing a commit message in vim or nano:

In vim :

1. Write your commit message: Type the commit message as needed in the editor.

2. Save and exit:

   • Press Esc to exit insert mode.
   • Type : wq (short for "write and quit") and press Enter.
   • This saves the file and exits vim.

3. Alternative commands:

• To save without exiting, type :w and press Enter.
• To exit without saving, type :q! and press Enter.

In nano

1. Write Your commit Message:
   Type the commit message directly into the editor.

2. Save and exit:

   • Press Ctrl + O (Write Out) to save the file.
   • Press Enter to confirm the filename (usually pre-filled).
   • Then press Ctrl + X to exit nano.

3. Cancel without saving:

   • Press Ctrl + X and when prompted to save changes, type N for "No."

Tips for writing effective commit messages

1. Use Imperative Tone (Present Tense) :
   1. Good: fix: resolve issue with pagination.
   2. Bad: fixed issues with pagination.
2. Be Specific:
   1. Good: feat(ui): add tooltip to icons.
   2. Bad: feat: update UI
3. Keep It Short: Aim for under 50 characters in the header.

Best Wishes.
you can find me on Github : anikakash