Skip to main content

Git-flow adapted for GitHub

Project description

Flowhub translates the workflow implemented by the excellent git-flow Git add-on to GitHub.

Scott Chacon (of GitHub fame) points out that sometimes git-flow isn’t the best workflow for an agile team. Flowhub is cool with that, too - setting the options one way gives you a translation of git-flow, and setting them a slightly different way gives you a translation of GitHub Flow.

You can also get a hybrid of the two, if that floats your boat.

Flowhub has no meaning outside of a Git repository.

After installing, you’ll have access to the flowhub command:

flowhub init
# blah blah
flowhub feature start <name-of-feature>

See flowhub -h and its descendants for more information.

What Can Flowhub Do?

Flowhub keeps groups working in an orderly fashion, with minimal intrusion.

For Developers

Let’s examine a common use-case: you’ve forked another repository on GitHub (totally coincidentally, this happens to be the case that Flowhub was written for - though it doesn’t require this set up).


Suzy has forked a fellow developer’s repository, and already has a clone of it on her development box. She wants to keep her contributions orderly, and (luckily!) the original repository adheres to a single-stable/single-dev branching philosophy already (Flowhub doesn’t require this, but it makes things easier).

Suzy decides to use Flowhub (she’s got a bright future).

cd /path/to/my/clone
flowhub init

After answering all of Flowhub’s questions, Suzy is ready to start working (she decided to keep all of Flowhub’s defaults).

feature start

She’s already got some ideas about how to improve the project:

flowhub feature start suzy-feature-the-first
Password for '':

Summary of actions:
 - New branch feature/suzy-feature-the-first, from branch develop
 - Checked out branch feature/suzy-feature-the-first

She’s also come up with a solution to an existing issue:

flowhub feature start -i 13 i-know-the-answer
Password for '':

Summary of actions:
 - New branch feature/13-i-know-the-answer, from branch develop
 - Checked out branch feature/13-i-know-the-answer

When she’s ready to publish, that branch will be tied to issue #13 on canon.

feature publish

After Suzy’s been working for a while, she decides it’s time to get some feedback from the original repository. Flowhub makes this a cakewalk.

flowhub feature publish # Since Suzy is still on her feature branch, Flowhub assumes that's the one to publish

Flowhub creates a pull-request for her, and reports the url so she can quickly navigate to it.

When she’s gotten some feedback and addressed it, she runs the same command. Flowhub updates the pull-request for her.

feature abandon/accepted

When her pull-request has been accepted, Suzy can run

flowhub feature accepted

Summary of actions:
 - Latest objects fetched from canon
 - Updated develop
 - Deleted feature/accepted-feature from local repository
 - Deleted feature/accepted-feature from origin
 - Checked out branch develop

from her feature branch, and Flowhub will clean things up a bit. She can also specify a feature name, if she’s not currently on the accepted branch.

If Suzy’s feature is deemed a non-starter, and summarily rejected, Flowhub is there to comfort her:

flowhub feature abandon

Summary of actions:
 - Deleted feature/abandoned-feature from local repository
 - Deleted feature/accepted-feature from origin
 - Checked out branch develop

Which will remove the feature branch she’d been working on.

The difference between accepted and abandon is that accepted will complain if the feature branch hasn’t been fully merged into your trunk branch; abandon doesn’t care.

feature list

At any time, Suzy can get a list of her current features’ names (she’s been so prolific that she’s lost track of them all).

flowhub feature list
* suzy-currently-checkedout-feature
  # ...

release/hotfix contribute

When it’s time for a release, Flowhub has your back as well. Just branch off the tip of the release, and work. When you’re satisfied, run the release contribute command while that branch is checked out:

flowhub release contribute

It’s very similar to the feature publish command, but the target of the pull-request is the release branch, not the trunk.

hotfix contribute does the same thing, but for hotfixes.

Both contribute commands won’t allow you to contribute branches that aren’t descended from release/hotfix branch (as appropriate).

For Managers

After a while, Suzy is given push access to the original repository (the maintainer cited her excellent branch organization as a key reason for the promotion).

Now Suzy can make use of Flowhub’s managerial commands.

A milestone has been reached in her project, and it’s time to get ready to release a new version (Suzy’s repository is a good fit for git-flow - if Github-flow were a better match for her, she wouldn’t need the managerial commands at all).

flowhub release start 0.3 # or whatever you want to tag the release as

Summary of actions:
 - New branch release/0.3 created, from branch develop
 - Pushed branch release/0.3 to canon
 - Checked out branch release/0.3

Bump the release version now!

this creates a new branch, off of develop, and sends it to github so that other developers can start dotting i’s and crossing t’s. Flowhub will only allow one release branch at a time.

When the release is polished to Suzy’s satisfaction, she publishes the release:

flowhub release publish # Suzy is on the release she wants to publish; she could also name it here.
Message for this tag (0.3): Lotta cool stuff here!

Summary of actions:
 - Latest objects fetched from canon
 - Branch release/0.3 merged into master
 - New tag (0.3:"Lotta cool stuf here!") created at master's tip
 - Branch release/0.3 merged into develop
 - master, develop, and tags have been pushed to canon
 - Branch release/0.3 removed
 - Checked out branch develop

A few days later, Suzy notices that a rare but seriously bad bug snuck through testing, and is affecting users. Suzy doesn’t panic - she has Flowhub:

flowhub hotfix start 0.3.1

Summary of actions:
 - Latest objects fetched from canon
 - Updated master
 - New branch hotfix/0.3.1 created, from branch master
 - Pushed hotfix/0.3.1 to canon
 - Checked out branch hotfix/0.3.1

Bump the release version now!

Just like releases, Flowhub will only let you have one hotfix branch going at a time.

When the bug’s been killed, Suzy runs

flowhub hotfix publish
Message for this tag (0.3.1): Sorry, guys.

Summary of actions:
 - Branch hotfix/0.3.1 merged into master
 - New tag (0.3.1:"Sorry, guys.") created at master's tip
 - Branch hotfix/0.3.1 merged into develop
 - master, develop and tags have been pushed to canon
 - Branch hotfix/0.3.1 removed
 - Checked out branch develop

If Suzy had been running a release branch at the time, the hotfix would have been merged into that instead of her trunk; the bug would have been killed in trunk when the release was published.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for flowhub, version 0.4.5
Filename, size File type Python version Upload date Hashes
Filename, size flowhub-0.4.5.tar.gz (15.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page