Got a new job or in your current one they are planning to implement Git-Flow and you don't know what the fuss is all about?
You've come to the right place. In this post I'll break it down for you, however, if you already know it and just want to tinker around with it, you can just skip to the tutorial.
In a few words, Git is a version control system, an essential tool to handle the life cycle of the development of an application.
So far so good, classic Git, but problems start showing up when handling teamwork: you and your team might decide to just work on the main branch of the project and create some secondary branches on special occasions, but what happens when there is a lot of work or several people must work in the same function at the same time?
When working as a team, it is necessary to define conventions or good practices so that everyone knows how to work together. Git-Flow is one of many so-called workflows, quite popular for its practicality and relatively quick learning, it is a way to organize the branches of the project repository.
It seems and is complicated at first glance, but when you know the different branches used and the reason for their existence, you will see that the handling is quite logical.
As we saw in the image, Git-Flow uses several branches to organize the development:
If you have used Git before, you will be familiar with the
master branch. In this new context, this branch is "untouchable", no one from the team should make any changes directly to it, nor create new branches from it, with one exception that we will review later.
When creating a new project, or when starting to use Git-Flow, the
develop branch must be created from
master, and like
master, it will be a "long-lived branch", that is, it will never be deleted and will be parallel to
As its name implies, the
develop branch serves as the basis for working on all new project features and fixes, which is why it is considered the main branch.
Once all the new project functions & bugfixes have been completed and
develop is on a rather 'stable' state, we should
merge develop in
master branch should always reflect an 'production' state, so it is important that we do not make changes directly to it, since every time there is a new
commit, we should
tag it to define the new version and publish it. In this context the
master branch is sometimes referred to as the 'integration' branch.
feature branches are those that we dedicate completely to the development of each of the new planned functions to be added to the project in the next version. They come always from
develop and we must
merge 'em back to
Following Git-Flow best practices, when creating a new
feature branch, we must always add the prefix
feature/, in this way we can maintain a good organization and just by looking at the active branches we can quickly identify the work in progress.
At the same time, it is important to name the
feature branches in a descriptive way to identify the purpose of the branch:
❌ feature/new-method ✔️ feature/add-support-for-json-parsing
The important thing about feature branches is that they only live during development and that they should disappear once we have done the
develop or that they are discarded if the function is no longer necessary.
NOTE: the prefix
feature/* is the default, but if you or your team deem it necessary, you can adapt the prefix to anything else, for example
release branch is used to regroup the functionalities and corrections made, to prepare for the release of the version in development. This branch starts from
develop and must be
merged in both
The perfect time to create a
release branch is when the
develop branch looks as much as possible to what we want to have in production, it provides then a moment to make last minute corrections that we may have forgotten, or to make changes of the project that do not necessarily need a whole branch to be carried out, for example to increase the version number.
release branches also have a prefix,
release-*, usually followed by the version number or name they represent, for example:
The advantage of having a release branch is that work can continue in
develop and we can create other new
feature branches, since the planned work is already in the release one and will
should not have major changes.
hotfix branches come from
master and must be
merged back in
develop. They are used to make quick or critical corrections to the project, in order to publish a new version as soon as possible.
NOTE: If you create a
hotfix branch but there is already a
release branch, instead of doing the
develop, it must be
In some projects we can see that in addition to the
hotfix branches, sometimes we have some branches with the
bugfix prefix. The difference between these two types of branches is that the
bugfix ones behave like
features and the
hotfix ones behave like
In other words, we can use the
bugfixes to make minor bug fixes that can wait for the release of the development version, while the
hotfixes cannot wait and should be published as soon as the development has been approved.
✔️ bugfix/fix-some-thingy-that-almost-nobody-uses-and-its-not-really-important ✔️ hotfix/fix-clic-on-top-right-corner-of-login-button-sets-the-users-computer-on-fire
Initialize Git-Flow in the project
# Initialize Git in the project, create the develop branch and # configure the prefixes of the other branches. # Then, switch to the develop branch git flow init
Starting to work on a new feature
# Creates a new feature/* branch and starts pointing to it git flow feature start <feature-name>
Finish a feature
# The name of the feature is optional, not really necessary if # you are already on the branch. # Changes to develop, performs a merge of the feature to develop # And deletes the feature branch git flow feature finish <feature-name>
NOTE: All these actions are performed in your local repository, nothing is done in the distant one, unless you
pushthe branches. Always remember to
pushwhen you finish your features, to update
Prepare for the new version
# Creates a new release/* branch from develop y change the pointer to it git flow release start <version-name>
NOTE: Right after updating the version number of your project it is a good time to publish the release branch in
Finishing the release
# Checks out the master branch # Merges the release in master # Creates the version tag using the name of the release branch # Checks out the develop branch # Merges the release in develop # Deletes the release branch git flow release finish # Don't forget to push! git push origin master git push origin develop git push --tags git push origin :release/1.2.0 (if the release was in the distant repo)
Creating a hotfix
# A hotfix branch may be created from a specific commit or from the last commit if not specified. # Creates a hotfix branch and checks it out git flow hotfix start <hotfix-name> [<commit>]
Finish a hotfix
# Same behavior as the release branches # You can also specify the option -T or --tagname # to create the tag correctly if the name of your # hotfix branch is not a version number. git flow hotfix finish [<-T version-name>]
For the next article, we will talk about other strategies, but if you want to learn more about Git-Flow at the moment, here are some sources that I used for this article.
A successul Git branching model: The original article from the author of Git-Flow
Git-Flow cheat sheet: The essential Git-Flow cheat sheet
GitFlow considered harmful: A simpler alternative to Git-Flow and the subject of my next article.