Git-flow is a branching model for Git designed by Vincent Driessen to provide a wrapper around git commands that basically allows you to create branches.

If you’re thinking about using this workflow, ask yourself the following question:

Which one of these photos represents you?

If you chose the first photo, you’re a one man army, so you probably don’t need parallel development (that is one of the advantages of git-flow) but, however, you may have release cycles and git-flow makes these very easy. If you don’t deal with these then it maybe that this is not the best option for you.

However, if you chose the second photo, you can be sure that git-flow will help you a lot. You need parallel development because you have a team that works every day on new features, fixing bugs…and when you have to release new versions, git-flow will make your life easier, believe me!

How does it work?

First you need to install git-flow, and then you can start to use it by running a simple command:

git flow init

After you’ve run the command you’ll need to answer a few questions, all of them have a default answer, related to branch prefixes:

$ git flow init

Initialized empty Git repository in ~/test/.git/

No branches exist yet. Base branches must be created now.

Branch name for production releases: [master]

Branch name for “next release” development: [develop]

How to name your supporting branch prefixes?

Feature branches? [feature/]

Release branches? [release/]

Hotfix branches? [hotfix/]

Support branches? [support/]

Version tag prefix? []

And now you’ll see that you have two branches in your project:

$ git branch

* develop

master

The develop branch will contain the features that will be released in the next cycle and the master branch reflects a production-ready state.

Usual development

Feature branches

The feature branches are used to develop new features. If you have a team working on this project, usually each one of the team will work on their own feature (or at least will work on its individual development). So, for example, John starts to work on feature1 and a few days after Mary will begin on feature2. To do this, each person will create their own feature branch, the feature branches always start from the develop stage and have to be merged in develop.

In order to create new feature branches, we need to use the git-flow command:

git flow feature start FEATURE_NAME

This command will create a new feature branch adding a prefix (feature/) which was defined when git-flow was initialized.

$ git branch

develop

master

* feature/feature1

Then, after multiple pull request revisions and multiple tasks have been resolved, because the team lead is an incredible professional ;), these two features are ready to be merged in the develop branch. However, just for fun, let’s add another layer, so that between merging these features Martha joins the team and creates a little feature (feature3), which she finishes very quickly.

In order to finish the feature branches, we need to use the git-flow command:

git flow feature finish FEATURE_NAME

After running this command, the feature branch should be merged into the develop branch. At this point, we could have some problems with merging the feature branch into the develop branch, and we should resolve them as we do with others conflicts in git.

Release branches

We are now ready to release a new version with some new features, so it’s time to create a release branch. The release branches always start from develop and have to be merged in develop and in master.

In order to create the release branch, we should use the git-flow command:

git flow release start VERSION

Now we have created the release branch, we have a version that is regarded as the branch name (in this case we will put the 1.0.0 version).

$ git branch

develop

master

* release/1.0.0

We have to test this release in the staging environment to check that all is fine, so the best option will be to tag this branch as a release candidate. In our case the new version will be 1.0.0.RC1.

Based on Vicent’s workflow, only bug fixes are allowed in the release branch (we will talk about this type of branch later), so if John starts on a new feature4 he needs to create a feature branch from the develop branch and this feature branch has to be merged into the develop branch so that it will be available on the next release.

The release date has arrived! We’ve been testing the release candidate during the past week in staging and everything is fine, so it’s time to tag the release version (1.0.0) and close the release branch.

In order to finish the release branch, we need to use the git-flow command:

git flow release finish VERSION

After running this command, the release branch will be merged into the develop and master branches. At this point we’re in the same situation that we had when we merged the feature branches, and we could have some problems merging the release branch into the develop/master branch so we must ensure that we resolve any issues as we do with others conflicts in git.

The “Oh shit” moment

Bugfix branches

When we’re testing the release branch in staging, we could find an error that has to be solved before the release date. According to the workflow, we need to solve this by creating a bugfix branch that starts from the release branch and has to be merged in the same branch. For example, if Martha solves a little error, the flow should be like this:

Hotfix branches

The best “oh shit” moment is an error in a live environment… now it’s time to work under the hood!

Mary is looking to solve an error in live, she needs to create a hotfix branch from the master and it has to be merged in the master and in the develop branches.

In order to start the hotfix branch, she needs to use the git-flow command:

git flow hotfix start HOTFIX_NAME

After running this command your branches should be something like:

$ git branch

develop

master

* hotfix/HOTFIX_NAME

And when the error is fixed and the hotfix branch has to be merged Mary will finish the hotfix branch

git flow hotfix finish HOTFIX_NAME

This command will then merge this branch into the develop and master branches, and volia!