How to Version your app with Git

Semantic Versioning

To organize your applications into versioned segments, we use Semantic Versioning aka Semver.

Here's Semver in a gist:

We version applications like so: <Major>.<Minor>.<Patch> .

Brand new projects start at 0.0.0, and every time we release new changes, we bump the version up, based off of the type of changes being released.

Following this table, we decide which version to "bump"; the example is if we are starting from version 1.2.0:

Semantic Versioning with Git

In order to apply this concept with Git, we use Git tags.

Examples

Minor bump

If your project is at version 2.1.3, and you just finished a feature that is still compatible with the project at version 2.1.3, you would do a minor version bump.

From 2.1.3 to 2.2.0:

git tag -a v2.2.0 -m 'Release version v2.2.0'

This will tag your project to version v2.2.0 based off of the last commit of the branch you are on. It will also include a message with the tag with message contents of whatever is in the quotation marks.

Push tag to remote

Next, you would push this tag to remote with

git push origin <branch name> --follow-tags

Doing this will not only push all the commits from local to remote on that branch, it will also push any tags that are local to the remote repo.

Patch bump

Now let's say you made a bug fix after tagging the project with 2.2.0 and releasing it. You would bump the version to v2.2.1 and release the fix.

From 2.2.0 to 2.2.1:

git tag -a v2.2.1 -m 'Release version v2.2.1'

git push origin <branch name> --follow-tags

Major bump

After making the bug fix, let's say you have just finished a series of large changes that is completely incompatible with the previous version (2.2.1), this qualifies for a major version bump.

From 2.2.1 to 3.0.0:

git tag -a v3.0.0 -m 'Release version v3.0.0'

git push origin <branch name> --follow-tags

Cheatsheet

# Major bump
# From v3.2.0 -> v4.0.0
git tag -a v4.0.0 -m 'Release version v4.0.0'
# Minor bump
# From v3.2.1 -> v3.3.0
git tag -a v3.3.0 -m 'Release version v3.3.0'
# Patch bump
# From v3.2.0 -> v3.2.1
git tag -a v3.2.1 -m 'Release version v3.2.1'

Notice in addition to increasing the version number, how minor bumps reset the patch versions to zero, and major bumps reset the minor and patch versions to zero.

And that's it!

The idea is every time you want to create a new release based off of the changes you made before the previous release, you bump the version according to the rules of semver and tag it with Git.

There is actually a whole process that incorporates semantic versioning with Git, called Gitflow that I highly recommend reading about.

With Gitflow, everytime you decide to release new features, you would tag your project according to the type of changes made when it is ready in either the release or hotfix branch. In addition, every tag represents a version of the project that exists on the master branch.

Git tags Cheatsheet

As a reference, checkout the Git tags documentation as it is very helpful.

Checking out previous tags

One very handy usecase is having the ability to go to any previous versions of your project. You could do this with git checkout.

First see all available versions/tags:

git tag

if v2.1.1 was listed and we wanted to go to that version,

git checkout v2.1.1

The repo will now show the codebase at version v2.1.1. We could always go back to where we were, for example if we were on the develop branch with git checkout develop.

Deleting tags

Locally:

git tag -d <tag-name-here>

Remotely:

git push origin --delete <tag-name-here>

Tagging commits in the past

First view all previous commits:

git log

And copy the commit hash you would like to tag, then

git tag -a <tag-name-here> <commit-hash-copied>

I hope you found this post helpful!

shaunjacks.io

Uncovering the landscape of Software Engineering and Data Science.

Subscribe

Comments