Gitflow: Release & Hotfix

Photo By Vincent Driessen

If you are a developer, you undoubtedly use some form of version control. This is intended to be a summary of using Git in conjunction with gitflow to generate a release and understand the hotfix.

Note: if you do not yet possess the basic skills you should learn Git basics and then learn about gitflow before you continue. For a more in-depth read about gitflow, check this out.

Release

Once you become comfortable with using gitflow inevitably it will become time to release something to the wild. This is a pivot point because up until this point, you have only been in “feature development mode.” Moving forward, you will have a living something out there and at the same time have to deal with bugs as well as adding in features.

This is where gitflow shines. But it takes a little organizing and understanding of what’s going on behind the scenes: create a new branch (from develop), bump up our version number (tag it), merge to `master`, back-merge to `develop` and delete the release. All from one simple command!

The Setup

Our example repo has both a `master` and `develop` branch. We’re currently on the `develop` branch, all of our features have been tested, and we’re ready to release. The first thing we want to do is to make sure we know what version we want to release. If you are a team of one then you probably already know what version you are on. However, more often than not you are part of a team. We want to find out what tags we have and we want to make sure we’re up to date:

$ git fetch --tags
$ git tag -l
...
0.2.7
0.2.8
0.2.9
1.0
1.0.1

From the above, we can glean that we should probably go with 1.0.2 (or 1.1 or 2.0 — depending on what you’re releasing) for this release*.

$ git flow release start 1.0.2
Switched to a new branch ‘release/1.0.2’
Summary of actions:
- A new branch ‘release/1.0.2’ was created, based on ‘develop’
- You are now on branch ‘release/1.0.2’
Follow-up actions:
- Bump the version number now!
- Start committing last-minute fixes in preparing your release
- When done, run:
git flow release finish ‘1.0.2’

The first thing we want to do is to “Bump the version number now!” Right, where does this happen? Well, the README file is a good place. We should see a “History”, “Versions” or “Releases” section that has all the previous releases with details of each with the date of the release.

Once we’ve added our version number we will want to tell Git what we’ve done:

git commit -am "Bumped version number to 1.0.2"

From here you will want to build your project/do any last minute fixes to prepare your release. Important: No feature development at this point. Once you’re all done, commit your files to get the `develop` branch ready for the release.

Finish It!

Once you are ready to release you will issue the command (see below) which will prompt you to insert 3 messages into the commits: one for each branch and one for the tags — so be prepared.

In my case, I default to vim and for both the `master` and `develop` branches I can default to the pre-populated message by hitting `:wq` to write and quit vim for that message. In the case of the tags, you will have to actually write a message. Again, using vim you enter ‘insert’ mode by typing `i` and then adding your message followed by, `:wq` to move on. Below is the full transcript (after adding messages) for finishing a release.

$ git flow release finish 1.0.2
Switched to branch ‘develop’
Your branch is up-to-date with ‘origin/develop’.
Merge made by the ‘recursive’ strategy.
README.md | 3 +++
1 file changed, 3 insertions(+)
Deleted branch release/1.0.2 (was 67bed4a).
Summary of actions:
- Latest objects have been fetched from ‘origin’
- Release branch has been merged into ‘master’
- The release was tagged ‘1.0.2’
- Release branch has been back-merged into ‘develop’
- Release branch ‘release/1.0.2’ has been deleted

As you can see, gitflow nicely handles all the maintenance that goes along with this model. We don’t need to fetch, merge, tag, back-merge, or delete anything. My kind of tool!

Push It!

The only remaining task is to push to our remote repository. We can see that we are on `develop` (from the above transcript) so this is easy.

git push
git push origin master
git push --tags

With that, we are properly pushed, tagged, and on `develop` to start more feature development. Unless, of course, someone finds a few bugs. In which case, `hotfix` to the rescue.


Hotfix

Much like the `release` workflow, the `hotfix` is needed when you are in active development and bugs are encountered. In this case, you need to start with the current `master` (the live site), fix the bugs and merge back into `master` followed by tagging the build and back-merging the fixes to `develop`. Once again, we have a nice command that takes care of all the necessary steps.

Following our example, we know we’d want to have our version be 1.0.3 however keep in mind this can happen at any time. Please be sure that you have the current `tags` and are up to date before you start a new `hotfix`.

$ git flow hotfix start 1.0.3
Switched to a new branch ‘hotfix/1.0.3’
Summary of actions:
- A new branch ‘hotfix/1.0.3’ was created, based on ‘master’
- You are now on branch ‘hotfix/1.0.3’
Follow-up actions:
- Bump the version number now!
- Start committing your hot fixes
- When done, run:
git flow hotfix finish ‘1.0.3’

Again, you are told to “Bump the version number now!” … and you know what to do.

Finish It!

You will then squash all of your bugs and commit them at which point you’re ready to finish that hotfix. Remember, you will be adding messages to each of these just like you did above when you made the release. Below is a condensed version of the transcript (after adding messages) for finishing a hotfix.

$ git flow hotfix finish 1.0.3
Switched to branch ‘master’
Your branch is up-to-date with ‘origin/master’.
...
Merge made by the ‘recursive’ strategy.
README.md | 4 ++++
...
Merge branch ‘hotfix/1.0.3’ into develop
...
10 files changed, 4 insertions(+)
...
Switched to branch ‘develop’
Your branch is up-to-date with ‘origin/develop’.
...
Merge made by the ‘recursive’ strategy.
README.md | 4 ++++
...
Deleted branch hotfix/1.0.3 (was e096422).
Summary of actions:
- Latest objects have been fetched from ‘origin’
- Hotfix branch has been merged into ‘master’
- The hotfix was tagged ‘1.0.3’
- Hotfix branch has been back-merged into ‘develop’
- Hotfix branch ‘hotfix/1.0.3’ has been deleted

Once again, all the maintenance has been taken care of and the last task to perform is, of course, a push to our remote.

git push
git push origin master
git push --tags

There is great power in version control. Maintaining, releasing, and fixing a repository are second nature to a seasoned developer however can be intimidating to someone not used to the procedure.

But it doesn’t have to be.


Show your support

Clapping shows how much you appreciated Stephen Koch’s story.