☕ Git-Flow: an introduction

🇪🇸 Version en español
🇫🇷 Version française

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.

🧐 The Context

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?

📓 Git-Flow

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.

You have probably already seen this image or a similar one when searching the term Git-Flow on the Internet:
A picture is worth a thousand words, or in this case a couple thousand more

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.

🌳 Branches

As we saw in the image, Git-Flow uses several branches to organize the development:

• master
• develop
• feature
• release
• hotfix

🌴 master & develop

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 frommaster, and like master, it will be a "long-lived branch", that is, it will never be deleted and will be parallel to master.

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.

The 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

The 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 develop.

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 merge in 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 function/*

⭐ release

The 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 develop and master.

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.

Following Git-Flow, release branches also have a prefix, release/* or release-*, usually followed by the version number or name they represent, for example: release/1.2.0 or release/5.0 or release/1.0.0-rc.1+build.123.

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

The hotfix branches come from master and must be merged back in master and 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 merge in develop, it must be merged in master and release instead.

⚔️ hotfix vs bugfix

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 releases.

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

✏️ Tutorial

For this tutorial and in order to simplify it, I will use the Git-Flow console plugin of Peter van der Does, but you can also see the equivalent classic Git commands to Git-Flow commands.

1. 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
   

   

2. Starting to work on a new feature
   

   # Creates a new feature/* branch and starts pointing to it
   git flow feature start <feature-name>
   

   
   We can see how the console tells us the actions performed and that we can start working on the new branch.

3. 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 push the branches. Always remember to push when you finish your features, to update develop.

4. 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 origin.

5. 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)
   

   

6. 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>]
   

   

7. 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>]
   

   

Next steps

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.