My Five-Step Process to Master Your Git Branch Workflow

Merge vs. Rebase, maybe Cherry-Pick, what about Squash?

Photo by Yancy Min on Unsplash

“It is easy to shoot your foot off with git, but also easy to revert to a previous foot and merge it with your current leg.”

— Jack William Bell

By far, Git is the most popular modern version control system(VCS) worldwide. Not to mention, Git has features that really make it stand apart from nearly every other VCS; Merging and Branching is one of them.

Whether your company/team has chosen to work with the Centralized Workflow, or the Feature Branch Workflow, or perhaps the Gitflow Workflow — Before you can master any workflow, first, you will need to craft the art of Merging and Branching.

Before getting to the process itself, let’s first take a few seconds to explain the problem.

Git is a distributed system; in other words, it allows users not only to check out a repository but instead, clone it entirely to their local machines.

Once a git repository is cloned, users can add, remove, or modify the code locally. Users can also commit or revert to/from the local repository. All by using git’s basic commands. Pretty good! As easy as winking. But there’s a catch.

When users decide to merge their local repository back to the master branch, problems might arise. Let me explain.

Assuming that a user has branched from the master at some point, e.g. (E).

      A---B---C user
     /
D---E---F---G master

As you can see, the user branch has produced 3 additional commits (A, B, and C). In addition, the master branch has two new commits (F and G) committed by other developers after the branching.

At this point, a question will arise — How would you like the tree of commit history of the master branch to look like?

Option1-Detailed and None-Linear History:

      A---B---C
     /         \
D---E---F---G---H master

As you can see in this option, you have a detailed view of what has been done, H is the merge commit, and as you can see, the history is not linear.

Option2-Straightforward and Linear History:

D---E---F---G---A---B---C master

In this option, you can see that the user branch has been merged on top of the recent changes in the master branch, it is called a fast-forward merge, and the history is linear.

Another question that should be addressed team-wise or even company-wise to agree on some convention.

Here’s a process that you will make the right decisions in most cases if you follow.

1. Is there a request to maintain a linear history?

In case it’s a “no!”.

Then it's pretty simple; All you need is to create a Merge/Pull request(Step 5), and your code will be merged into the master branch.

The master branch history will look like this.

      A---B---C
     /         \
D---E---F---G---H master

Where H is the merge commit, and you can see the branching in the master branch history.

But in case you should keep a linear history, then there are two ways to do it.

Rebase and Cherry-Pick.

2. First try to Rebase

Rebase is a function that you can perform on your local branch(e.g., user) to apply your local changes as a batch, on top of the recent changes in the master branch, allowing you to merge your changes as a fast-forward merge.

Before rebasing:

      A---B---C user
     /
D---E---F---G master

After rebasing:

              A---B---C user
             /
D---E---F---G master

As you can see, after rebasing the user branch onto master, now commits A, B, and C can be merged as a fast-forward merge.

But beware.

Occasionally, Rebase can produce conflicts and unnecessary need to use force push to the remote user branch, which I am not a big fan of.

Picture it this way.

Basically, Rebase is rewriting the history of the user branch behind the scenes, which will result in the new commits A’, B’, and C’ applied on top of the recent changes from the master branch.

As you can see, now the user and remote user branches are no longer the same.

      A---B---C origin/user
     /
D---E---F---G---A'---B'---C' user

There is a workaround that I often use when I face such a problem, you can create a new branch locally from the user branch, let's call it user-workaround, Rebase it onto the master branch. This way no conflicts will occur with the remote user-workaround, since simply it does not exists.

Once Rebase has passed successfully you can push the new branch user-workaround to the remote server, altogether with the new commits A, B, and C on top of the master branch recent changes.

Commands that will help:

>git checkout user
>git rebase master
or
>git checkout user
>git pull
>git branch user-workaround
>git checkout user-workaround
>git rebase master
>git push -u origin user-workaround

If Rebase has passed successfully, you can jump to Step 4.

Otherwise, or in case Rebase is not allowed in the first place due to DevOps restrictions, you might want to try Cherry-Pick.

3. Try to Cherry-Pick.

Cherry-Pick is the process where code can be merged into the current branch by choosing specific commits(Cherry-Picking) from another branch.

      A---B---C user
     /
D---E---F---G master

In this case, you can check out the master branch, pull the recent changes, and then create a new branch on top of it, let’s say user-cherry-pick.

      A---B---C user
     /
D---E---F---G master
D---E---F---G user-cherry-pick

While on user-cherry-pick, you can view the history of the user branch and cherry-pick the commits A, B, and C., Which will result in the following

      A---B---C user
     /
D---E---F---G master
D---E---F---G---A---B---C user-cherry-pick

Commands that will help:

>git checkout master
>git pull
>git branch user-cherry-pick
>git checkout user-cherry-pick
>git cherry-pick A

Almost done, Let's jump to the next step.

4. Do you want to Squash?

Squash is a function in Git that allows the user to squash a few commits into one single commit, which is useful sometimes.

If it’s a “no!”, then that’s all, and you are good to go to Step 5.

Ok, it’s a “yes!”; Lest’s assume that the commits A, B, and C has no special meaning, and all 3 of them can be squashed into a single commit H

Before squashing:

      A---B---C user
     /
D---E---F---G master

After squashing:

      H user
     /
D---E---F---G master

Whilst creating a Merge/Pull request(Step 5), you have an option to squash before merging.

Commands that will help:

>git checkout master
>git merge --squash user

That’s it; you are ready for the last step.

5. Merge/Pull request.

So you have made a few decisions, and now you have a user/user-cherry-pick(In case you have used Cherry-Pick) branch that is ready to be merged to the master branch.

In case you aren’t using GitHub enterprise, then you can simply merge the user/user-cherry-pick branch to the master branch. And that’s it; you are done!

Commands that will help:

>git checkout master
>git merge user

If you are using GitHub enterprise, then make sure the branch you want to merge(user/user-cherry-pick) is a remote branch, since otherwise, you cannot create a Pull Request.

A Pull Request is a Github enterprise feature that allows the user to tell other developers that he intends to push changes and also collaborate with reviewers to discuss and review the potential changes.

“You can do a lot of things with git, and many of the rules of what you *should* do are not so much technical limitations but are about what works well when working together with other people. So git is a very powerful set of tools.”

— Linus Torvalds