Writing a Good Git Commit

Introduction

Before we delve into writing good Git commits, it's essential to have a basic understanding of the Git workflow. If you're new to Git, I recommend reading through the Git Handbook first. Now, let's talk about what a commit is in Git.

In simple terms, a Git commit is like a snapshot that records changes you make to the files in a Git repository. Each commit comes with a commit message that describes the changes you've made.

What makes a Good Commit ?

It's simple: when you look at previous commit messages using the git log command, and you can easily understand what each commit does and the changes made, then you're doing it right. However, if your commit messages are confusing or unclear, there's room for improvement. Clear and descriptive commit messages are essential for effective version control and collaboration.

Why should you write good commit message ?

1. A good commit message helps you communicate clearly with your team and your future self. When others look at your commits, they can quickly understand what changes you made and why you made them. This clarity saves time and reduces confusion.
2. Commits serve as a history of your project's development. Good commit messages act like short documentation, showing the evolution of the code over time.
3. Easier bug tracking.
4. When collaborating with other developers, they will review your code through pull requests or code reviews. A clear commit message helps them understand your changes without having to dig into the code right away. It also facilitates discussions about the code changes.

Git Commit Workflow

Before writing top notch commit message we need to understand the workflow associated with making commit message. In order to make a commit, a developer must :

1. Create and Add a File
   
   
2. Stage Changes
   
   
3. Create a Commit

4. View Commit History using git log

Git Commit Message Structure

There are two main components of a Git Commit Message: the title or summary and description.

The basic commit message structure that most of us are familiar with is:

git commit -m <message>

However, we can also write a more detailed commit message using the following format: :

git commit -m <title> -m <Description>

Steps to write better commit message

1. Consistency is Key: Whether you're working alone or in a team, consistency is important. Follow agreed commit message guidelines to maintain a uniform and easily understandable commit history.
2. Use Imperative Mode: Write the subject line in the imperative mode (e.g., "Fix," "Add," "Update") to clearly indicate what the commit does.
3. Keep It Concise: Limit the subject line to no more than 50 characters and the commit body to 70 characters. This ensures that commit messages are concise and easy to read.
4. Include Task IDs: If you are working on specific features, bugs, or tasks with IDs (e.g., Jira or project management IDs), include them in the commit body or in commit summary. This links the commits to their respective tasks, aiding in project management.
5. Be Specific: Avoid vague commit messages. Instead, be specific about the changes made in the commit, describing what was fixed, added, or updated.

Example

Bad

git commit -m "Add README.md file"

Good

git commit -m "STORY-123: Add README.md with project description" -m "Created a new 'README.md' file to provide essential information about the project. The README includes a brief project description, installation instructions, and usage guidelines"

Conventional Commits

Conventional commits are a way to enhance our commit messages and bring them to a higher standard. With this approach, commit messages start with a specified commit type, such as

Feat– feature

Fix– bug fixes

Docs– changes to the documentation like README

Style– style or formatting change

Perf – improves code performance

Test– test a feature

The commit type subject line should be all lowercase with a character limit.

To ensure that these committing conventions remain consistent across developers, commit message linting can be configured before changes are able to be pushed up.

Commitizen is a great tool to enforce standards, sync up semantic versioning, along with other helpful features.

Let us add README.md file in one of the project . I assume you have successfully installed Commitizen on your computer, you can follow these steps to make a commit using it:

1. Stage Your Changes: Use the git add command to stage the changes you want to include in the commit. For example, you can use git add filename to stage specific files, or git add . to stage all changes.
2. Commit Using Commitizen: Instead of the regular git commit command, use cz commit to make a commit with Commitizen.
3. Select Commit Type: A dialogue box will appear on the screen, asking you to choose the type of commit. In your case, since you're adding a README file, you'd select "docs" as the commit type.
4. Skip Scope: The next prompt will ask you about the scope of the change.You can skip this by pressing Enter.
5. Write Commit Title: You'll be asked to write a short and clear summary of the changes made. This will serve as the title of your commit message. Use lowercase letters and avoid using periods at the end.
6. Add Description (Optional): If you want to provide more details about the changes made, you can write a description. Press Enter if you don't want to add any further information.
7. Breaking Change (Optional): If your commit introduces a breaking change (significant changes that might affect existing code), you'll be asked to indicate it. In your case, you've answered "No" (as "N").
8. Footer Information (Optional): The last prompt will ask for footer information, but you can skip it if you don't need to provide any additional details.

Conclusion

Writing good commit messages is important because it helps team members understand the changes made in a commit quickly and reduces confusion. Clear messages serve as documentation for the project's history and make bug tracking easier. Using a consistent format like Conventional Commits and keeping messages concise and descriptive enhances collaboration and efficiency in software development.

For more queries regarding Git commit feel free to DM me . I would be more than happy to help.

Happy Commiting 😊 !