When Gitflow Fails: Using `git checkout -p` to Untangle Your Commits

Intro to Gitflow

In the ideal world you won’t be delving into the depths of git patching when versioning your code project. I highly recommend the Gitflow approach that you can read about more here - some argue that it has an unnecessarily high overhead compared to trunk-based approaches or GitHub flow in an era of continuous deployment rather than versioned releases and rollbacks. Yet, I have found the structure reasonably simple to follow and having clear versions to rollback to quite useful along with clear alignment of branches to environments.

I have included a quick summary diagram below but Gitflow involves managing merges to main to reduce breaking changes through releases (which can be used to test code in a UAT environment). Moreover it prioritizes running a ‘parallel’ branch for code to run in the development environment (here called the develop branch).

What is important here is keeping these branches in sync. You want to avoid a situation where main is ahead of one of the other branches and has commits that the lower branches do not have. This is why merging back into lower branches is so important; for example, after a hotfix or release, note the merge into both main and back into develop.

When the flow gets messy

I was once working on a repository where things had fallen out of sync. I had also committed some code on a feature branch and then decided that actually it merited its own feature branch.

A git merge did not make sense here as I did not want to bring across all the changes into the fresh branch and a git cherry-pick was not an option as the changes I wanted to bring across were across commits and the commits themselves had changes to multiple files. Further muddying the water, one feature was originally branched off main while the other was originally branched off develop - as they were out of sync the scale of differences was also rather large.

In the past I've seen developers manually copy-pasted code across branches but I do not like this approach as there is scope for manual error when copy and pasting and it seems a waste not to leverage git functionality.

Interactive Patching

git checkout -p is the approach I opted for to interactively add changes from particular files to the correct branch. Git runs through the differences chunk by chunk and you can interactively carry changes over, reject changes while there are also options to make decisions on the file level rather than particular differences.

The steps in git commands are to create the clean-feature branch if not yet created otherwise simply check out the clean-feature:

git checkout -b clean-feature for creating a new branch or git checkout clean-feature for switching to a pre-created branch.

Then running the interactive patch command: git checkout -p messy-feature.

From within the command line you can go chunk by chunk using y or n in the command line to either bring differences over or stick with the existing version of the code. However there are some other useful time saving interactive keys:

• d skips an entire file of differences, effectively keeping a file as is in the currently checked out branch.

• a takes all the differences in a file in one button, effectively bringing over the whole file from the messy feature into the clean-feature.

• q allows you to quit the interactive portion early so once you have all the files or differences you want you don’t have to click through to completion.

Once you’ve made these changes remember to stage and commit the changes to the new branch!

This isn’t a gamebreaking git command, in an ideal world it wouldn’t be required, your repository will be nicely in sync, you won’t commit code for different features into the same branch in the same commits. Nevertheless, it's a useful command to have in the back pocket in case a situation requires it.