How does SimpleGitVersion work?

Git Basics

CSemVer (http://csemver.org) can be applied to Git repository: this is the goal of the SimpleGitVersion project. To understand it, try to forget the Git branches and consider the basics of Git:

• A commit point has a ‘content’: its ‘File tree’ is our ‘base of code’.
• A commit can have tags: in our case, when a commit is tagged with ‘v4.5.0-rc.2’ this means that the ‘File tree’ of this commit contains and defines everything we need to build this exact version of our product/artifact.
• Tags are unique across the repository: there can be only one commit tagged with ‘v4.5.0-rc.2’.
• More than one commits can contain identical File trees and this is easy to detect: these File trees share the same SHA1 that we call ContentSHA.
• A commit point is either:
  • An orphan (the initial commit in ‘master’ commit for instance)
  • Based on one commit: it carries the differences between itself and its Parent.
  • Based on 2 (or more) commits: it merges its 2 (or more) Parents’ File tree into one File tree.
• There can not be cycles in the graph. This is a classic DAG.

This is our playground for Git, no more no less. You may wonder where the branches are in this picture. We don’t use branches. Of course, branches help, they are important to organize the repository (and the work), but we consider them to live at a higher level of organization.

We are claiming that proper versioning can, and should, be achieved by considering only the commits and the topology of the repository.

The algorithm

SimpleGitVersion can compute two sets of versions for any commit C in the repository. The first step is to compute the Base Version of C:

• Considering P(C), all the parent commits of C.
• Computes the Base Version Bv of C based on:
  • Tc = The greatest Version Tag that appears in P(C).
  • Cc = The greatest Version Tag that appears on the commits' file tree (ie. considering the ContentSHA) in P(C).
  • 0v = The special no-version Tag (its successors are the Very First Possible Versions).
  • Base Version is:
    • Bv = Max(Tc, Cc)
    • Bv = {0v} when there is no Tc nor Cc.

Based on this Base Version, two sets of versions are computed for C:

• PossibleVersions: The versions that are valid for C regardless of any current Tag on C itself.
• NextPossibleVersions: The versions that may appear on any future commits based on C.

The algorithm itself (C#)

Go to code, the TagCollector does the job:

https://github.com/SimpleGitVersion/SGV-Net/tree/master/SimpleGitVersion.Core/TagCollector