🇪🇸 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.
-
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>
We can see how the console tells us the actions performed and that we can start working on the new branch. -
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 topush
when you finish your features, to updatedevelop
. -
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
. -
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>]
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.
Top comments (0)