A Git-Flow Explainer & How To Tutorial

What is Git-Flow?

When someone talks about Git-Flow, it could mean two things:

  • A successful branching model (theory)
  • A set of terminal commands that extend the regular git command set (practice)

In this post, I will cover both in order to get you ready to start using it today.

As a developer, Git is probably part of your daily work. You develop new features, you merge them later, then you release them, and finally, you fix potential bugs.

If there is no clear way of doing all these things -especially as a team- you get in trouble really fast. That’s why Git-Flow is here: It provides you with a clear work-“flow” (ha, I said it) to handle day-to-day Git business.

The Theory 😒

There is a lot explained in Vincent Driessen’s original introduction of Git-Flow, but I’ll try to keep it short.

Main Branches

There are two main branches: master and develop. They are the king and queen of Git-Flow Land. Which explains why there is only one of each.

master is for production. Here sits the code that’s live, nice and cozy. Not much happens here unless someone releases code to production.

develop is for code that’s currently in development. Features and bug fixes are merged here, so it’s a little bit busier.

Supporting Branches

There are three supporting branches: features, releases, hotfixes. Each of these branches has clear rules from where they originate and where they merge to. There can be multiple branches for any of these. (e.g. one for every feature that’s being developed, one per hotfix, etc.)

Feature branches

If you want to program a new feature or do some refactoring, this is what you want. You create a new feature branch and do your thing while leaving develop untouched. At some point, the feature finishes and the produced changes merge back into develop. This is the kind of branch that’s probably being used the most, here is where all the action happens. All code that is still under development is somewhere in a feature branch.

This is also the perfect place if you want to make an experiment. If it doesn’t work, just delete the branch and nothing happens. Nobody needs to know.

When a feature branch gets created, it originates from the develop branch and merges back into develop.

The name of the branch will be features/name_of_your_feature.

Release branches

You decide that you have enough well-tested fancy features to bring them to production. Then you make a release branch. No development should be done here, just minor last-minute bug fixes, version bumps, etc.

When a release branch gets created, it originates from the develop branch and merges back into master and develop.

The reason for this branch is, that you can read the code for production while the develop branch can already receive new features for the next release.

When a release branch gets created, it gets assigned a version number. NOT EARLIER. Everything up to that point that’s sitting in develop branch is for “the next release”.

The name of the branch will be releases/name_of_your_release.

Hotfix branches

Ay yes. You pushed your glorious code into production, but just then notice a bug that needs fixing in production. There is no reason for panic, this happens to everyone. And, there is a Git-Flow solution for it: The hotfix branch. It grabs the code from production (master), the bug gets fixed and the changes merge back in master and develop.

When a hotfix branch gets created, it originates from the master branch and merges back into master and develop.

The beautiful this here is, that potentially unstable code in develop is not going to affect our hotfix, plus other developers can continue coding while the hero may fix the production bug.

Also, hotfix branches get a version number when it’s created, (e.g. 1.2.1 if your release was 1.2). Don’t forget to bump the version in your code when doing this.

The Practice 🤩

Yes, I am well aware that theory is boring but necessary. So, good we arrived at the fun part of this article.

Having read all of the above theory probably sounds like “a lot of work”, or “so many git commands, just to fix a bug”. Well, you’re in luck. There is a command tool, which extends the abilities of git to those of Git-Flow.



$ brew install git-flow


$ apt-get install git-flow

Windows (Cygwin):

$ wget -q -O - --no-check-certificate https://raw.github.com/petervanderdoes/gitflow-avh/develop/contrib/gitflow-installer.sh install stable | bash


$ git flow init

This command initializes your repository as a “git flow” repository. You have to choose names for your branches, but I strictly advise you to leave it at the defaults (as described above). It also checks out the develop branch, which is from where you should go.

Now you’re ready to go!


You’ll see, it’s pretty straightforward. The best is just to play around a little bit with it on a test repository.

Create a feature

$ git flow feature start feature_name

Remember: Branches off develop

Finish a feature branch

$ git flow feature finish feature_name

Remember: Merges back into develop

Create a release

$ git flow release start version_number

Remember: Branches off develop

Finish a release

$ git flow release finish version_number

Remember: Merges into master and back into develop

Create a hotfix

$ git flow hotfix start new_version_number

Remember: Branches off master

Finish a hotfix

$ git flow hotfix start new_version_number

Remember: Merges into develop and back into master

Bonus: For Lazy Developers

I wrote some scripts that make it easier to work with git-flow, or even git in general, and linked them to an alias in my terminal. You can check the project out from GitHub:


There you can do cool things with the blink of an eye:

# Creates a new git-flow feature
$ f my_feature

# Finishes the current git-flow release
$ rl finish

# Pushes the current branch (whatever it is)
$ p

1 thought on “A Git-Flow Explainer & How To Tutorial

Leave a Reply