How-to
How to Use Gitflow in 7 Steps
- Release tag
- Feature flag
- Loglune
On this page
Gitflow is the branching model Vincent Driessen published in January 2010: two long-lived branches, master for production-ready code and develop for the next release, plus feature, release, and hotfix branches with fixed rules for where each one starts and where it merges back. This guide uses Gitflow in 7 steps: check that your software fits Gitflow, set up the main branches, develop on feature branches, cut a release branch, finish the release, fix production with hotfix branches, and ship merged but unreleased features switched off with feature flags.
The steps follow Driessen’s post and apply to software released in explicit versions. The final step adds feature flags, which the post does not cover.
What Gitflow means
Driessen’s post A successful Git branching model (January 5, 2010) presents the model as a set of procedures that every team member follows to reach a managed software development process. The repository setup has one central repository, called origin, that the team treats as the source of truth, and each developer pulls from and pushes to it. Driessen’s note of reflection spells the model git-flow; this guide writes Gitflow.
Driessen calls master and develop the main branches, with an infinite lifetime, and calls feature, release, and hotfix branches supporting branches, with a limited lifetime because they are removed eventually. The post also says the supporting branches are plain Git branches, categorized by how the team uses them.
| Branch | Branches off from | Merges back into | Naming | Lifetime |
|---|---|---|---|---|
| master | Not specified | Not specified | master | Unlimited; every merge into it is a production release |
| develop | Not specified | Not specified | develop | Unlimited; the integration branch for the next release |
| Feature | develop | develop | Any name except master, develop, release-, or hotfix- | Until the feature is merged or discarded |
| Release | develop | develop and master | release-* | Until the release is tagged and merged back |
| Hotfix | The tag of the production version on master | master and develop, or the open release branch instead of develop | hotfix-* | Until the fix is tagged and merged back |
Before you adopt Gitflow
Six inputs decide whether the branch rules hold up in daily work.
- A central repository that the team treats as origin.
- A version numbering rule, because Gitflow assigns the version number when a release branch starts.
- A build that runs from develop, such as the automatic nightly build in Driessen’s post.
- A decision on who finishes releases and hotfixes, since those steps merge into master and create tags.
- A feature flag setup for features that merge before they are ready for customers.
- A record of which release each customer runs, when several versions are supported at once.
How to use Gitflow in 7 steps
1. Check that your software fits Gitflow
Driessen’s note of reflection (March 5, 2020) says Gitflow became hugely popular and that many teams started treating it as a standard, and also as a dogma or panacea. The note says web apps are typically delivered continuously, not rolled back, and do not need several versions supported in the wild, and that this is not the class of software the model was written for.
| Your software | Driessen’s 2020 suggestion |
|---|---|
| A web app delivered continuously, with one version in production | A much simpler workflow, such as GitHub flow |
| Explicitly versioned releases | Gitflow may still fit |
| Several versions supported in the wild | Gitflow may still fit |
The note ends by telling teams to consider their own context and decide for themselves.
2. Set up master and develop
Driessen’s model keeps two main branches in the central repository. The HEAD of master always reflects a production-ready state, and the HEAD of develop reflects the latest delivered development changes for the next release. Driessen notes that some call develop the integration branch and that automatic nightly builds come from it.
Every merge into master is a new production release by definition. Driessen’s team was strict enough about this rule that a script could, in principle, build and roll out the software to production on every commit to master.
3. Develop each feature on a feature branch
Start each feature on a branch off develop, and merge it back into develop when it is finished, or discard it after a disappointing experiment. Driessen notes that feature branches typically live in developer repositories and not in origin, and that the target release of a feature may be unknown when work starts.
Driessen merges feature branches with the –no-ff flag, which always creates a merge commit even when a fast-forward is possible. The merge commit keeps the record that the feature branch existed, groups the commits that added the feature, and makes reverting the whole feature straightforward.
4. Cut a release branch when develop is almost ready
Branch a release branch off develop when develop almost reflects the desired state of the new release. Every feature targeted at that release must be merged into develop by then, and features for later releases wait until the release branch exists. Driessen assigns the version number at the start of the release branch and not earlier.
While the release branch is open, it takes minor bug fixes and release metadata such as the version number and build dates. Driessen strictly prohibits large new features on a release branch; they go to develop and wait for the next release. Meanwhile develop is free to receive features for the next release.
5. Finish the release: merge, tag, and merge back
When the release branch is ready, merge it into master and tag that commit on master for future reference. Then merge the release branch back into develop, so later releases keep its bug fixes. Driessen expects the merge back into develop to conflict, likely over the version number, and the conflict is fixed and committed. After both merges, the release branch is removed. Driessen also mentions signing the tag cryptographically as an option.
6. Fix production with a hotfix branch
When a critical bug in production must be fixed at once, branch a hotfix branch off the tag on master that marks the production version, bump the version number, and commit the fix. Work on develop continues while one person prepares the fix.
To finish, merge the hotfix into master and tag it, then merge it into develop. When a release branch exists at that moment, merge the hotfix into the release branch instead, and the fix reaches develop when the release finishes; if develop needs the fix at once, Driessen says it can be merged into develop as well. When the failing code path sits behind a feature flag, switching the flag off stops the problem for customers while the hotfix branch is prepared, and the fix still goes through master and develop.
7. Ship merged but unreleased features switched off with feature flags
In Gitflow, a feature merged into develop joins the next release, and a feature meant for a later release waits on its branch until the current release branch is cut. A feature flag adds another option: merge the feature into develop with its code path switched off, ship it in the release, and switch it on later without a new release. Pete Hodgson’s article Feature Toggles (October 9, 2017) describes release toggles, which let incomplete code paths ship to production as latent code that may never be turned on.
In Loglune, switching the feature on after the release is a flag edit, and every flag edit is appended to the change history as a change event with the customer, the actor, the time, the target flag, and the values before and after. Loglune assigns percentage buckets with the same MurmurHash3 hashing in every Loglune SDK language and version, so a customer lands in the same bucket for the same rule whichever release evaluates the flag. When a customer reports a problem after the release, pick the customer and the time T of the report. Loglune rebuilds the flag state at T from the change history and delivers it in reproduction mode to a development, CI, or staging environment, and one delivery counts as one reproduction. Read together with the release tag the customer runs, the rebuilt flag state shows which code path the customer was on. Loglune reproduces the flag evaluation, not the root cause in application code. The walkthrough on reproducing a bug that affects one customer covers the path from a report to a reproduction.
Editorial example (not a customer case): a feature merged and switched off across a release
The table follows one feature through a Gitflow release of a desktop invoicing app. Weeks, versions, and names are illustrative.
| When | Branch or tag | Event | bulk-export flag |
|---|---|---|---|
| Week 1 | feature/bulk-export | Feature developed on a branch off develop | Created, off for every customer |
| Week 2 | develop | Feature merged, launch date not set | Off |
| Week 3 | release-2.4 | Release branch cut, version 2.4 assigned | Off |
| Week 4 | master, tag 2.4 | Release merged into master and tagged, then merged back into develop | Off |
| Week 5 | No new release | Export switched on for 3 pilot customers | On for 3 customers, change event recorded |
| Week 6 | No new release | A pilot customer reports a failed export from Tuesday at 4:05 p.m. | Customer’s flag state at that time rebuilt in staging, showing the export on |
| Week 6 | hotfix-2.4.1 | Fix branched off tag 2.4, merged into master and develop, tagged 2.4.1 | On for 3 customers |
The rebuilt flag state and the customer’s release, 2.4, pointed the team to the export code path in tag 2.4, so the hotfix branched off tag 2.4 instead of starting from develop.
Troubleshooting Gitflow
- The history no longer shows which commits formed a feature: merge feature branches with –no-ff, as Driessen recommends, so each feature has its own merge commit.
- The merge of a release branch back into develop conflicts: expect a conflict over the version number, fix it, and commit, as Driessen’s post describes.
- A large feature lands on a release branch: move it to develop, because Driessen’s model prohibits large new features on a release branch.
- A hotfix is missing from the next release: merge the hotfix into develop as well as master, or into the open release branch when one exists.
- The team delivers a web app continuously and Gitflow slows it down: consider the much simpler workflow Driessen suggests in the 2020 note.
- A customer report arrives after a feature was switched on without a release: rebuild that customer’s flag state at the reported time, and read it with the release tag the customer runs.
FAQ
Is Gitflow the same as git flow?
Gitflow, git-flow, and git flow name the same branching model from Driessen’s 2010 post. Driessen’s note of reflection spells it git-flow.
Is Gitflow a branching strategy?
Gitflow is a branching strategy with release management rules. Driessen’s post says it covers the branching strategy and release management of the author’s projects, and that the branch types are plain Git branches categorized by how the team uses them.
What does the Gitflow workflow look like for one release?
Features merge into develop, a release branch branches off develop and takes bug fixes and release metadata, and the finished release merges into master with a tag and back into develop. Production fixes between releases go through hotfix branches that start from the tag on master.
Is Gitflow still used?
Driessen’s 2020 note says Gitflow became hugely popular in its first 10 years, without giving usage figures. The note still recommends Gitflow for explicitly versioned software and for software with several versions in the wild, and suggests a much simpler workflow for continuous delivery.
Deciding whether the Gitflow branching strategy fits
Use Gitflow when the software ships in explicit versions or several versions must be supported in the wild, and the team wants release branches for stabilizing each version. Choose a simpler workflow for a continuously delivered web app, as Driessen’s 2020 note suggests. In either model, put features that merge before launch behind feature flags and keep the flag change history, so a report after a release can be traced to both the release tag and the flag state one customer had at that moment.
Check what a released feature served one customer
In a Gitflow project, a release tag fixes the code, and feature flags decide which code paths run after the release. Loglune records every flag edit as a change event with the actor, the time, and the values before and after, and rebuilds the flag state a customer had at time T for your development, CI, or staging environment. The Free plan includes 5 reproductions.