Anas Anjaria
Anas Anjaria's blog

Anas Anjaria's blog

4 Tips to Write Clean Commit History in Git

Photo by Yancy Min on Unsplash

4 Tips to Write Clean Commit History in Git

Even if you are a beginner, you can learn and understand it easily.

Anas Anjaria's photo
Anas Anjaria
·Aug 30, 2022·

4 min read

Subscribe to my newsletter and never miss my upcoming articles

Are you using git and struggling to organize your work in clean commits? When you start working on your task, you might push all your changes in one big commit.

I know how you feel because that’s how I used to work when I was a beginner. Over time I learned to write clean commit history, and I am happy to share it with you.


Motivation — Why clean commit history?

Before we dive into this topic, let me explain its significance. Here are the things I have learned about writing clean commit history.

  1. It facilitates reviewers at the time of reviewing our pull requests. It gives a better understanding of the topic when you organize commits well.
  2. Organizing code into small commits will not stress out reviewers.
  3. It helps reviewers to catch bugs or mistakes within a given pull request.
  4. Organizing and structuring code into meaningful commits reflects your understanding of a specific problem and the way you are trying to solve it.

Here are my four tips. I usually apply these strategies whenever I work on a task. Please note that there is no hard and fast rule.

Don’t mix refactoring with the business logic adjustments

It is a common mistake to mix refactoring and adjusting business logic to support the new features within the same commit. Please avoid doing that. It makes it harder for reviewers to understand both at the same time.

I would recommend making two commits. The first commit should cover only code refactoring without modifying existing business logic. Refactoring may include improving code readability or applying code styling etc. Add or adjust business logic in the second commit.

Make configuration changes visible

Configuration changes are vital and need to be reviewed carefully. Make those changes visible to reviewers by committing them in a separate commit.

Removing anything from a repository

I have read in this article that

Experienced software engineers know that the best engineers often remove code when solving problems rather than adding code.

So when you remove any code, ensure to do it in a separate commit. Also, ensure to document and explain the reason for removal within the commit description.

This way, you are not only documenting it for the future but also conveying the context to reviewers.

Skeleton followed by implementation

If you are working on a feature with complex business logic, I would recommend structuring your code into smaller commits or multiple pull requests.

One suggestion in this regard would be to add a commit that covers solely business logic without going into details. That’s what I meant by skeleton followed by implementation.

Consider the following example written in Scala. So, this would be your first commit.

def process(email: String): Unit = {
  val user = getUser(email)
  val score = calculateScore(user.id)
  storeScore(score)
}
def getUser(email: String): User = ???
def calculateScore(userId: Int): Int = ???
def storeScore(score: BigDecimal): Unit = ???

The upcoming commits would implement individual methods with their respective unit tests.

This is just an example but you can think of it as implementing DAO, Service, and Controller layer. The above approach is useful if you are following from top to bottom i.e from controller layer to DAO.

Usually, I prefer from bottom to top i.e from DAO to the controller layer.


Life is not a bed of roses. You may find it challenging organizing your work in the beginning but practice makes a man perfect. It’s not challenging as it seems.

Find below the list of commands I am using mostly at work — My git cheatsheet.

- git check -b BRANCH-NAME
- git commit -m "TASK-ID your message here"
- git commit --amend
- git cherry-pick commit-id
- git rebase master 
// when I would like to edit or amend any specific commit then
- git rebase -i master

If you have any questions or scenarios you would like to discuss, please, ask them in the comment section. I would be happy to answer your questions.

Thanks for reading.


Originally posted on medium

 
Share this