Assembly Versioning With Git Hooks

by jmorris 6. January 2014 17:56

Source code can be found here: https://github.com/jeffrymorris/githook-version-example

Consider the scenario where you wish to base your assembly versioning off of your commit history from Git. Ideally you would want to be able to pull some information from Git regarding the commit you wish to build from, you most definitely would want this information to follow the traditional .NET versioning semantics or something similar like semver.org, and importantly you would want it to be integrated with your build process and automated. Integrated, because once you have your process in place, you probably don’t want to waste time manually changing things every time you do a build and automated, because you don’t want human fingers touching it (and perhaps making human mistakes) every on every build cycle.

Getting Commit Information from Git

Git provides a couple of different ways of getting information regarding the current state of your repository, of prominence are “git-describe”, which will show you the most recent tag that is reachable from a commit[1] and “git-rev-parse” to print out the SHA1 of a given revision.

git describe --long shows you the “nth” commit since the last tag and the shortened SHA1 of that commit. For example, given a tag created with the following command: “$ git tag -a 1.0.0 -m "1.0.0 tag", assuming that two commits have occurred since the tag was created, git-describe with the –long parameter will output: “1.0.0-2-g1089655”:

image

Where 1.0.0 is your tag, 2 is the number of commits since you created the tag, and the 1089655 is a shortened SHA1 of the last commit.

Storing Git Commit Information in your Assembly

.NET Assembly versioning is fairly well documented, in a nutshell it involves the following four values that are included within a special class in your project under the properties subfolder and compiled into the manifest of your assembly:

<major>.<minor>.<build number>.<revision>

All four values are positive integers, which separated by periods: 1.201.344.1 as an example. The .NET runtime uses this information, along with other information (say from an App.config or Web.config file) to ensure that the correct version of an assembly is loaded at runtime.

The special class mentioned previously is the AssemblyInfo.cs class and it contains a number of attributes which when compiled, make up a portion of the assembly manifest, which is a collection of static data describing how the assembly elements related to each other[2].

Of importance to this blog post are the following three attributes contained within the AssemblyInfo.cs class:

  • AssemblyVersion
  • AssemblyInformationalVersion
  • AssemblyFileVersion

For our purposes the AssemblyVersion, which contains the <major>.<minor>.<build number>.<revision> values and the AssemblyInformationalVersion, which is largely a plain-text value will be the attributes, will be what we rely on to version and provide build information to the assembly.

Post Merge Git Hooks

Within every Git repo is a folder called “.git”, by default it is not visible but it’s still accessible via the command line. The “.git” folder contains another set of folders where Git stores information related to the repository:

image

The “hooks” file is a special folder for storing, well, hooks! What are hooks? They are special snippets of code or script that is run when certain events are triggered in git. For example, there are hooks that are run when a commit occurs, after a rebase, etc. A full overview of all of the hooks can be found on the git man pages here.

We want the version information to be updated only when a build is in process and because we only want it updated when git pull happens (otherwise the validity of the version is compromised), we will use the post-merge hook. The post-merge hook fires after a successful pull and merge. This means, however, that if the local is the same as the remote, it will not fire. This is something to consider in your solution.

Creating a post-merge hook is easy: you simply create a file named “post-merge” with no file extension and place it in the .git/hooks directory. The easiest way to do this is probably by just navigating to that folder and doing a touch:

image

Once you have the post-merge file in place, Git will invoke it on every pull request or fetch which results in the local repository being updated with changes from the remote. This workflow fits well in an automated build environment.

Using the Post-Merge Hook to Update the AssemblyInfo.cs File

Once you have the post-merge hook in place you can now write some script to update the version information within your .NET project.

When Git is installed, several bash tools are also installed it. One of those is probably familiar to most Linux developers or administrators is Sed, which translated means “Stream Editor” is utility for parsing and transforming text. In this case, we will use Sed and a regular expression to find the line within the AssemblyInfo.cs file we wish to update and replace it with the updated revision information obtained via the git-describe mentioned previously.

Here is the relevant code:

image

What this does is do a git-describe with the “—always” flag, which will always return something: a shortened SHA1 of the most recent revision if a tag is not present. The script then checks the return value of the git-describe, which is stored in the variable “tag” to see if it has a git tag associated with it. If it does then it splits the value in “tag” and concatenates them into a format compatible with .NET versioning discussed previously. The result of this is stored in another variable “version” and echoed out on the next line. This variable “version” is then swapped with the previous values in the AssemblyVersion and AssemblyFileVersion attributes using a regex and Sed. Finally, the whole git-describe value stored in “tag” is swapped with the previous value of the AssemblyInformationalVersion attribute.

After building the project and right clicking on the assembly generated, this is what we see:

image

The .NET assembly version stored within the assembly manifest will also be 1.0.0.2. As previously discussed this loosely translates to the <major>.<minor>.<build>.<revision> semantics described above. Additionally, if you chose to you could base your tag structure off of semver.org’s guidelines and only use the last digit to designate a non-releasable test build (for example) based off the previous tag and the number of commits since it was created. On release builds you would specify a new tag with the last digit zero and the second to last digit one increment more than the previous or something to that affect.

References

1 https://www.kernel.org/pub/software/scm/git/docs/git-describe.html

2 http://msdn.microsoft.com/en-us/library/51ket42z%28v=vs.110%29.aspx

Tags: , ,

Visual Studio | Git | Versioning

Jeff Morris

Tag cloud

Month List

Page List