HubFlow - GitHub and the GitFlow Model Together

stuartherbert's picture

We really like GitHub for hosting our Git repositories, and we've found Vincent Driessen's GitFlow very useful for organizing how we work inside each of our Git repositories. But it could be clearer and easier how to use the two together, especially if you're new to Git too. To help, we've adapted the original GitFlow model to make it clear how to use it with GitHub, and we've extended the original GitFlow tools to make it easier to use GitFlow with GitHub.

We've called this HubFlow, and it's available now on GitHub if you want to use it yourself.

Why GitHub + GitFlow

Unless you have specialist needs, hosting your Git repos yourself is a distraction from building a great product for your customers.  GitHub does the job very well, and there's a good chance that your engineers are already using it if they're active in open-source communities. It also has the advantage of being hosted outside your firewall, so it's available wherever you can get onto the Internet - from the office, at home, or whilst traveling.

GItFlow is a very straight-forward strategy which uses different branches to parallelize different stages of development as much as possible. Whether you're working alone on a project, or as part of a team, GitFlow gives you a way to organize your Git repo, and a workflow to follow as ideas progress to development and then to releases. It also comes with a handy set of GitFlow tools - extra commands for Git to simplify creating and managing the different kinds of branches in the GitFlow model.

Reducing The Friction Of Using GitFlow And GitHub Together

Both the GitFlow model and the GitFlow tools are hosting agnostic; they limit their scope to your local Git repo clone. Neither gets into the detail of what to do if you host your Git repos yourself, nor how to incorporate GitHub's key differences from vanilla Git (GitHub offers a fork + clone model, and has its own pull request system).

This leaves some important questions that you need to answer when you roll out GitFlow to a group of engineers:

  • Do you use GitHub's fork & clone approach, or just clone directly?
  • How do two or more engineers collaborate on the same feature?  What if they're working remotely, and cannot push/pull directly from each other's local Git repo clones?
  • How do you go about integrating changes back into the develop branch? Do you merge locally, or use GitHub pull requests?
  • What extra commands do you need to run to send changes up to GitHub? When do you need to run them? And what about fetching changes back from GitHub?
  • How do you manage version numbers in your projects?

Over the last six months, we've experimented with different answers to these questions before finally settling on one common approach that we're using across the entire company. As it's a mashup of GitHub and GitFlow, we've christened it HubFlow.

The HubFlow Model

The HubFlow model is how we're using GitFlow with GitHub here at DataSift

The HubFlow Model

If you already know GitFlow, the key points are:

  • Don't fork repos on GitHub - clone the master repo directly.
  • Push feature branches back to GitHub so that others can collaborate on the same feature. (Or, so that you can work on it at home on an evening if inspiration suddenly hits you!)
  • Don't merge features locally - use the GitHub website to create pull requests from feature branches. (And, don't accept your own pull requests - ask someone else to do a code review!)
  • Use the HubFlow tools to automatically push/pull as required.
  • Use semantic versioning.

If you've never used the original GitFlow, we have written up a tutorial on the GitFlow branching model, and all of the full HubFlow steps are available on one handy reference page.

The HubFlow Tools

The HubFlow tools are our Git extension for making it as easy as possible to work with GitHub and GitFlow - you can do each HubFlow step with just one command. They're forked from Vincent's original GitFlow tools.

There are a few key differences from the original GitFlow tools:

  • The HubFlow tools default behavior is to push to / pull from remote branches all the time
  • We've added some additional commands such as 'git hf feature push', 'git hf feature submit', 'git hf hotfix pull', 'git hf hotfix push'
  • We've added a few handy brand new commands such as 'git hf update' and 'upgrade'

The HubFlow tools install additional Git commands that start with 'git hf'. You can safely install the original GitFlow and the new HubFlow tools side by side.

Why the fork + rename? Partly because we've changed the default behavior of some of the commands you'll already be familiar with if you have used the GitFlow tools before, and partly because there's been little activity on the original project for several months now. We'll be actively maintaining the HubFlow tools going forward.

Installation instructions and a complete command reference are available on one handy reference page.

Available Now On GitHub

Both the HubFlow model and the HubFlow tools are available now on GItHub if you want to use them yourself. Feedback (via GitHub issues) and pull requests is welcome.