What is Git Flow and why implement it ?
Working on a repository with several contributors may be hard and confusing.
At least if there is not any sealed workflow regarding the usage of git.
That's why some people (I honestly don't know who) have designed a solid workflow to enhance the usage of git.
This workflow is simply named git flow. Let's talk about that !
In this tutorial there may be some changes compared to the original git flow workflow.
The key ideas are kept, feel free to compare with other articles or tutorials on the web.
I also try to add some enhancements regarding commit format in order to create changelogs easily.
git flow workflow
One of the key ideas of the workflow is to keep a single branch for production releases, and another branch for adding new features to the project:
master: branch for releases (some people name that branch
develop: branch that hosts new features between two releases.
Developing a new feature
Let's say you want to develop a new feature, the idea is to follow these few steps:
developbranch, create a new branch:
git checkout -b feature/my-awesome-feature
- Do your magic with the code, add as many commits as you want.
- Once the code is ready to be tested and reviewed by your colleagues, open a Merge / Pull Request.
Don't hesitate to rebase your branch against
origin/developto be sure that you have the latest changes.
To do a rebase locally:
git fetch -ap && git rebase origin/develop
After that, you need to push force to the remote branch because of the rebase:
git push -f
Once your code is tested, has passed your CI pipeline and approved by your pairs, you can merge
Do this step in your Git hosting service web application.
Note: In order to keep a nice commit historic on
develop, be sure to select
squash and mergewhen merging your branch: there will be a single commit on
You will be asked for a merge commit message:
Ideally, you can use this well known format for this message:
type(scope): my commit message.
typecould be any of:
scopecould be any word.
Other formats exist and could be used.
The idea is to be able to parse commits messages to create a clear ChangeLog between releases.
But it's not part of the git flow workflow. So do what you want regarding your commit messages.
Preparing a new release
Now, let's say you have some cool features / fixes ready to be deployed on production, the idea is to follow these few steps:
- Create a branch
- If you have any integration tests, use this branch to validate your release candidate
- If there are some bugs, you can add commits to fix them on this branch.
Once you're done testing, you are ready to merge it to
Note: in the traditionnal git flow workflow, a release branch merged to
masteris meant to be squashed before merged. But as I said in the disclaimer, I decided to modify a little bit the workflow. The idea is to keep commits from develop when merging to master. Merge commit could be as simple as
vX.X.X. Keep those well formatted commits to master will help you create changelogs. We'll see that at the end of the article.
- Do a new release (with a new tag), or edit your current major release with a new tag and describe the changes in the release description.
- Do not forget to rebase
masterto keep the same historic.
developshould be aware of what's in
master. Always ahead.
Developing hot fixes
Sometimes (not to say all the time ...), there are bugs in a fresh release.
Some bugs can wait for the next release to be patched, but some cannot.
They must be patched as fast as possible. Git flow has planned this case, follow these steps:
- Create a branch from
- Add your changes
Test it to check that the hotfix is:
- patching the bug
- not causing any other part of the app(s) to crash
- not causing any regression
Once the hotfix is tested and approved by the team, merge to
masterwith a squash and merge. The commit message should include the hotfix message, and the next release version.
hotfix(scope): fix critical vx.x.x
- Add a new release, or edit the current release with a new tag.
masterto keep it always at the same level.
Each time there is a change in
master, do not forget to rebase
git fetch -ap && git rebase origin/masterand
git push -f origin/develop
Same thing for the feature branches, when
git fetch -ap && git rebase origin/developand
git push -f origin/feature/my-awesome-feature
git flow , a package to facilitate the implementation of git flow workflow
When reading the explanation of git flow, I can understand that you think this workflow is hard to maintain in the long run.
That's why a package has been released to automate the workflow:
I personnaly don't use it because I'm used to work with this workflow for a while now.
But if you want to facilitate the use of the workflow in your team, you can check this repository https://github.com/nvie/gitflow and use it !
Appendix 2: Create consistent changelogs between two tags
In this article, some enhancements have been made from the traditional git flow workflow.
The main one deals with git commit messages.
If you follow those few guidelines, then you can create changelogs easily when releasing a new version of your app.
To do so, you need to install a small binary called
You can find it there https://github.com/git-chglog/git-chglog
I'm not going to do a full tutorial on how to use it, so be free to check its documentation and profit from it.
I'll just show you how it can be used in our case.
Let's say you have a new version of your app:
The tag before was
v1.0.7. You want to create a changelog between those two tags.
If you follow our advices regarding messages format, you can create a simple changelog by running:
Also, you can create a full changelog of you app since the beginning:
As simple as that !
In this article I wanted to show how a clean git workflow can help you and your team optimize your time and help you focus on what's important.
I hope this article / tutorial will help you guys understand how git flow works and how to implement it on your repositories !
I also want to share with you some cool articles / videos about git flow:
- Toptal: enhanced git flow explained
- The gitflow workflow - in less than 5 mins (from the youtuber
See you soon,