Blog / Engineering
git workflow

How (and why!) to keep your Git commit history clean

Kushal Pandya ·
Jun 7, 2018 · 15 min read
Kushal Pandya GitLab profile

Git commits are one of the key parts of a Git repository, and more so, the commit message is a life log for the repository. As the project/repository evolves over time (new features getting added, bugs being fixed, architecture being refactored), commit messages are the place where one can see what was changed and how. So it's important that these messages reflect the underlying change in a short, precise manner.

Why a meaningful Git commit history is important

What does Git commit do? Git commit messages are the fingerprints that you leave on the code you touch. Any code that you commit today, a year from now when you look at the same change; you would be thankful for a clear, meaningful commit message that you wrote, and it will also make the lives of your fellow developers easier. When Git commits are isolated based on context, a bug which was introduced by a single commit becomes quicker to find, and the easier it is to revert the commit which caused the bug in the first place.

While working on a large project, we often deal with a lot of moving parts that are updated, added or removed. Ensuring that commit messages are maintained in such cases could be tricky, especially when development spans across days, weeks, or even months. So to simplify the effort of maintaining concise commit history, this article will use some of the common situations that a developer might face while working on a Git repository.

But before we dive in, let's quickly go through what a typical development workflow looks like in our hypothetical Ruby application.

Note: This article assumes that you are aware about basics of Git, how branches work, how to add uncommitted changes of a branch to stage and how to commit the changes. If you're unsure of these flows, our documentation is a great starting point.

A day in the life

Here, we are working on a small Ruby on Rails project where we need to add a navigation view on the homepage and that involves updating and adding several files. Following is a step by step breakdown of the entire flow:

Since all the files belong to different territories of the architecture, we commit the changes isolated of each other to ensure that each commit represents a certain context and is made in a certain order. I usually prefer backend -> frontend order where most backend-centric change is committed first, followed by the middle layer and then by frontend-centric changes in the Git list commits.

  1. application_controller.rb & application_controller_spec.rb; Add routes for navigation.
  2. _navigation.html.haml & navigation_spec.rb; Page Navigation View.
  3. index.html.haml; Render navigation partial.
  4. styles.css.scss; Add styles for navigation.

Now that we have our changes committed, we create a merge request with the branch. Once you have merge request open, it typically gets reviewed by your peer before the changes are merged into repo's master branch. Now let's learn what different situations we may end up with during code review.

Situation 1: How to change the most recent Git commit

Imagine a case where the reviewer looked at styles.css.scss and suggested a change. In such a case, it is very simple to do the change as the stylesheet changes are part of last commit on your branch. Here's how we can handle this;

Since you modified an existing Git commit, these changes are required to be force pushed to your remote repo using git push --force-with-lease <remote_name> <branch_name>. This command will override the commit Add styles for navigation on remote repo with updated commit that we just made in our local repo.

One thing to keep in mind while force pushing branches is that if you are working on the same branch with multiple people, force pushing may cause trouble for other users when they try to normally push their changes on a remote branch that has new commits force pushed. Hence, use this feature wisely. You can learn more about Git force push options here.

Situation 2: How to change a specific Git commit changes

In the previous situation, the Git commit change was rather simple as we had to modify only our last Git commit, but imagine if reviewer suggested to change something in _navigation.html.haml. In this case, it is second commit from the top, so changing it won't be as direct as it was in the first situation. Let's see how we can handle this:

Whenever a commit is made in a branch, it is identified by a unique SHA-1 hash string. Think of it as a unique ID that separates one commit from another. You can view all the previous commits, along with their SHA-1 hashes in a branch by running the git log command. With this, you would see an output that looks somewhat as follows and is a list of commits, where the most recent commits are at the top;

commit aa0a35a867ed2094da60042062e8f3d6000e3952 (HEAD -> add-page-navigation)
Author: Kushal Pandya <[email protected]>
Date: Wed May 2 15:24:02 2018 +0530

    Add styles for navigation

commit c22a3fa0c5cdc175f2b8232b9704079d27c619d0
Author: Kushal Pandya <[email protected]>
Date: Wed May 2 08:42:52 2018 +0000

    Render navigation partial

commit 4155df1cdc7be01c98b0773497ff65c22ba1549f
Author: Kushal Pandya <[email protected]>
Date: Wed May 2 08:42:51 2018 +0000

    Page Navigation View

commit 8d74af102941aa0b51e1a35b8ad731284e4b5a20
Author: Kushal Pandya <[email protected]>
Date: Wed May 2 08:12:20 2018 +0000

    Add routes for navigation

This is where git rebase command comes into play. Whenever we wish to edit a specific commit with git rebase, we need to first rebase our branch by moving back HEAD to the point right before the commit we wish to edit. In our case, we need to change the commit that reads Page Navigation View.

Commit Log

Here, notice the hash of commit which is right before the commit we want to modify; copy the hash and perform the following steps:

pick 4155df1cdc7 Page Navigation View
pick c22a3fa0c5c Render navigation partial
pick aa0a35a867e Add styles for navigation

# Rebase 8d74af10294..aa0a35a867e onto 8d74af10294 (3 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove Git commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out

Notice how each commit has a word pick in front of it, and in the contents below, there are all possible keywords we can use. Since we want to edit a commit, we need to change pick 4155df1cdc7 Page Navigation View to edit 4155df1cdc7 Page Navigation View. Save the changes and exit editor.

Now your branch is rebased to the point in time right before the commit you made which included _navigation.html.haml. Open the file and perform desired changes as per the review feedback. Once you're done with the changes, stage them by running git add _navigation.html.haml.

Since we have staged the changes, it is time to move branch HEAD back to the commit we originally had (while also including the new changes we added), run git rebase --continue, this will open your default editor in the terminal and show you the commit message that we edited during rebase; Page Navigation View. You can change this message if you wish, but we would leave it as it is for now, so save and exit the editor. At this point, Git will replay all the commits that followed after the commit you just edited and now branch HEAD is back to the top commit we originally had, and it also includes the new changes you made to one of the commits.

Since we again modified a commit that's already present in remote repo, we need force push this branch again using git push --force-with-lease <remote_name> <branch_name>.

Situation 3: How to add, remove, or combine Git commits

A common situation is when you've made several commits just to fix something previously committed. Now let's reduce them as much as we can, combining them with the original commits.

All you need to do is start the interactive rebase as you would in the other scenarios.

pick 4155df1cdc7 Page Navigation View
pick c22a3fa0c5c Render navigation partial
pick aa0a35a867e Add styles for navigation
pick 62e858a322 Fix a typo
pick 5c25eb48c8 Ops another fix
pick 7f0718efe9 Fix 2
pick f0ffc19ef7 Argh Another fix!

Now imagine you want to combine all those fixes into c22a3fa0c5c Render navigation partial. You just need to:

  1. Move the fixes up so that they are right below the commit you want to keep in the end.
  2. Change pick to squash or fixup for each of the fixes.

Note: squash keeps the git fix commit messages in the description. fixup will forget the commit messages of the fixes and keep the original.

You'll end up with something like this:

pick 4155df1cdc7 Page Navigation View
pick c22a3fa0c5c Render navigation partial
fixup 62e858a322 Fix a typo
fixup 5c25eb48c8 Ops another fix
fixup 7f0718efe9 Fix 2
fixup f0ffc19ef7 Argh Another fix!
pick aa0a35a867e Add styles for navigation

Save the changes, exit the editor, and you're done! This is the resulting history:

pick 4155df1cdc7 Page Navigation View
pick 96373c0bcf Render navigation partial
pick aa0a35a867e Add styles for navigation

As before, all you need to do now is git push --force-with-lease <remote_name> <branch_name> and the changes are up.

If you want to remove a Git commit from branch altogether, instead of squash or fixup, just write drop or simply delete that line.

How to avoid Git commit conflicts

To avoid conflicts, make sure the commits you're moving up the timeline aren't touching the same files touched by the commits left after them.

pick 4155df1cdc7 Page Navigation View
pick c22a3fa0c5c Render navigation partial
fixup 62e858a322 Fix a typo                 # this changes styles.css
fixup 5c25eb48c8 Ops another fix            # this changes image/logo.svg
fixup 7f0718efe9 Fix 2                      # this changes styles.css
fixup f0ffc19ef7 Argh Another fix!          # this changes styles.css
pick aa0a35a867e Add styles for navigation  # this changes index.html (no conflict)

Pro-tip: Quick Git commit fixups

If you know exactly which commit you want to fixup, when committing you don't have to waste brain cycles thinking of good temporary names for "Fix 1", "Fix 2", …, "Fix 42".

Step 1: Meet --fixup

After you've staged the changes fixing whatever it is that needs fixing, just Git commit all the changes like this:

git commit --fixup c22a3fa0c5c

(Note that this is the hash for the commit c22a3fa0c5c Render navigation partial)

This will generate this commit message: fixup! Render navigation partial.

Step 2: And the sidekick --autosquash

Easy interactive rebase. You can have git place the fixups automatically in the right place.

git rebase -i 4155df1cdc7 --autosquash

History will be shown like so:

pick 4155df1cdc7 Page Navigation View
pick c22a3fa0c5c Render navigation partial
fixup 62e858a322 Fix a typo
fixup 5c25eb48c8 Ops another fix
fixup 7f0718efe9 Fix 2
fixup f0ffc19ef7 Argh Another fix!
pick aa0a35a867e Add styles for navigation

Ready for you to just review and proceed.

If you're feeling adventurous you can do a non-interactive rebase git rebase --autosquash, but only if you like living dangerously, as you'll have no opportunity to review the squashes being made before they're applied.

Situation 4: My Git commit history doesn't make sense, I need a fresh start!

If we're working on a large feature, it is common to have several fixup and review-feedback changes that are being committed frequently. Instead of constantly rebasing the branch, we can leave the cleaning up of Git commits until the end of development.

This is where creating patch files is extremely handy. In fact, patch files were the primary way of sharing code over email while collaborating on large open source projects before Git-based services like GitLab were available to developers. Imagine you have one such branch (eg; add-page-navigation) where there are tons of commits that don't convey the underlying changes clearly. Here's how you can create a patch file for all the changes you made in this branch:

As with previous situations, we basically modified the whole branch, so it is time to force push!

Git commit history: Conclusion

While we have covered most common and basic situations that arise in a day-to-day workflow with Git, rewriting Git history is a vast topic and as you get familiar with above tips, you can learn more advanced concepts around the subject in the Git Official Documentation. Happy git'ing!

Photo by pan xiaozhen on Unsplash

Edit this page View source