Gitflow

Internal

• Git
• Trunk-Based Development
• GitHub Flow
• Semantic Versioning

Subjects

• Concepts
• Operations

TO REFACTOR EVERYTHING BELOW THIS

Overview

git-flow defines a branching model that is tightly coupled with the project release cycle. This model is suited for projects that have a scheduled release cycle.

git-flow comes with a well-defined set of branches, where each branch (or each branch type) has a specific role:

• The master branch stores the official release history. The master contains the abridged history of the project, unlike develop, which contains the complete history.
• The develop branch serves as integration branch for features. This branch contains the complete history of the project.
• Feature branches serve to develop features. Each feature should reside on its own branch. The feature branches branch off develop, not master. When a feature is complete, the corresponding feature branch is merged back into develop. Features should never interact directly with master.
• Release branches host release preparation development. Once develop contains enough features for a release, or the schedule release date is approaching, a new release branch is forked off develop. The creation of the release branch starts the release cycle: no new features can be added after this point, only bug fixes, documentation and other release-related content. Once the release work is finalized: 1) the release branch is merged into the master and tagged with a release number and 2) the release branch is merged back into develop. Merging the release branch back into develop is critical because important updates may have been added to the release branch during the release process and we want those into the main development state. Having a dedicated release branch facilitates communication regarding the specific release: "we're preparing version 7.7". After release and merging, the release branch should be deleted.
• Hotfix (or "maintenance") branches. See:

Hotfix

git-flow is a merge-based solution. It does not rebase feature branches.

git-flow is supported by a toolset that can be installed, and which provides specialized command line extensions.

Installation

Mac

brew install git-flow-avh

Operations

git-flow-Enabling a Repository

If you intend to use 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 <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 <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/<feature_branch_1>
git branch --set-upstream-to=origin/feature/<feature_branch_1> feature/<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/<feature_branch_1>
git merge develop

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

git flow feature finish <feature_branch_1>

The command will checkout the develop branch and merge <feature_branch_1> into it, then will delete the feature branch. The equivalent base commands:

git checkout develop
git merge <feature_branch_1>

Release

Start the Release Process (Making the Release Branch)

git flow release start 0.1.0

Manual commands:

?

Finish a Release

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

Manual:

?

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 <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 '<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.