Git Flow

Table Of Content

• Workflows
• What is git flow?
• Setup
  • Install
    • Windows and Linux
    • MacOS
  • Configure
• Feature
• Release
• Hotfix
  • Start a Hotfix
    • Example
    • Equivalent Git Commands
  • Publish a hotfix branch
    • Example
    • Equivalent Git Commands
  • Finish a Hotfix
    • Example
    • Equivalent Git Commands
• Tags

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.

Git flow workflows are based on a set of branches:

• master: The production ready branch is master.
  This long lived branch is only updated when either or a new release or an urgent bug fix is made available.
  This is not where developers commit code for a new feature nor a bug fix!
• develop It contains the code under development but not production ready yet.
  This is not where developers commit code for a new feature nor a bug fix! This long lived branch is where branches for feature/release starts off.
• Feature Branch: feature/XXX
  A short lived feature branch (feature/XXX) is forked-off develop each time you start working on a new feature where XXX can be the name of a ticket (twitter-123), or even better the name of the ticket followed by a super short description of what the feature is about (twitter-123_add_timeline).
  It is intended to contain only the code for this specific feature.
  Once the feature is complete, it is merged into develop to make it available in our shared code base and ready to be released when we decide to do so.
  This feature branch then reaches the end of its life and can be removed locally and on the remote.
  No more code must be committed to a feature branch that has been merged or else it will be lost forever.
• Release Branch: release/A.B.C
  A branch forked-off develop to to release the code available in develop at that time. Bugs found when testing the release are fixed on the release branch. When the release is considered complete, it is merged into master and develop. A release tag is added on master.
  The release branch can then be removed because it has reached its end of life.
  Here again, no more code must be committed to a release branch that has been merged or else it will be lost forever.
• Hotfix Branch: hotfix/A.B.C-n
  TODO
• Support Branch
  TODO

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, like a bug in production that requires an immediate fix, use the Hotfix workflow instead.

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.
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

When a fixing an urgent bug requires several developper to commit code, you need to publish the hotfix branch (ie. push it to the remote repository).
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.

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 corresponding 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

You have just finished squashing this bug and are now ready to make the fix available in the branches master and develop.
Ok, let's do it.

git hotfix finish A.B.C-n

Git flow runs the following git command under the hood 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

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