When committing changes to your Git repository, you’ll sometimes make mistakes. If on a feature branch, you can use Git Rebase to erase mistakes for a clean Git history and improved Code Reviews. Otherwise, if the mistake is made on your default branch or, worse, deployed into production you’ll need to use git revert because you need to document the change being made and explain why you had to unwind a previous change.

The problem everyone makes is using git revert <sha> instead of git revert --no-commit <sha>. The former results in an ugly and hard to read commit with no further modification to the commit message while the latter allows you to explain your reasoning.

To illustrate, we can use a demo project and learn why using git revert --no-commit is important:

Assuming the above bad commit passed code review, was deployed, and now needs to be reverted, you’d need to revert this commit by doing the following:

You’ll then see the following message pop up in your editor:

…​which most people save, exit, and move on. That’s not what we want because we need to explain ourselves not only for our own recollection but also for our team and eventual Milestones. To fix, let’s first delete the previously reverted commit:

Now, with a clean slate, we can make a couple of corrections. The first is to modify your Git global configuration so you have this configuration:

💡 You can also use git config set --global revert.reference true if you don’t want to edit your configuration directly.

The above ensures Git provides a full reference to the commit you are reverting (i.e. SHA, subject, and date) by saving you time by not having to hunt down the original commit details.

Next, you need to use git revert --no-commit which allows you to provide your own commit message. If we put all this together, we can do the following:

The above reverts the bad commit without making a commit message. The best part is Git has saved the relevant details you need to make a proper commit message. Here’s what you’ll see in your editor when using git commit:

Notice Git provided the commit SHA, subject, and date thanks to our revert.reference = true configuration. 🎉 Now we can use this information to finesse and save the following commit message:

The above takes what Git initially provided us so we could craft a detailed commit message as explained when adhering to good Git Commit Anatomy. Now, if we look at our Git commits, we have history that reads well:

Now you know how to use git revert professionally. Enjoy!