Using git-flow to automate your git branching workflow

Vincent Driessen’s “git flow” branching model is a git branching and release management workflow that helps developers keep track of features, hotfixes, and releases in bigger software projects. This workflow involves many commands to type and remember. The git-flow library of git subcommands can help by automating some parts of the flow to make working with it easier.

The "git flow" branching model

After installing git-flow1, use the init command to start using git-flow in a repository. To create a new repository, run git flow init in an empty directory:

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 a wrapper around existing git commands, so the init command does not change anything in your repository other than creating branches. To stop using git-flow in a project, stop using the git-flow commands. There’s nothing to change or remove.

After setting up, git-flow automatically switches to a newly created branch named develop:

git branch
* develop
  master

The develop branch is the default branch for development, while the master branch is kept in sync with production.

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

Git-flow created a feature branch and automatically switched the current branch. Implement your feature in this branch while using git like you normally would.

When the feature is done, 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 prevent losing historical information about your feature branch before it is removed.

Versioned releases

Git-flow uses release branches to start a new branch when preparing to deploy a new version to production.

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. Any last-minute fixes are merged into the master and develop branches.

Then, to finish the release, use git flow release finish:

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

Git-flow pulls from the repository’s origin, merges the release branch into master, tags the release and merges everything back into develop before removing the release branch.

After the release is merged into the master and develop branches, git-flow switches to the master branch, which is now ready for deploy.

Hotfixing production code

Because the master branch remains in sync with production, git-flow creates hotfix branches by branching out from the master 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 like release branches, but they are based on the master branch instead of develop. When you’re done, use hotfix finish to merge the hotfix branch:

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.


  1. On a mac, use Homebrew:

    brew install git-flow
    

    Otherwise, follow the instructions.

    ↩︎