Gitflow Workflow

The Git­flow Work­flow (we’ll call it Git­flow from here for­ward) is much more involved than the first work­flows we dis­cussed. The work­flow still uses the same set of com­mands that you’d need with the last work­flow but it nar­row­ly defines how branch­es are named and used.

Git­flow was cre­at­ed by Vin­cent Driessen and pub­lished in a wide­ly read arti­cle on his web­site in Jan­u­ary 2010.

In Git­flow, the goal is to cre­ate a sol­id soft­ware devel­op­ment work­flow that is focused on pre­dictable and sta­ble soft­ware releases. 

While Git­flow is more com­pli­cat­ed than the oth­er two work­flows, it’s still stan­dard Git; it com­pris­es most­ly of branch­ing, adding, com­mit­ting, and merging. 

Let’s review the struc­ture of Gitflow.

Branch­es Struc­ture #

The main struc­ture behind Git­flow is the branch­es set­up. Git­flow has two dif­fer­ent types of branches:

  • Main Branch­es
  • Sup­port­ing Branches

The Main Branch­es hold sacred ver­sions of the project code. The Sup­port­ing Branch­es help ensure a smooth and pre­dictable soft­ware devel­op­ment cycle. Let’s look at each a bit closer.

insert image of branch­ing setup

Main Branch­es

There are two branch­es in the Main Branch­es category: 

  • master
  • develop

We’re already famil­iar with the master branch from ear­li­er. In Git­flow, the master branch has the fol­low­ing traits:

  • always pro­duc­tion-ready, release-ready
  • every com­mit is a new release
  • no work is done in master
  • lim­it­ed options for branch­ing off master

The master branch is the ulti­mate branch of the project and should always be treat­ed as if you could ship pro­duc­tion-ready code from it at any time. It rep­re­sents the cur­rent­ly released state of your prod­uct. The master branch has a tag for each release (see more under Sup­port­ing Branch­es).

Thedevelop branch, on the oth­er hand, isn’t quite so rigid. How­ev­er, develop should only con­tain changes that are con­sid­ered ​“ready for next release.” It’s the branch from which you would cut night­ly releas­es, or use as an inte­gra­tion branch.

develop is also the source of the sup­port­ing branch­es. How­ev­er, unlike in oth­er work­flows, develop should not be used as branch in which you active­ly com­mit new changes. It’s name is con­fus­ing but it is not the branch in which you actu­al­ly devel­op new code. That respon­si­bil­i­ty lies with the Sup­port­ing Branches.

Sup­port­ing Branches

There are three types of sup­port­ing branches:

  • fea­ture branches
  • release branch­es
  • hot­fix branches

These branch­es serve as the active devel­op­ment branch­es where you add new fea­tures, make major changes, pre­pare releas­es, or quick­ly fix seri­ous bug or issues post-release.

Let’s break down each branch type since they all have a set of guide­lines on how to use them in a Git­flow project.

Fea­ture Branches

Fea­ture branch­es are where you do new work on fea­tures or oth­er changes. These branch­es are typ­i­cal­ly local-only but some ver­sions of Git­flow push all fea­ture branch­es to the ori­gin serv­er so they can be merged serv­er-side via a pull request.

Fea­ture branch­es have the fol­low­ing rules:

  • may branch from develop
  • must merge back in to develop
  • can be named any­thing you want. Com­mon nam­ing con­ven­tions are feature/the-feature-name or feature_the-feature-name

Fea­ture branch­es are where you will do your major cod­ing work. You may still need to do some work inside of the release or hot­fix branch but it should be minor changes.

Release Branch­es

The release branch­es are used to pre­pare a new soft­ware release. You may have to do some work direct­ly in this branch, if you need to update project meta­da­ta (like bump­ing a ver­sion num­ber) or oth­er small tasks that are required to get a release out the door.

Release branch­es have the fol­low­ing rules:

  • may branch from develop
  • must merge into master and develop
  • should be named accord­ing to this con­ven­tion: release-* where * is the release ver­sion num­ber. E.g. release-1.2.0

When a release is ready to go, the release branch will be merged into both master and develop. This is how you bring those branch­es up to speed with the cur­rent state of the project. 

Hot­fix Branches

Some­times after you cut a release using a release branch and merge back into master , tag the release, and dis­trib­ute the soft­ware, you find a prob­lem with the release. You need to quick­ly fix the prob­lem and cut a new ver­sion. Rather than go through the stan­dard work­flow, you would use Hot­fix branches.

Hot­fix branch­es short cir­cuit the stan­dard work­flow so you can quick­ly fix the prob­lem and release an update.

Release branch­es have the fol­low­ing rules:

  • may branch off mas­ter, via a tag for the release
  • must merge back into mas­ter and develop
  • should be treat­ed like a release branch
  • should be named accord­ing to this con­ven­tion: hotfix-* where * is the incre­ment­ed release number

Once you have com­plet­ed the work on the Hot­fix branch you merge it back into develop and then master and tag the release in master. You do not need to cre­ate a release branch since the hot­fix branch acts as a release branch.

Step-by-Step #

Let’s step through the Git­flow work­flow using our sam­ple project and show­ing the com­mands that we’d use for a typ­i­cal release cycle. This is sim­u­lat­ed and trun­cat­ed and just for demon­stra­tion pur­pos­es in this instruc­tion. Your work­flow will almost cer­tain­ly be more com­plex than what I have writ­ten here.

  1. Our devel­op­er kicks off a new soft­ware devel­op­ment cycle by cre­at­ing a new fea­ture branch off of develop. git checkout -b feature/adding-the-widget develop
  2. With her new fea­ture branch cre­at­ed and check­out out, she gets to work imple­ment­ing the new wid­get fea­ture. She com­mits her changes to the feature/adding-the-widget branch.
  3. Mean­while, her col­leagues are also work­ing on their own fea­ture branch­es, cod­ing away on their con­tri­bu­tions to the next release.
  4. Our devel­op­er is now done with her fea­ture and she alerts a co-work­er to pull her changes and do a code review. The co-work­er gives a green light and she merges the fea­ture branch into develop. git checkout develop && git pull && git merge --no-ff feature/adding-the-widget
  5. Now that the new fea­ture is in develop it will be ready for the next night­ly build and includ­ed in the next release.
  6. The release man­ag­er made a deci­sion on the date and changes in the release and is ready to cut a new release from develop. A new release branch is cre­at­ed from the develop branch. git checkout develop && git pull && git branch -b release-1.2.0
  7. The release branch is updat­ed with any last minute changes like bump­ing the ver­sion num­bers in files or meta­da­ta. When the release is ready, the release-1.2.0 branch is merged back in to devel­op: git checkout develop && git pull && git merge --no-ff release-1.2.0
  8. Then the branch is merged into master: git checkout master && git pull && git merge --no-ff release-1.2.0 and tagged as a new release: git tag -a 1.2.0
  9. After the release is in the wild, the devel­op­ers notice a crit­i­cal issue that needs to be fixed imme­di­ate­ly and includ­ed as part of a new release. They decide it’s wor­thy of a hot­fix. They cre­ate a hot­fix branch off of master. git checkout -b hotfix-1.2.1 master They make the nec­es­sary changes and com­mit them: git commit -a -m "Hotfix 1.2.1 changes
  10. Once the crit­i­cal hot fix­es are done, the hotfix-1.2.1 branch is merged into develop: git checkout develop && git merge --no-ff hotfix-1.2.1 and master: git checkout master && git merge --no-ff hotfix-1.2.1
  11. From master a new release is tagged: git tag -a v1.2.1.

At this point the sup­port­ing branch­es that were cre­at­ed in the cycle can be delet­ed since they are all safe­ly part of the both master and develop.