Tips to write a clean commit history in Git

Introduction

Git is one of the most important tools. Not only does Git keep a history of projects, but it also makes collaboration easy between teams. Although it is such a valuable tool, it is often overlooked or underutilized.

Clean Git history tells the story of a project and is easy to understand. The process of adding features and implementing them is evident. Clean Git histories are something I cherish on a project. The good news is, maintaining a clean history is not difficult.

Here are some tips for achieving a clean history in git

What is Git history

The way Git represents history is fundamentally different from the way centralized version control systems (CVCS) such as Team Foundation Version Control, Perforce, and Subversion represent history in their own way. Each file in a repository has its own history in centralized systems. Git stores history as a graph of snapshots of each part of the repository at any given time. There can be multiple parents for these snapshots in Git, creating a graph-like history instead of a line. Git's history is incredibly different from CVCS, which is one of the main reasons users find it confusing.

Importance of meaningful Git history

A commit message is a fingerprint you leave on a piece of code. If you look at the same change in a year, you will be grateful for the clear, meaningful commit message that you wrote, and it will also make your fellow developers' lives better. Isolating commits by context makes it easier to find bugs introduced by a certain commit, making it easier to revert the commit that introduced the bug. Writing clean commit histories has taught me the following things.

It facilitates the review process of pull requests. Commits that are organized well give a better understanding of the topic.

The reviewers will not be stressed if the code is organized into small commits.

Reviewers use it to catch bugs or mistakes in pull requests.

The way you organize and structure code into meaningful commits reflects your understanding and approach to a particular problem.

Tips to maintain a clean Git history

Here are five tips for maintaining a clean Git history

Work on a branch at all times

The benefits of working with branches are numerous. First, by working on a branch rather than the main branch, a developer avoids polluting the main branch with work-in-progress commits. A branch also makes it easier for multiple people to work on a feature set at the same time. The use of branches assists in condensing the work on a feature into a few logical commits

Observe and follow style guidelines

Describe the effect your change will have in a clear and descriptive manner. Be consistent when writing commit messages (use the imperative or past tense). Often your future self will be reading your commit so a brief explanation of its purpose is necessary. Rather than "fix titles", it is better to "fix error loading Python DLL". Keep your commit messages under 50 characters, since someone is reading your commit log for a quick summary of changes. Each commit includes your name and date, so you don't have to add them yourself. It facilitates the review process of pull requests. Commits that are organized provide a better understanding of the topic.

Practice Merge and Squash

In a project, the main branch should contain a high-level summary. It should be straightforward to locate when and how features were implemented. In order for a feature to be fully rolled up, it needs to be squashed again when it is merged with git merge --squash. Before merging, all commits will be rolled into a single one. This is convenient since all commit messages are contained within a single message.

Take a look at it from another person's perspective

It should be easy for someone with only a general understanding of the application to understand this nicely squashed set of commits. In most cases, it's difficult to summarize your work in 50 characters. Whenever possible, include bullet points or paragraphs in the commit message as per styling guidelines. Think of your writing as a billboard, not a dissertation. Get another person's opinion on your commit message before merging your code-reviewed feature into 'master'. You succeeded if they could read and understand your changes quickly and easily.

Deleting the branch when needed

The longer branches remain, the more confusion there will be. Did that branch already merge? Was there still work to be done? Could it have been a spike that should never have been merged?

Delete branches as soon as they have served their purpose to avoid confusion. It is possible to delete a branch locally and remotely with the help of an awesome Git extension project. The process is as simple as running git delete-branch <branch>.

Conclusion

It takes discipline to keep a clean Git history. If these steps are followed, reading a project's history is simple. How do you maintain a clean history of your projects?