Git flow workflow simply explained

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 !

Disclaimer

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.

The `git flow` workflow

Key ideas

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 main).
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:

From the develop branch, 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/develop to 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 feature/my-awesome-feature to develop.

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 merge when merging your branch: there will be a single commit on develop.

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.

Where:
- type could be any of: feat,fix,docs,breaking,build,ci,misc,refactor,style,test
- scope could 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 release/vx.x.x from develop
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 master.

Note: in the traditionnal git flow workflow, a release branch merged to master is 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 develop to master to keep the same historic. develop should 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 master, called hotfix/my-hotfix
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 master with a squash and merge. The commit message should include the hotfix message, and the next release version.

Example: hotfix(scope): fix critical vx.x.x
Add a new release, or edit the current release with a new tag.
Rebase develop to master to keep it always at the same level.

Important notes

Each time there is a change in master, do not forget to rebase develop to master:

git fetch -ap && git rebase origin/master and git push -f origin/develop
Same thing for the feature branches, when develop has changed:

git fetch -ap && git rebase origin/develop and git push -f origin/feature/my-awesome-feature

Appendix 1: `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: git flow.

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 git-chlog.

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: v1.1.0 .

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: git-chlog v1.1.0..

Also, you can create a full changelog of you app since the beginning: git-chlog.

As simple as that !

Conclusions

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:

See you soon,

Adem.