Skip to content

Git Flow

Jump to bottom
Eric Bouchut edited this page Apr 9, 2018 · 145 revisions

Table Of Content

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.

Workflows

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

Branches

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 ready to be released when we decide to do so.
    This long lived branch is where branches for feature/release starts off.
    This is not where developers commit code for a new feature nor a bug fix!
  • 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.
    This feature branch then reaches the end of its life and should 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

Git Flow does not enforce a naming convention for tags, release and hotfix branches. The names I gave above are only for example purposes. It is up to you to use the one that floats your boat. However git flow can be configured to fit your needs. More about this here.

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

Git flow needs to be configured locally per git repository.
There is no global configuration which means you need to locally configure each git repository where you want to use git flow.
The configuration settings are stored in your local git config file (.git/config).

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

If the above fails telling you that another hotfix already exists, because you cannot work on 2 hotfixes at the same time. You probably have one old local lingering hotfix branch. You can find out which one with git branch | grep '^hotfix/'. Make sure it has been finished (ie. merged into master and develop) and if so remove it.

git fetch
git branch -r --contains hotfix/A.B.C-n

# If you see `origin/master` and `origin/develop`,
# then you can remove it like so
git branch -d hotfix/A.B.C-n

If the hotfix has not been merged, tell your other self to finish it first or else take the other pill (the blue one) and everything will be fine.

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

When a fixing an urgent bug requires several developper to commit code, you need to push the hotfix branch 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-n

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

Get a Published hotfix

There is no dedicated git flow command to retrieve a previously published hotfix branch. The workaround is to fall-back to using regular git commands:

git checkout hotfix/A.B.C-n

Example

git checkout hotfix/1.9.4-1

Finish a Hotfix

You have just finished squashing this bug, which is great. Now let's make the fix available in both master and develop branches.

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

Clone this wiki locally