How to automatically tag a Git repository using NodeJs, CoffeeScript and Cake

If you have worked in a project that have several developers and several repositories, then you know that tagging can be pretty annoying.

Indeed to tag a repository you need to know two things: The latest version of your application and whether the new version contains bug fixes, new features or things that would break the backward compatibility (If following a Semantic Versioning based on MAJOR.MINOR.PATCH).

The purpose of this tutorial is to be able via a Cakefile to tag a repository using a simple task, without knowing the number of the latest version of your application.

Get this tutorial source code from GitHub

What is a Cakefile?

CoffeeScript includes a (very) simple build system similar to Make and Rake. Naturally, it’s called Cake, and is used for the tasks that build and test the CoffeeScript language itself. Tasks are defined in a file named Cakefile, and can be invoked by running cake [task] from within the directory. To print a list of all the tasks and options, just type cake.

What is Semantic Versioning?

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.

This is not a new or revolutionary idea, but by giving a name and clear definition of the above concept we ensure that the Software user is aware of your intentions.

Prerequisite

This tutorial requires several prerequisite in order to be completed successfully:

  • NodeJs must be installed
  • CoffeeScript must be installed

If those requirements are not fulfilled yet, I invite you to read a post I wrote: How to install Node.js, CoffeeScript, LESS and Uglify-js on Ubuntu

Let’s get started!

Create the needed files

For this tutorial purpose we need only two files:

Cakefile
Contains the tasks to tag the Git repository and all the logic behind it.
version
Contains the latest version of your application
If you are using Unix a simple mkdir Cakefile version would do. If you are on Windows please note that those files do not have any extension (.something) and therefore you are on our own…

Leave the Cakefile empty for now and add a line containing your application latest version (or 1.0.0) within the version file like this.

Add NodeJs packages

We will only need two NodeJs packages, the File System (fs) to read and write the version file and the Child Process (child_process) to execute command lines for us (e.g: git tag -a v2.0.1). Add the below lines to your Cakefile:

# Required packages
fs      = require 'fs'
{spawn}	= require 'child_process'

Create empty tasks

We want to be able to increase the Major, the Minor or the Patch

###
TASKS
###
task 'tag.major', 'Major tag incrementation', ->

task 'tag.minor', 'Minor tag incrementation', ->

task 'tag.patch', 'Patch tag incrementation', ->

To make sure your new tasks are referenced try to run the cake command:

$ cake
Cakefile defines the following tasks:
cake tag.major            # Major tag incrementation
cake tag.minor            # Minor tag incrementation
cake tag.patch            # Patch tag incrementation

Create the methods

Our Cakefile will need four methods to be able to tag a Git repository:

tag()
The entry point method to tag repository.
run()
Execute commands.
getVersion()
Reads the version saved within the version file.
getIncreasedVersion()
Get the current version via the getVersion method and increase the major, minor or the patch.

run(cmd, args, successCallback)

The run method is pretty generic and allow us to execute wathever command needed via the spawn object. It has three parameters:

cmd
[string] The command, in our case “Git”
args
[array] The arguments, options used with the command.
successCallback
[function] Ran once the command is successfully executed.
run = (cmd, args, successCallback) ->
	# Execute the command
	child = spawn cmd, args

	# Listen to exit event
	child.on 'exit', (code) ->
		# Success
		if !code
			successCallback()

	# Listen to errors
	child.stderr.on 'data', (data) ->
		console.log 'Oups something wrong happened: ' + data

getVersion()

Reads the version saved within the version file via the NodeJs File System. It has no parameter.

# define the version file name
versionFile = 'version'
getVersion = ->
	"#{fs.readFileSync versionFile}"

getIncreasedVersion(label)

Get the current version and increase it. It has only one parameter:

label
[string] Could be: major | minor | patch
getIncreasedVersion = (label) ->
	v = getVersion()
	vSplitted = v.split('.');
	switch label
		when "major"
			vSplitted[0] = parseInt(vSplitted[0]) + 1
			vSplitted[1] = 0
			vSplitted[2] = 0
		when "minor"
			vSplitted[1] = parseInt(vSplitted[1]) + 1
			vSplitted[2] = 0
		when "patch"
			vSplitted[2] = parseInt(vSplitted[2]) + 1
	vSplitted.join('.');

tag(version)

The tag method calls the run() method with the appropriate parameters. It has only one parameter:

version
[string] The version in which you want your Git repository to be tagged.
tag = (version) ->
	run 'git', ['tag', '-a', '-m', ""Version #{version}"", version], () ->
		# Save the new version within the version file if success
		fs.writeFileSync versionFile, version

Populate tasks

Update the tasks by adding a call to the tag method.

###
TASKS
###
task 'tag.major', 'Major tag incrementation', ->
	tag getIncreasedVersion 'major'

task 'tag.minor', 'Minor tag incrementation', ->
	tag getIncreasedVersion 'minor'

task 'tag.patch', 'Patch tag incrementation', ->
	tag getIncreasedVersion 'patch'

Make a release!

Everything is now ready to execute our tasks. Let’s try shall we!

Release a Patch

$ cake tag.patch
Increasing from 1.0.0 to 1.0.1...
command used: git tag -a -m "Version 1.0.1" 1.0.1

Release a Minor

$ cake tag.minor
Increasing from 1.0.1 to 1.1.0...
command used: git tag -a -m "Version 1.1.0" 1.1.0

Release a Major

$ cake tag.major
Increasing from 1.1.0 to 2.0.0...
command used: git tag -a -m "Version 2.0.0" 2.0.0

In a next post I will continue working with this Cakefile and explain how to make a complete release of code (Minification, Packaging and Tagging). This tutorial is now finished, let me know if you liked it or not by commenting 🙂

Get this tutorial source code from GitHub

Sources