Gitflow Operations

External

• https://danielkummer.github.io/git-flow-cheatsheet/
• https://github.com/petervanderdoes/gitflow-avh/wiki/Installation

Internal

• Gitflow

Overview

This page refers to operations with the git-flow extension, if installed. For general git-flow concepts, see Gitflow Concepts.

Installation

Mac

brew install git-flow-avh

Operations

git-flow-Enabling a Repository

If you intend to use the git-flow extension, it is mandatory to "git-flow-enable" the repository with the following command, otherwise the extension commands will complain and will refuse to work. Initialization creates the set of standard branches and branch prefixes required by the git-flow workflow.

git flow init

The command runs a questionnaire where you should select the default answers, with the exception of the "Version tag prefix", which should be "release":

Which branch should be used for bringing forth production releases?
  - develop
Branch name for production releases: [] master

Which branch should be used for integration of the "next release"?
  - develop
Branch name for "next release" development: [develop] develop

How to name your supporting branch prefixes?
Feature branches? [feature/]
Bugfix branches? [bugfix/]
Release branches? [release/]
Hotfix branches? [hotfix/]
Support branches? [support/]
Version tag prefix? [] release-
Hooks and filters directory? [/Users/ovidiu/github/some-repository/.git/hooks]

Note that any newly created branch does not have any corresponding remote branch, so if you want to establish the relationship, apply Publish a Local Branch in a Remote Repository procedure.

Feature

Create a Feature Branch

git flow feature start my-feature-branch-1

Note that the repository must be "git-flow enabled" for this to work. See git-flow-enabling a repository.

The equivalent standard commands:

git checkout develop
git checkout -b my-feature-branch-1

Note that this command does not push the newly created feature branch into the origin repository. If you wish to do so, follow:

Create the Remote Branch and Its Local Remote-Tracking Branch

and then:

Link the Local Branch to its Tracking Branch

In our case is:

git push origin feature/my-feature-branch-1
git branch --set-upstream-to=origin/feature/my-feature-branch-1 feature/my-feature-branch-1

Finish the Feature

Go to the develop branch and synchronize it with origin:

git checkout develop
git pull

Then go back to the feature branch and merge develop into it, to preemptively resolve merge conflicts:

git checkout feature/my-feature-branch-1
git merge develop

From any branch, including the feature branch being worked on (note that you can simply use "my-feature-branch-1", not "feature/my-feature-branch-1", git-flow knows what this is about:

git flow feature finish my-feature-branch-1

The command will checkout the develop branch and merge my-feature-branch-1 into it, then will delete the feature branch. The equivalent base commands:

git checkout develop
git merge my-feature-branch-1

Release

Start the Release Process (Making the Release Branch)

git flow release start 0.1.0

Finish a Release

git checkout master
git checkout merge release/0.1.0
git flow release finish ‘0.1.0’

Hotfix

A hotfix or maintenance brach carries maintenance work for functionality that was released. The results of the maintenance work are used to patch production releases. Hotfix branches are based on master. These are the only branches that fork off directly from master. As soon the fix is complete, the hotfix branch should be merged both in master and develop, or the current release branch, if there’s one in progress, and master should be tagged with an update release number. Hotfix (maintenance) branches can be thought of as ad-hoc release branches that work directly with master.

Start a Hotfix

The repository must be "git-flow enabled" to be able to start a hotfix with git flow. See git-flow-enabling a repository.

Check the Hotfix Branch Root Commit

Logically, a hotfix branch should be rooted in the master branch commit that was released. Since theoretically it should be no activity on the master after release, that commit should be the HEAD of the branch. This can be checked with:

git checkout master
git log

The HEAD commit should have a "release ..." log entry.

Start the Hotfix Branch

To start the hotfix, use the following command ("hotfix/" prefix does NOT need to specified, git-flow will append it):

git flow hotfix start my-hotfix-branch-1

Example:

git flow hotfix start update-creditlimit-fix

Note that this command does not push the newly created feature branch into the origin repository. If you wish to do so, follow:

Create the Remote Branch and Its Local Remote-Tracking Branch

and then:

Link the Local Branch to its Tracking Branch

Increment the Version

For a Gradle project, the version is conventionally maintained in gradle.properties. The version should be incremented at this stage. We get a dot version, since we're on a hotfix version, we should increment the patch component and temporarily (until we figure out what is broken) mark it SNAPSHOT

version=1.3.0

should become:

version=1.3.1-SNAPSHOT

Finish the Hotfix

Insure Tests Pass

Wrap up work, increment all dependencies, if necessary, and make sure all tests pass on the hotfix branch, locally and on the remote build server, if any.

Set the Dot Release Version

On the hotfix branch, remove the -SNAPSHOT postfix and set the correct dot release version:

version=1.3.1-SNAPSHOT

should become:

version=1.3.1

then:

git add .
git commit -m "release $(grep '^version=' ./gradle.properties | sed -e 's/^.*=//')"
git push

Finish the Hotfix Branch

The "hotfix/" prefix is not needed, git flow knows to prepend it automatically.

git flow hotfix finish my-hotfix-branch-1

Example:

git flow hotfix finish 'update-creditlimit-fix'

During the process, provide a message for the tag that will be generated for the hot fix merge. If the tag is not provided, the "finish" procedure will fail.

The finish procedure will automatically attempt to merge the hotfix branch into both "master" and "develop" and will locally delete the hotfix branch.

If there are conflicts, resolve them on both branches.