Using git-flow to automate your git branching workflow

Vincent Driessen’s branching model is a git branching and release management strategy that helps developers keep track of features, hotfixes and releases in bigger software projects.

This workflow has lot of commands to type and remember, so there’s also the git-flow library of git subcommands to help automate some parts of the flow to make working with it easier.

After installing git-flow (brew install git-flow), you can start using git-flow in your repository by using it’s init command. You can use it in existing projects, but let’s start a new repository:

$ git flow init

Initialized empty Git repository in ~/project/.git/

No branches exist yet. Base branches must be created now.

Branch name for production releases: [master]

Branch name for "next release" development: [develop]

How to name your supporting branch prefixes?

Feature branches? [feature/]

Release branches? [release/]

Hotfix branches? [hotfix/]

Support branches? [support/]

Version tag prefix? []

git-flow is just a wrapper around existing git commands, so the init command doesn’t change anything in your repository other than creating branches for you.

If you don’t want to use git-flow anymore, there’s nothing to change or remove, you just stop using the git-flow commands.

If you run git branch after setting up, you’ll notice that you switched from the master branch to a new one named develop.

$ git branch

* develop

  master

The develop branch the default branch where most of the work will happen, and the master branch keeps track of production-ready code.

Feature branches

git-flow makes it easy to work on multiple features at the same time by using feature branches.

To start one, use feature start with the name of your new feature (in this case, “authentication”):

$ git flow feature start authentication

Switched to a new branch 'feature/authentication'

Summary of actions:

- A new branch 'feature/authentication' was created, based on 'develop'

- You are now on branch 'feature/authentication'

Now, start committing on your feature. When done, use:

     git flow feature finish authentication

A feature branch was created and you’re automatically switched to it.

Implement your feature in this branch while using git like you normally would.

When you’re finished, use feature finish:　　

$ git flow feature finish authentication

Switched to branch 'develop'

Updating 9060376..00bafe4

Fast-forward

 authentication.txt | 1 +

 1 file changed, 1 insertion(+)

 create mode 100644 authentication.txt

Deleted branch feature/authentication (was 00bafe4).

Summary of actions:

- The feature branch 'feature/authentication' was merged into 'develop'

- Feature branch 'feature/authentication' has been removed

- You are now on branch 'develop'

Your feature branch will be merged and you’re taken back to your develop branch.

Internally, git-flow used git merge --no-ff feature/authentication to make sure you don’t lose any historical information about your feature branch before it is removed.

Versioned releases

If you need tagged and versioned releases, you can use git-flow’s release branches to start a new branch when you’re ready to deploy a new version to production.

Like everything else in git-flow, you don’t have to use release branches if you don’t want to.

Prefer to manually git merge --no-ff develop into master without tagging? No problem.

However, if you’re working on a versioned API or library, release branches might be really useful, and they work exactly like you’d expect:

$ git flow release start 0.1.0

Switched to a new branch 'release/0.1.0'

Summary of actions:

- A new branch 'release/0.1.0' was created, based on 'develop'

- You are now on branch 'release/0.1.0'

Follow-up actions:

- Bump the version number now!

- Start committing last-minute fixes in preparing your release

- When done, run:

     git flow release finish '0.1.0'

Bump the version number and do everything that’s required to release your project in the release branch.

I personally wouldn’t do any last minute fixes, but if you do, git-flow will make sure everything is correctly merged into both master and develop. Then, finish the release:

$ git flow release finish 0.1.0

Switched to branch 'master'

Merge made by the 'recursive' strategy.

 authentication.txt | 1 +

 1 file changed, 1 insertion(+)

 create mode 100644 authentication.txt

Deleted branch release/0.1.0 (was 1b26f7c).

Summary of actions:

- Latest objects have been fetched from 'origin'

- Release branch has been merged into 'master'

- The release was tagged '0.1.0'

- Release branch has been back-merged into 'develop'

- Release branch 'release/0.1.0' has been deleted

Boom. git-flow pulls from origin, merges the release branch into master, tags the release and back-merges everything back into develop before removing the release branch.

You’re still on master, so you can deploy before going back to your develop branch, which git-flow made sure to update with the release changes in master.

Hotfixing production code

Because you keep your master branch always in sync with the code that’s on production, you’ll be able to quickly fix any issues on production.

For example, if your assets aren’t loading on production, you’d roll back your deploy and start a hotfix branch:

$ git flow hotfix start assets

Switched to a new branch 'hotfix/assets'

Summary of actions:

- A new branch 'hotfix/assets' was created, based on 'master'

- You are now on branch 'hotfix/assets'

Follow-up actions:

- Bump the version number now!

- Start committing your hot fixes

- When done, run:

     git flow hotfix finish 'assets'

Hotfix branches are a lot like release branches, except they’re based on master instead of develop. You’re automatically switched to the new hotfix branch so you can start fixing the issue and bumping the minor version number. When you’re done, hotfix finish:

$ git flow hotfix finish assets

Switched to branch 'master'

Merge made by the 'recursive' strategy.

 assets.txt | 1 +

 1 file changed, 1 insertion(+)

 create mode 100644 assets.txt

Switched to branch 'develop'

Merge made by the 'recursive' strategy.

 assets.txt | 1 +

 1 file changed, 1 insertion(+)

 create mode 100644 assets.txt

Deleted branch hotfix/assets (was 08edb94).

Summary of actions:

- Latest objects have been fetched from 'origin'

- Hotfix branch has been merged into 'master'

- The hotfix was tagged '0.1.1'

- Hotfix branch has been back-merged into 'develop'

- Hotfix branch 'hotfix/assets' has been deleted

Like when finishing a release branch, the hotfix branch gets merged into both master and develop. The release is tagged and the hotfix branch is removed.

Why aren’t you using git-flow?

If you’re not doing versioned releases, Vincent’s git workflow and the git-flow library might not be a right fit for you. However, if you work on a project that’s semantically versioned, like a Rubygem or a versioned API, git-flow will give you a couple of simple commands that will do a lot of work under the hood, making working on features, pushing new releases and hotfixing bugs a lot easier. Well, at least on the git side.