Mastering Gitflow : The Ultimate Guide from Noob to Ninja

Hello there! New month, new article! This time, we’ll delve into the core concepts of Gitflow and explore its benefits for teams of all sizes. At Waltio, we have fully embraced the use of this model on all our projects.

One flow to rule them all

Gitflow is a popular branching model designed to streamline collaboration and release management in software development projects. It was first published and made popular by Vincent Driessen at nvie. In other words, a Gitflow is a set of rules that a team imposes on itself for optimal project code management. This branching model provides a structured approach to managing feature development, hotfixes, and releases within a Git repository.

Throughout this article, you’ll find the git commands you need to build your own git flow, as well as the equivalent with the git-flow extension. This extension provides a CLI to manage branches according to GitFlow model. We recommend using it.

Let’s begin our journey, young apprentice because there’s still a long way to go…

The original Gitflow, by Vincent Driessen

Git in the Game

First things first, why do we use Git to build a clean code flow ?

Despite all the critics that could exists towards it, Git has truly revolutionized the way that developers manage their code. Compared to old source code control systems, Git is above them all, notably on merging and branching.

In bygone days, merge conflicts were scary but with Git, it’s so much simple en repetitive by design that it became trivial and we don’t have to worry about branching and merging now!

Enough about git, let’s head onto the development model!

While Git is an important topic, we won’t be covering it in detail in this article. Instead, we’ll assume that you have a basic understanding of Git and focus on how Gitflow works and the benefits of it.

Main branches

At the origin, they were 2 : main and develop branches

At its core, Gitflow revolves around two main branches that Git users knows well, with an infinite lifetime :

• main (or master) : represents the stable, production-ready codebase. This branch stores the official release history.
• develop : serves as the integration branch for ongoing development work. Source code here always reflects the latest delivered development changes for the next release.

Once the source code in the develop branch stabilizes and becomes release-ready, it’s essential to merge all changes back into the master branch and appropriately tag it with a release number.

Therefore, each time when changes are merged back into master, this is a new production release.

The initial action involves enhancing the default master branch by introducing a develop branch following its creation.

git branch develop
git push -u origin develop

You can achieve this with git-flow extension like this :

git flow init

Initialized empty Git repository in ~/projects/.git
No branches exist yet. Base branches must be created now.
Branch name for production releases: [master]
Branch name for "next release" development: [develop]

How to name your supporting branch prefixes?
Feature branches? [feature/]
Release branches? [release/]
Hotfix branches? [hotfix/]
Support branches? [support/]
Version tag prefix? []

At this stage, you know how to deal with primary branches. I think the moment has come to explore supporting branches.

Supporting branches

In addition to the primary branches, there exist several auxiliary branches aimed at facilitating parallel development among team members, simplifying feature tracking, preparing for production releases, and swiftly resolving live production issues. Unlike the primary branches, these auxiliary branches are temporary in nature and are eventually removed.

These branches are :

• Feature
• Release
• Hotfix

Each of these branches serves a distinct purpose and adheres to strict guidelines regarding their originating and merge target branches.

Feature

The original Gitflow only describes feature branch behavior but at Waltio we also uses bugfix branch. These branches are created off develop.

Features branches, feature branches everywhere

Feature branches serve the purpose of developing fresh features or improvements intended for either an imminent release or one scheduled for the distant future. Upon initiating the development of a feature, the specific release into which it will integrate may remain uncertain. The core principle of a feature branch is its existence throughout the feature’s development phase, ultimately culminating in its integration back into the develop branch (to definitively incorporate the new feature into the upcoming release) or its abandonment (if deemed an unsuccessful experiment).

For the bugfix branch it’s the same behavior except they are used to bug fixing (thanks captain obvious).

Creating a feature branch

Without git-flow

git checkout develop
git checkout -b feature_branch

With git-flow

git flow feature start feature_branch

Finishing a feature branch

Without git-flow

git checkout develop
git merge feature_branch

With git-flow

git flow feature finish feature_branch

Release

When preparing for a new release, a release branch is created from develop. This branch allows for final testing, bug fixes, and version number increments before merging into both master and develop.

Wild release branch appeared!

Once the develop branch has accumulated adequate features for a release, or when a predetermined release date approaches, a new branch is branched off from develop, known as the release branch. This marks the commencement of the subsequent release cycle, during which no further feature additions are permitted. The release branch is exclusively reserved for bug fixes, documentation generation, and other tasks related to the impending release.

When the release is deemed ready for deployment, the release branch is merged into the master branch and tagged with a version number. Additionally, it undergoes merging back into develop, which may have evolved since the initiation of the release.

Employing a dedicated branch for release preparation enables one team to refine the current release while another team continues to work on features for the upcoming release. It also delineates distinct developmental phases, facilitating clear communication such as stating, “This week, we are preparing for version 1.0.0,” which aligns with the repository’s structure.

Creating a release branch

Without git-flow

git checkout develop
git checkout -b release/1.0.0

With git-flow

git flow release start 1.0.0

Once the release is prepared for deployment, it undergoes merging into both master and develop branches, following which the release branch is deleted. It’s crucial to merge back into develop as critical updates might have been integrated into the release branch, ensuring accessibility for new features. This is how you can finish a release :

Finishing a release branch

Without git-flow

git checkout master
git merge release/1.0.0
git branch -D release/1.0.0

With git-flow

git flow release finish '1.0.0'

Hotfix

Hotfixes are critical patches applied to the master branch to address urgent issues in production. These branches are created from master, fixed, and merged back into both master and develop.

Time to hotfix!

Hotfix branches serve the purpose of swiftly patching production releases. Similar to release and feature branches, they are structured branches, but unlike them, they derive from master instead of develop. It is imperative that hotfix branches directly fork from master.

Having a dedicated line of development for bug fixes lets your team address issues without interrupting the rest of the workflow or waiting for the next release cycle.

Creating a hotfix branch

Without git-flow

git checkout master
git checkout -b hotfix_branch

With git-flow

git flow hotfix start hotfix_branch

Once the fix is finalized, similar to finishing a release branch, it should promptly merge into both master and develop, with master being tagged with an updated version number.

Finishing a hotfix branch

Without git-flow

git checkout master
git merge hotfix_branch
git tag -a 1.0.0
git checkout develop
git merge hotfix_branch
git branch -D hotfix_branch

With git-flow

git flow hotfix finish hotfix_branch

Bonus branch : support

We don’t use this kind of branch very often, but it is very useful in the case of multi-version support. Indeed, sometimes multiple versions of a project in production must be supported. This is frequently the case on framework-type projects such as Angular, where several versions have to be maintained while users upgrade their versions.

Another use case is a complete project rework that introduces many breaking changes. It may therefore be useful to use this branch to secure the transition between the old and new versions of the project, without blocking users.

Once support for this project version is no longer required, support branch is deleted. By its very nature, only bugfix branches can be merged with this branch, so no new functionality is added.

Benefits

Clear Versioning : With Gitflow, versioning is systematic and easy to manage. Each release is isolated in its own branch, making it simple to track changes and roll back if necessary.

Controlled Development : By separating feature development from ongoing stabilization efforts, Gitflow ensures that unstable code doesn’t interfere with the main development branch. This promotes a cleaner, more organized workflow.

Collaboration : Gitflow encourages collaboration among team members by providing a structured framework for concurrent feature development. Developers can work on separate features without stepping on each other’s toes, leading to smoother integration and fewer conflicts. The cherry on top is that each developer task coming from a project management software (like JIRA) can be correlate to Gitflow.

Risk Mitigation : The use of release and hotfix branches minimizes the risk of introducing bugs or regressions into the production environment. By thoroughly testing changes in isolation before merging into master, teams can maintain a high level of stability and reliability in their releases.

Best practices

While Gitflow offers a solid foundation for collaborative development, it’s important to follow best practices to maximize its effectiveness :

• Regularly merge changes from develop into feature branches to stay up-to-date with the latest codebase. Depends on your preferences, you can “rebase + merge” them to avoid verbose git history (our choice at Waltio) or just merge them with a merge commit.
• Keep feature branches small and focused to facilitate easier code review and integration.
• Prioritize code quality and testing to catch issues early in the development process.
• Communicate effectively with team members to coordinate feature releases and minimize conflicts.

Recommended tools

• Git-flow : provides a CLI to manage branches according to GitFlow model
• Git Lens : a VS Code extension that shows directly in editor informations provided by “git blame” command
• Fork : fast and friendly git client to visualize branches
• Commitizen : commit formatter
• Conventional changelog : generate a CHANGELOG from git metadata

Conclusion

Finally, Gitflow is essentially a series of procedures that each team member must adhere to, ensuring a structured software development process. It can be used for projects that have a scheduled release cycle.

It provides a robust framework for managing complex software development projects, offering clear guidelines for branching, collaboration, and release management. By adopting Gitflow at Waltio, teams can streamline their workflows, improve code quality, and deliver more reliable software releases. Whether you’re working on a small startup project or a large enterprise application, mastering Gitflow can significantly enhance your development process.