How to Amend Git Commits

I've talked about Git a couple of times before. It's fair to say that version control is a fundamental tool in any developer's arsenal, and knowing a little more about how it works, and how to use it really should be very high on any young developer's list of things to learn.

One thing situation that every developer will find themselves in time and again is needing to amend a commit that has already gone in. We've all been there. It's hardly the end of the world to simply push a second commit in, but I personally like a tidy Git history and it seems like a bit of a commit to just do one for a tiny missed change all on its own.

Luckily, you can amend local git commits using git commit ‑‑amend.

Forgotten a File or Need to Edit One?

If you need to amend the contents of your previous commit, for example, you need to further edit a file, or you've missed one out altogether, then this is a quick and easy one.

In your branch, carry out the additional work that you need to do (or add the additional files you missed out), and then use git add to add the additional work to the Git index. If you're adding everything that you've changed, you can append the command with a ., this will add everything: git add .

With the updates added to the index, you can simply run:

git commit --amend --no-edit

This takes the previous commit in the branch and amends it with the latest files you've added to the index. The additional ‑‑no‑edit flag just means that you don't need to edit your commit message at all, and Git just needs to include the new files, within the previous commit.

Now you can push this commit, and it will have all the files you needed!

Need to Update Your Commit Message?

The other common scenario for needing to amend a Git commit is when you've made a mistake in the commit message itself. It happens to the best of us. A typo slips through the cracks, or you include some details that aren't relevant (or miss out on some that were). Again, git amend is the answer, this time using the ‑m flag.

After you've made your commit with the message that you need to update, just run:

git commit --amend -m

Git will then ask for a new commit message and all you need to do is type the corrected message in, and then push as normal.

Using Reset to Step Back through Git History

Another alternative for rewriting your local Git history is using reset instead of amend. Whereas amend can be used to modify the most recent commit in your local branch, reset can be used to simply undo the commit altogether.

reset is a complex and versatile tool, which I will only scratch the surface of today. Here, we are interested in the ‑‑soft flag, which will undo the previous (or several previous ‑ as you will see) commits, and place them back into the staging index:

git reset --soft HEAD~1

What this command does is reset the head of your local branch back by one previous commit, placing those changed files back into the staging index, in their pre‑committed form. You get the files and the changes you made, but it removes the commit itself.

From here, you can make the change you need, and simply commit again. This is the technique I use most often, often keeping the original commit message in my clipboard or on a note on my desktop until I'm ready to commit it again.

The ~1 at the end of that command is important: if you found you wanted to undo further back down the repository history, you could change this number. git reset ‑‑soft HEAD~5 for example would undo the most recent five commits, placing all those changes back in your index. This is especially useful if you want to combine commits together before pushing up to the remote.

One word of warning: I mentioned above, this is the command I most usually use. I tend to access it using Terminal's history via the command + r key combination. If you have most recently been undoing multiple commits, be very careful which command comes up in your history before you press enter, otherwise, you may inadvertently end up undoing far more than you intended!

A Note About Amending Remote Commits

You may have noticed that my examples here today all focus on editing commits locally, which have not yet made their way into the remote repository. A word of advice though: if you have already pushed your commit up, I would generally, and absolutely not recommend attempting to amend a remote commit.

If you're working on your own branch, or you can be absolutely confident that there is nobody else working on the same codebase at the time, then you could use any of the options we've discussed today to amend your local commit and then use push ‑‑force to overwrite the previous remote commit. However, this will also overwrite anything else that has occurred within the remote branch since your commit. ‑‑force is an incredibly useful tool, but also a very dangerous one ‑ there's no undo afterwards!

For me, and in most of the teams I work within, it is simply not a risk worth taking. In a previous project I was involved in, one of my developers used ‑‑force, thinking they were in their branch, inadvertently overwriting the entire remote master branch. Fortunately, I had a recent local copy, but even then it was still several merge requests behind so we spent an afternoon reinstating master. Not an experience I would wish on another developer, and not a task I enjoyed undertaking!

So, my advice: if you find you need to amend a remote commit, then just create a new one and push it up. I would far rather have multiple commits in the Git log than lose my team's work ‑ or lose an afternoon of my team's productivity whilst we piece the remote back together again.