Hotfix branch and Gitflow tutorial

Hopefully, you don’t need to start a Gitflow hotfix too often. In fact, life is best if you never have to start the Gitflow hotfix process at all.

A Gitflow hotfix branch is only required when a critical bug or security flaw is found in live, publicly facing and globally accessible applications or binaries. The flaw is in a tagged commit on the Git master/main branch, and it has to be addressed immediately. The Gitflow hotfix branch creation process is the recommended workflow to address stop-the-world bugs in the master branch.

Properties of the Gitflow hotfix

Here’s the skinny on the Gitflow hotfix branch process:

  • A hotfix branch is created directly off the latest commit on master/main.
  • The only commits allowed on the hotfix branch are ones that explicitly address the software bug.
  • No feature enhancements or chores are allowed on the Gitflow hotfix branch.
  • The hotfix branch merges into both master and develop branches when its lifecycle ends.
  • The hotfix branch is deleted after it is merged or rebased into master and develop branches.
gitflow hotfix example

In this Gitflow hotfix branch example, we see the branch merge to master and develop before it is deleted.

Simple Gitflow hotfix example

The following Gitflow hotfix example demonstrates how to use the hotfix process in a software development project.

First, initialize a Gitflow-based repository.

<span style="color: #993300"><span style="color: #ff6600">GitFlow@Example</span> <span style="color: #ff00ff">MINGW64</span> <span style="color: #993366">/c/git-flow-tutorial </span>



<span style="color: #003366"><span style="color: #008000">$</span> git flow init</span></span>

Note that there are only two branches in existence after the “git flow init” call and no tags in the recently created repository.

<span style="color: #993300"><span style="color: #003366"><span style="color: #339966">$</span> git branch -a</span>



<span style="color: #808080"><span style="color: #ff0000">*</span> develop



master</span>







<span style="color: #003366"><span style="color: #339966">$</span> git tag -l</span></span>

Gitflow hotfix start

Now, we create the hotfix branch, add a file to the repository, and then make a Git commit.

<span style="color: #993300"><span style="color: #003366"><span style="color: #339966">$</span> git flow hotfix start '0.1.1'</span>



<span style="color: #808080">Switched to a new branch 'hotfix/0.1.1'</span>







<span style="color: #003366"><span style="color: #339966">$</span> touch hotfix.html</span>







<span style="color: #003366"><span style="color: #339966">$</span> git add .</span>







<span style="color: #003366"><span style="color: #339966">$</span> git commit -m "A git flow hotfix from start to finish."</span>



<span style="color: #808080">[hotfix/0.1.1 053131c] A git flow hotfix from start to finish.



1 file changed, 0 insertions(+), 0 deletions(-)</span>







<span style="color: #003366"><span style="color: #339966">$</span> git branch -a</span>



<span style="color: #808080">develop



<span style="color: #ff0000">*</span> hotfix/0.1.1



master</span>







<span style="color: #003366"><span style="color: #339966">$</span> git tag -l



</span></span>

Gitflow hotfix finish

When the “Gitflow hotfix finish” command is called, the commit is merged into both master and develop branches and then deleted.

$ git flow hotfix finish '0.1.1'



Switched to branch 'master'



Merge made by the 'recursive' strategy.



Switched to branch 'develop'



Merge made by the 'recursive' strategy.



Deleted branch hotfix/0.1.1







GitFlow@Example MINGW64 /c/git-flow-tutorial  (develop)



$ ls



hotfix.html







$ git checkout master



Switched to branch 'master'







GitFlow@Example MINGW64 /c/git-flow-tutorial  (master)



$ ls



hotfix.html

The hotfix branch no longer exists, and the only reminder it was ever here is the tag left on the master branch.

<span style="color: #993300"><span style="color: #003366"><span style="color: #339966">$</span> git branch -a</span>



<span style="color: #808080">develop



<span style="color: #ff0000">*</span> master</span>







<span style="color: #003366"><span style="color: #339966">$</span> git tag -l</span>



<span style="color: #808080">0.1.1</span></span>

Nobody likes to deal with production problems or bugs on their main branch. But when these issues do occur, the Gitflow hotfix branch is there to guide your development efforts and ensure urgent code changes get merged into both master and development branches.

Gitflow Hotfix Branch Diagram

The Gitflow hotfix branch is one part of the larger Gitflow workflow.