Git Flow - About, installing and using

Jürgen Gutsch - 01 April, 2019

The people who know me, also know that I'm a huge fan of consoles and CLIs. I run the dotnet CLI as well as the Angular CLI and the create-react CLI. Yeoman is also a tool I like. I own a Mac, but cannot really work with the Mac UI. I really prefer the terminal in Mac. Also Git is used in the console the most time. The only situation where I don't use git in the console, is while resolving merge conflicts. I configured KDiff3 as the merge tool. I don't really need a graphic user interface for all the other tasks to work with Git.

So I do using the Git Flow process.

About Git Flow

In general Git Flow is a branching concept over Git. It is pretty clear and intuitive, but following this concept manually in Git is a bit hard and needs some time. Git Flow is now implemented in many graphical user interfaces like SourceTree. This reduces the overhead.

Git Flow is mainly about merging and branching. It defines two main branches, which are "master" as the production/release branch and "develop" as the working branch. The actual work is done in different types of feature branches:

  • "feature" a branch created based on "develop" to implement new featues
    • will be merged back to "develop"
    • branch name pattern: feature/<name|ticket|#123-my-feature>
  • "release" a branch created based on "develop" to create a new release
    • the branch name gets the tag name
    • will create a tag
    • will be merged to "master" and "develop"
    • branch name pattern: release/<tag|version|1.2.0>
  • "hotfix" a branch created based on "master"
    • the branch name gets the tag name
    • will create a tag
    • will merge to "master" and "develop"
    • branch name pattern: hotfix/<tag|version|1.2.3>
  • "bugfix" less popular. We use "feature" to create bug fixes
    • not available in all tools
    • behaves like "feature"
  • "support" much less popular. We don't use it
    • not available in all tools
    • almost behaves like hotfixes

I propose to have a look into the Git Flow cheat sheet documentation to see how the branching concept works: http://danielkummer.github.io/git-flow-cheatsheet/

Git Flow is also a tool provided as Git extension. This reduces branching, merging, releasing tagging to just one single command and does all the needed tasks in the background for you. This CLI makes it super easy to follow Git Flow.

Install Git Flow as Git Extension

The installation is a bit annoying, because it needs a some additional tools and some more tasks for just a small Git extension.

To install it you need cygwin, which also is a console that gives you Linux like tools on Windows. The easiest way to install cygwin is to use Chocolatey, which is a packet manager for Windows. (apt-get for windows). You can also install it manually by running the installer, but you need to ensure to also install cyg-get, wget and util-linux, which is much easier using Chocolatey.

To install Chocolatey follow the instructions on https://chocolatey.org.

Open a console and type the following commands

choco install cygwin
choco install cyg-get

If this is done you can use cyg-get to install the needed extensions for the cygwin console

Open the console and type the following commands:

cyg-get install wget
cyg-get install util-linux

Now the cygwin is ready to use to install Git Flow. Type

cygwin

This will open the cygwin bash inside the current console.

Now you are able to run the installation of Git Flow. Copy the following command to the cygwin bash and press enter:

wget -q -O - --no-check-certificate https://raw.github.com/petervanderdoes/gitflow-avh/develop/contrib/gitflow-installer.sh install stable | bash

If this is done exit the bash by typing exit and close the console by typing exit. Closing the consoles and open it again ensures all the environment variables needed are available.

Open a new console and type git flow. You should now see the Git Flow CLI help like this:

Every time you checkout or create a new repository you need to run git flow init to enable Git Flow.

Using this command you will setup Git Flow on an existing repository by configuring the different branch prefixes and specifying the two main branches. I would propose to choose the default prefixes and names:

Working with Git Flow

Using Git Flow is pretty easy using this CLI. Let's assume we need to start working on a feature called "Implement validation". We could now write a command like this

git flow feature start implement-validation

This will work as expected:

Since the most of us are using a planning tool like Jira or TFS it would make more sense to use the ticket number here as feature name. In case you use the TFS I would propose to add the work item type to the number:

  • Jira: PROJ-101
  • TFS: Task-34212

This helps to keep the branch names clean and you don't start messing around with long branch names or wrong names. Git Flow usually deletes the feature branch after merging it back. So the list of branches will never be too long. But anyway, I learned in the past few years, it is much easier to follow ticket numbers than weird named branch names, because we talk about the current tickets every day in the daily scrum meeting.

All the commands that are not related to branches can be done using the regular Git CLI. That means commands to commit, to push and so on.

Git Flow will merge the branches, if you finish them. It doesn't work with rebase or other approaches. This means it'll take over the entire history of the feature branch. Because of this I would also propose to add the ticket number to the commit messages like this: "PROJ-101: adds validation to the form". This makes it easy to follow the history in case it is needed.

To finish a feature you should first merge the latest changes of the development branch in:

git fetch --all
git merge develop
git flow feature finish

If you don't add the feature name to the git flow feature finish command, Git Flow will try to close the current feature branch and will write out a message in case the current branch is not a feature branch.

I would propose to always merge the latest changes of develop to the current feature branch to solve possible conflicts within the feature branch instead in the develop branch. This way the merge to develop will almost never have a conflict.

I showed the way how to work with Git Flow using the feature branch. But it'll work the same way with the other branch types. Except with the release and the hotfix branches where you need to set the tag name as feature name. This should be the version number of the release or the version number of the hotfix.

While finishing these two branches Git Flow will ask you for a tag message. After finishing it you need to push both the master and the develop brunch, as well as the tags:

git push --all
git push --tags

For more information about the Git Flow commands please follow the documentation on Daniel Kummer's Git Flow cheat sheet: http://danielkummer.github.io/git-flow-cheatsheet/. (Which is BTW the best Git Flow documentations ever)

Conclusion

I really love the CLI help of this tool. It is not only descriptive but also explaining. The same way the GIT CLI is explaining things. It is also providing proposals in case a command is miss-spelled.

Git Flow helps me to speed up the branching and merging flows and to follow the Git Flow process. I proposed to use Git Flow in the company and works pretty well there. And I learned a lot about how this process works in production.

As written somewhen in the past, It also helps me to write my blog. I really use Git Flow to organize my posts I'm working on. I'm creating a feature per post and a hotfix in case I need to fix a post or something else on the blog. I use SemVer to version my releases and hotfixes: Every post increases the feature number and a hotfix increases the patch number. The feature number also is the number of post in my blog. The number of open features in my blog is the number of posts I'm working on. This way I can work on many posts separately and I'm able to release the posts separately.