Git Flow

Workflows

Git flow provides 3 workflows to make the following operations easier and smoother:

• Feature: Add a new feature or fix a non urgent bug
• Release: Release a new version
• Hotfix: Fix an urgent bug because something went wrong in production

What is git flow?

It is superset of git sub-commands starting with git flow that help automate the above recurrent workflows. With git flow, you type less recurring and error prone boilerplate git commands in order to focus more on what you really need/love to do.

Setup

Install

Windows and Linux

https://danielkummer.github.io/git-flow-cheatsheet/#setup

MacOS

brew install git-flow-avh

I prefer installing and using git-flow-avh instead of git-flow because it offers more features, like for instance the --showcommands option useful to see the underlying git commands git-flow is running.

Configure

https://danielkummer.github.io/git-flow-cheatsheet/#getting_started

# First off, make sure you have both the develop and master branches available locally
git checkout develop
git checkout master

git flow init

Using the default values (in between square brackets in the screenshot below) is the recommended way to go except you if you have an existing project with a naming convention for branch(es) that differs from default git flow convention.

FYI, this adds at least the following to the git config file (.git/config).

[gitflow "branch"]
        master = master
        develop = develop
[gitflow "prefix"]
        feature = feature/
        bugfix = bugfix/
        release = release/
        hotfix = hotfix/
        support = support/
        versiontag =

Feature

This is how we add a new feature or fix a non urgent bug to the code base. For an urgent bug fix, the one that requires an immediate intervention in production, cf. Hotfix.

Here is a diagram that gives a visual representation of the flow

[TODO]

Release

Here is a diagram that gives a visual representation of the flow

[TODO]

Hotfix

We use this process when something went wrong in production and needs to be fixed immediately.

Here is a diagram that gives a visual representation of the flow

Start a Hotfix

A hotfix branch starts off master and ends up being merged into master when you finish it. You don't have to checkout master beforehand because git flow does this for you (see below).

git hotfix start A.B.C-n
# You are now on the branch hotfix/A.B.C-n  ready to commit fixes

Example

Here is how to start the first hotfix for the release 1.9.4:

git flow hotfix start 1.9.4-1
# You are now on the branch hotfix/1.9.4-1  ready to commit fixes

Equivalent Git Commands

Here is the command git flow runs under the hood to start the hotfix, so you don't have to:

git checkout -b hotfix/1.9.4-1 master

Publish a hotfix branch

Your mileage may vary here, because this command does not exist in all git flow implementations, maybe because pushing a hotfix branch to the remote is not considered a use-case common enough. It however may prove to be useful when a hotfix requires several developper to commit code to a hotfix branch.

git flow hotfix publish A.B.C

Example

The first hotfix for the release 1.9.4 is named 1.9.4-1 and the corresponding git branch is hotfix/1.9.4-1. Here is how to push this hotfix branch to the remote origin.

git flow hotfix publish 1.9.4-1

If your git flow implementation does not provide the publish sub-command, then use the below git command as a workaround.

Equivalent Git Commands

Here are the git commands git flow runs under the hood to publish the hotfix, so you don't have to:

git push origin hotfix/1.9.4-1

Finish a Hotfix

Here are the git command that git flow runs when asked to finish a hotfix:

• Merge the hotfix branch hotfix/A.B.C-n into master
• Then, add the tag A.B.C-n on master with the annotation vA.B.C-n
• Merge the hotfix branch into develop
• Remove the hotfix branch locally

git hotfix finish A.B.C-n

Example

Here is how to finish the hotfix branch hotfix/1.9.4-1

git hotfix finish A.B.C-n

Equivalent Git Commands

Here are the git commands, git flow runs under the hood to finish the hotfix, so you don't have to:

git checkout master  
git merge --no-ff hotfix/1.9.4-1
  
git tag -a 1.9.4-1 -m "v1.9.4-1"
  
git checkout develop  
git merge --no-ff hotfix/1.9.4-1
 
git branch -d hotfix/1.9.4-1

Tags

Release candidate tags A.B.C-RCn are added on the release branch.
For instance the RC tag 1.9.4-RC1 is added on the release branch release/1.9.4.

Hotfix tags are added on the master branch
eg. 1.9.4-1 (First hotfix for release v1.9.4)
Git flow adds the tag for you when you finish the hotfix, so you don't have to!

Release tags are added on the master branch
eg. 1.9.4 (release v1.9.4)
Git flow adds the tag for you when you finish a release, so you don't have to!

The table below summarises this.

Type of Tag	Added on branch	Naming Convention	Name Example
Release Candidate	Release Branch (release/1.9.4)	A.B.C-RCn	1.9.4-RC1
Release	master	A.B.C	1.9.4
Hotfix	master	A.B.C-n	1.9.4-1