the skinny on git-flow

Today we switched over from chaotic use of git to the more systematic git-flow. We made our first release, we finally have production code to track, so it is time to get organized. Here’s the fifteen-minute rundown for coworkers:


Git-flow is a methodology for using git, and a git extension that streamlines it. Here’s what you need to know.

Immortal Branches

There are two branches that last forever. 
master: Every commit on master is a release version. Every commit is tagged with its version number. Before code is merged into master, it’s been through all testing and is ready for prod. If you automate production deployment, it’ll work off the master branch.  

develop: Work happens on the develop branch. Small changes are direct commits here. Features will be merged in here. develop is always ready for new functionality.

Mortal Branches

There are three species of branches that come and go. First, let’s take a look at how code gets from develop to master.


release: When the app is feature-complete and ready to release to test, it’s time for a release branch. The release branch is named release/versionNumber. Release branches start from develop. Once a release branch is created, develop represents the next version of the app, while the release branch holds the version under test. Commit any fixes to the release branch. 

When testing is complete, finish the release. The release branch is merged into master (and develop, so the fixes get into the next version). Goodbye, release branch. Your commits will remain in our tree forever, but your name is no longer needed.

The next mortal branch is familiar to git developers, even renegades like us who have been committing to master for a year.
feature: A feature is a piece of new functionality that will be include several commits, span more than a few hours of development, or be worked on by multiple people. Branching groups the commits together for posterity. It allows me to switch at will between work on the feature and fixes or investigations on develop. Starting a feature creates a feature/featureName branch off develop:

Finishing a feature merges back these commits back into develop. The feature branch is deleted, but the commits are still grouped. The merge has the feature branch name in its commit message for posterity(1). Note that a feature can start work while one release is under development, and wind up in the next release.

What happens when bug reports come in from the users? How do we get the fixes into production code after develop has moved on with work for the next release?


hotfix: The third species of mortal branch is hotfix. This branches off master, and fixes made here wind up in a new production release. The name of the hotfix branch is hotfix/newVersion.

When the hotfix is done, it is merged back into master, forming a new production version. It also gets merged back into develop, to keep develop up with the latest.

That’s It

That’s the process of git-flow. Two immortal branches, three mortal branch species. master contains only tagged production releases, while develop is always ready for new functionality. Features come off develop and go back to develop. Releases move code from develop to master, with testing in between. Hotfixes branch off master and go back to master as a new release.


Minor complications occur when this system is implemented on a real team across repositories, but that is another post.


(1) If the feature branch has only one commit, then finishing might do a fast-forward with no merge commit.