Gitflow release branch process from start to finish example

The Gitflow release branch has the shortest lifespan of all the Gitflow branches. It is only created when the develop branch is feature complete, and it is merged with the master branch once final testing is done. The Gitflow release branch is then deleted and focus goes back to development and hotfixes.

Feature completeness is typically determined by the stakeholders of the project. It often maps to an Agile epic and is associated with a set of features defined by milestones established at the outset of the project.

Software projects will have several, if not hundreds, of releases throughout their lifecycle. The JDK has two releases a year. Smaller projects may have releases every month. Older, stable projects may not have any releases for decades.

No new development is allowed to happen on the Gitflow release branch. Once created, the only commits made to this branch should be for bug fixes and urgently necessary chores. No feature development is allowed.

Release and bugfix branches

The topic branches created off the release branch to deal with issues are known as bugfix branches. Gitflow bugfix branches only interact with the release branch. The Gitflow bugfix branch should not be confused with the hotfix branch which interacts exclusively with the master branch.

When all of the bugs discovered in the final test cycles are fixed, the release branch is dually merged into both master and development branches.

The merge into master is then tagged and promoted as a publicly available release.

A separate merge of the Gitflow release branch into the develop branch is also required. This ensures that any fixes made to the release after the initial branching make it back into development.

The Gitflow release branch is made from the develop branch and gets merged into both master and develop when finished.

Gitflow release branch vs. hotfix

Release and hotfix are the only two Gitflow branches that get merged directly into master. But the key difference is that release branches are created off the development branch, while hotfix branches are created directly off the master/main branch.

Gitflow release branch process

The following set of commands takes you through the Gitflow release branch process lifecycle.

To work with the release branch, first initialize a Gitflow repository.

$ git flow init
Initialized empty Git repository in C:/_tools/temp/.git/

Only two branches exist after initialization, and there are no tags.

$ git branch -a
* develop
master

$ git tag -l

Create a feature branch to represent some work that will make the project feature complete. Notice this adds a new branch named “feature/feature_branch.”

$ git flow feature start feature_branch
Switched to a new branch 'feature/feature_branch'

$ git branch -a
develop
* feature/feature_branch
master

When the feature is finished, the feature branch is deleted.

$ git flow feature finish feature_branch
Switched to branch 'develop'

$ git branch -a
* develop
master

Use the “git flow release start” command to create the release branch.

$ git flow release start 0.1.0
Switched to a new branch 'release/0.1.0'

$ git branch -a
develop
master
* release/0.1.0

When the release is stable, run the “git flow release finish” command.

$ git flow release finish '0.1.0'
Already on 'master'
Deleted branch release/0.1.0 (was f9cdbf0).

After the “git flow release finish” command runs, the release branch should be deleted and a new Git tag exists in the repository.

$ git branch -a
develop
* master

$ git tag -l
0.1.0

Gitflow release branch process overview

In summary, the key features of the Gitflow release branch are:

• The release branch represents a complete feature set.
• The only commits on the release branch are for bug fixes and important chores.
• The Gitflow release branch is created off the development branch.
• Gitflow release is merged into master and also back into development.
• The release branch is the shortest lived of all Gitflow branches.

Here is what a complete GitFlow workflow looks like. This example did not include the hotfix branch.