git: Implementing “Gitflow Workflow”

While working on a project that gets bigger and bigger features, client requirements and scope, I needed to create (work with) some repositories. While doing some research, consulting with some co-workers and analyzing the current status of this repository, I decided to implement the workflow that Atlassian presents as “Gitflow”. And I want to illustrate it with a little and simple execution example, but before check out the workflow schema:

Figure 1) Basic workflow schema for Gitflow. Reference: Copyright © 2017 Atlassian at

In this schema you can see three branch levels (Figure 1). The first branch is Master, this branch will act as a production branch, the second one is Develop which will be merged between Master and the Feature branches every time a new feature is completed and last but not least we have the last level named Feature, which is not just one branch but multiples branches that will be created during the development of the project. But! what if we include a new level of branches named Release between Develop and Master? You might wonder, why would you do that?!. Well, here is your answer.

We need to release our work, if not what is the point? We need a stable place where we can test safely, one that will not change every day like Develop does. We need a release branch, this branch is created from develop in order to provide a stable environment before we go live. But let’s be honest, we are not perfect and sometimes we make mistakes. When our super awesome new feature has been merged into Develop and the release branch has been created, we might realize that there are some bugs that have to be fixed, or maybe we forgot to do some documentation (who needs that anyway, right?) or maybe some special change is needed before going to production, here is where this release branch comes handy. All needed changes will be done in this branch and once everything is fixed, patched, documented, tested and blessed by the pope, we are going to merge it with Master and Develop and tag it with the a number version (optional but recommended). The Develop merge must be updated in both sides, so we don’t lose all of our beautiful work. So, the new schema will look like the Figure 2:

Figure 2) Workflow schema for Gitflow including Release branches. Reference: Copyright © 2017 Atlassian at

As I said before, our feature will probably have bugs that passed the review and that hid from our beloved tester and made its way into production (awful little beasts), in this case it comes in handy to have maintenance branches which we will name Hotfix, they will be used for quick patches in production, no need to say that they have to be forked from Master branch and, as we did with Release, it will be merged into Develop branch too. Check the last Figure and let’s go right to the example.

Figure 3) Final workflow schema for Gitflow including Hotfix branches. Reference: Copyright © 2017 Atlassian at

The example (with git commands)

Assuming that we have our project with git initialized, create the Develop branch:

git branch develop
git push -u origin develop (if you are creating it)
git checkout -b develop origin/develop (if you are cloning and copying locally the develop branch)

Now lets imagine that we are working on a new feature, create the Feature branch:

git checkout -b new-awesome-feature
git add <perfect-code-made-by-us>
git commit

The new feature is completed and commited with the last command, so we need to merge it into Develop branch, but first, let be sure that nothing has changed on this branch:

git pull origin develop (checking for up to date)
git checkout develop (switching to local develop branch)
git merge new-awesome-feature
git push
git branch -d new-awesome-feature (deleting the new feature branch)

Now we merge our new awesome feature into Develop, so what now? It cannot stay there forever, we have to show it to the world! We have to release it! So, let’s prepare a new Release branch that will be used for testing, documentation, etc:

git checkout -b release-0.1 develop (creating the release branch)

Finally, we need to ship it to production (Master) and Develop as well:

git checkout master (switching to local master branch)
git merge release-0.1 (merging)
git push
git checkout develop (switching to local develop branch)
git merge release-0.1 (merging as well)
git push
git branch -d release-0.1 (deleting the release branch)

And don’t forget the tag :)

git tag -a 0.1 -m “new-feature completed and released” master
git push — tags

Some magic is done and our new awesome feature is released, Tada! But wait, something broke, fire, alarms, users complaining! Sh*@ is going down. What do we do?! Hotfixes are here to help you:

git checkout -b issue-001 master (creating the hotfix branch)
git checkout master (bug/issue fixed and committed at this step)
git merge issue-001
git push

And as always, merge it into Develop too:

git checkout develop
git merge issue-001
git push
git branch -d issue-001 (deleting the hotfix branch)

That’s all about this Gitflow workflow, it’s time to try it and see how useful can be for your case.

Isaac Herrera & Marjorie Figueroa


This information was extracted from Atlassian website (URL linked) and can be read on more exhaustive way there. Take a look :)