What is gitflow?

Gitflow is a plugin for git that helps you build a project upon a streamlined workflow easy to follow along for other people in a team. The plugin itself is a bunch of custom commands that will help you do a bunch of stuff with git (stuff that usually would take you long or many different commands at a time) with easy to remember "one off" instructions.

Why should I use gitflow?

Well, let's say you're working on a SemVer style project where branches and releases are important or maybe a project where you might want to follow an specific achitecture style-guide, or maybe a project where you might want to have some sort of QA proccess and contribution guidelines... Then you'll benefit from using gitflow.

How do I install Gitflow?

Gitflow is avaliable on every major operating system out there, I'm using Ubuntu Linux right now so to install it here I just did:

# apt-get install git-flow

But if you're on a different O.S. the wiki has detailed instructions on the installation.

Initializing a project

To initialize a project with gitflow, we run:

$ git init

$ git flow init -d

Easy, right? the -d there is for "defaults", you can omit that parameter to customize the initialization options.

Project Branches

If we run:

$ git branch

after initializing a project using the default values, we'll see we have two branches by default, develop and master. The develop branch is where most of the "ongoing" work will be happening, while the master branch is the one for production releases. There are also other types of branches that we'll be using:

feature branches
bugfix branches
release branches
hotfix branches
support branches

Most of these branches explain their purpose with their names, ones behave different than others. I'll try my best to do the clarifications I find needed as follows:

Main Branches

Master branch

Does not receive direct commits, only merges. It only contains production facing code, and continous delivery hooks can be setup to listen changes on it for releasing versions of the codebase directly to the end user.

Develop branch

All the new features and bugfixes we develop will stem (and be aggregated) directly from/into this branch, it is basically the core of our project. As with master, usually direct commits into develop are not necessary as we are gonna be merging back into it by using the other types of branches that gitflow provides; However, as far as I could find out direct commits to develop aren't strictly discouraged by the gitflow model (unlike master's case). Hooks for our continous integration process listen to this branch usually.

Secondary Branches

Feature Branches

Stems from: Develop
Merges back into: Develop
SemVer bump: Minor

Feature branches are your "regular branch". You need to work on a new feature? then you need to use a feature branch by default. As you can see above, they stem directly from the develop branch usually and merge back into that... After this is done, your feature branch will be merged and deleted, then you'll be taken back to the develop branch.

Bugfix Branches

Stems from: Develop
Merges back into: Develop
SemVer bump: Minor

As far as I found out, they're just the same as your regular feature branch, just marked with a bugfix prefix. Consensus hasn't been reached on the default behavior for these branches (or at least it seems so) but for the moment use them as is.

Release branches

Stems from: Develop
Merges back into: Develop & Master
SemVer bump: Major

Release branches are for code that's almost ready to face the end user. Code at this stage is tested, deployed to a suitable staging environment and any issues with it are fixed directly on the respective release branch. This QA cycle continues until we're happy with the end result and then (when we finish the release) the refs are pulled from the remote and these branches are meged back into both develop and master to make sure changes made in the release aren't lost by new development. The release then gets tagged with the appropiate version number and the branch deletes itself.

Hotfix branches

Stems from: Master
Merges back into: Master & Develop
SemVer bump: Patch

Hotfix branches stem directly from master and their purpose is to fix production facing bugs. They pull the latest refs from the remote, merge back into master and develop, go and tag the hotfix and then delete themselves.

Support branches

Stems from: Master
Merges back into: Itself
SemVer bump: Minor || None

Support branches are for forking master. If you are going to develop a feature that's very specific for a client or at a certain point in time of your project then most likely you'll use support branches. Once you fork master in a support branch, it stays forked there, "frozen" at that specific point in time so you can deviate as much as you need from the original course of the project from then on (by using that branch) while also carrying the normal course of the project in the others.

After the support branch is finished, it will (take this with a grain of salt or two) merge back into itself as if you were working on a new "develop" branch, it's a new experimental feature (or at least it seems so); So use it with care.

How to use Gitflow

$ git flow [feature | bugfix | release | hotfix | support] start foobar

work and use git normally (add, commit, etc.)

$ git flow [feature | bugfix | release | hotfix | support] finish foobar

That's the simplest use of gitflow you'll see out there. However, other commands (besides start and finish) such as:

list: Lists all the branches that concide with the gitflow sentence.
publish: Push a branch into the remote
pull: Pulls a branch published by another user
track: Tracks a branch on origin

Also exist, and you may use them accordingly. You're not required to use gitflow-only commands while working, in fact you can only use start and finish, and fill the rest of your git workflow with normal git commands. Actually, there are more commands on gitflow that the ones listed here, but I could not find good documentation about all of them, these are the important ones according to the community.

The only thing to keep in mind here is that gitflow commands (although, essentially are just a bunch of git commands packed together); Can change the way your project behaves. For example, usually start commands behave like this (talking about the branch):

Encourage a manual version bump for your project
Fork the parent branch they stem from
Give advice on what to do next

While finish commands will do this (again, talking about the branch):

Pull the refs from the remote (not all cases)
Merge changes into parent branch
Tag release with version bump (not all cases)
Merge with other necessary branches (not all cases)
Delete themselves

But for example in all of this process, one thing that might differ on how you might be used to work is that all the merges that gitflow does go with a git merge --no-ff command, to prevent fast-forwarding. This is to preserve the maximum amount of historical data in the tree. According to this guy it will make your commit history a complete mess, but also the comments in his post have very valid points, take your side.

Caveats and final thoughts

PROS: It's a quick, automatic, and semi-standard way of setting up/organizing a new (or existing) project using git without any hassle.

CONS: It feels like a work in progress to me and it is awfully docummented, just to patch together this blogpost I had to read like 9 articles and watch a couple of videos. Most people use (or, correction used) a version of gitflow that only had features, releases and hotfixes (obviously development and master were there too); Other branch types are measly documented out there, as it seems gitflow is mainly the brainchild of only 1 guy, adopted by the community.

Summary: Gitflow seems cool but I think it is like coffeescript for git. I mean it does not do a lot of things in automatic for you nor it alters the syntax of git or stops playing nice with vanilla git commands but it is awfully documented and because of this, many questions arise in my head (I've yet to try it in a large team setup); Mainly about conflicts:

What happens in the case of a conflict while finishing or publishing a branch with gitflow? I mean, yeah, it's only git but should then I know what's under the hood of gitflow (what git commands does it use in each sentence and it what order) to keep the commit style clean? What other things like that should I know? I mean, my gut tells me that the help messages in the console will guide me, but so far the help messages in git flow had been dreadful explaining how to use it or what it does.

I feel that, the same time that's needed to "learn" and apply gitflow is the same time that a team would take coming up with a solid git workflow, better documented and easier to understand. That said, I see the point of using gitflow in the enterprise: You hire developers, they one day are gone and you don't want to end up with an unsupported architecture or design... Gitflow is somewhat known out there, and it's getting traction, it's a one serving git workflow for everyone.