Git Tagging and Git for Hardware Development in Altium Designer

Ari Mahpour

|  Created: July 23, 2020  |  Updated: September 2, 2020

The concept of revisioning in electronics design has stayed fairly standard across the industry. A revision will typically consist of a letter and sometimes contain a number. There are many other revision schemes which people have experimented with, but, from my experience, the standard letter revision seems to be prevalent within our industry. One question that I have always asked myself is: What happened to all the revisions in between? I understand that a change in a revision letter means a release, but what about all the changes between those releases? How are those tracked?

Over time, this question has been addressed with version control systems such as CVS, Subversion, and Git. Software developers are most likely familiar with Git, but using Git for hardware development is a great way to track revisions, fork PCB projects, and release projects. These version control systems gave us the ability to view each version in between the releases. In Continuous Integration and Deployment in ECAD, we discussed the concept of releasing a new version of a project at every commit. In this article, we will review a simple, yet effective way of releasing through your Git server, but while still maintaining the linkage with your PCB’s revision letter.

Git Tagging for Your PCBs

Git Tagging is a feature in Git that enables users to designate a specific commit for a special purpose. Users will “tag” a commit to indicate its release. For example, one may tag the third commit in the repository as Revision 1.0.0, whereas ten commits later that commit may end up being tagged as Revision 1.1.0. There is no right or wrong way to use tags, but the use of Git tagging for release points is typically the primary use of this feature. 

Whether you are using Managed Projects in Altium Concord Pro, GitHub, Bitbucket, Gitlab, or any other form of Git server, they all come with the ability to tag a commit. Some Git servers have their own tagging system that can be run from their web interfaces such as GitHub and Bitbucket. For other Git servers, you can use the git-tag command from the command line. No matter how you decide to implement tagging in Git for hardware development, a team needs to create a revision naming system so that everyone understands how different versions are related to each other.

Linking Your Release to a Git Commit

As the ECAD community migrates to a version control system such as Git, it is important to maintain the linkage between Git and the release process that we are all familiar with. Many have struggled with determining the best way to keep their commits in a version control system while maintaining the freedom to put together an official package that can be sent to vendors (or sent for review at a later point in time). There are many ways to go about this. I am proposing that the release process may not be a one-size-fits-all solution, but I would recommend trying it as a baseline and then catering it towards your group’s needs.

The biggest challenge is making sense of all the Git commits and then linking that to a release package. Here is an example of what a series of Git commits look like in GitHub:

As you can see, there are many commit comments that describe design changes, and other various commits comments that proclaim an “official release.” This is prevalent among many version control system users, and it generally works. I’ve also seen users bundling release packages within the repository as well. While this may not be the cleanest solution (as it pollutes the repository with non-design files), it does seem to get the trick done.

Rather than making your official release known in a commit comment, we can leverage the concept of git tagging (or also known as “Releases” in GitHub). In this example, we have taken those official release commits and made them into releases in GitHub (which also become tags):

As you can see above, we have taken specific commits and made releases out of them. GitHub now attaches a tag to each of these commits, like so:

Finally, we can now search by release or tag in GitHub like so:

Linking Your Schematic to a Git Commit

Another way to ensure proper linkage between your PCB project and Git repository is by keeping track of the Git hash in your schematic itself. This is a little trick that John Watson showed me back when we were using Subversion. By making use of special strings, one can link their schematic (and PCB) directly to the Git commit in which they are pushing to the Git server. In this example, we’ve placed the version control string on the top-level schematic right by the title block:

As you can see above there are two versions of the Git hash depicted on the schematic: the first is the full Git hash, and the second is the shortened version (just like what is used in GitHub). To use the full-length one, I entered the following special string:

=VersionControl_ProjFolderRevNumber

If you would like to concatenate this with the title in front, you would add the following:

=’Git Hash:’ + VersionControl_ProjFolderRevNumber

At the time of this writing, however, it was discovered that this special string was too long to be concatenated. A workaround could be to set VersionControl_ProjFolderRevNumber to a shorter parameter. In this case, a parameter was created and set equal to VersionControl_ProjFolderRevNumber in the Properties Panel for this particular schematic.

Now that you have created a shortened parameter, we can manipulate the string. In this case, we want only the first 7 characters of the Git hash, just like GitHub uses when they display their Git hashes. We use the following concatenated and manipulated special string statement:

='Git Hash: ' + Copy(GitHash,1,7)

Keep in mind that any string manipulation function used comes from the Delphi language. The substring technique is a simple Copy function call from Delphi embedded into the text string. Once you or your team opens design documents from a Git release in Altium Designer, they will see the tag in the design documents, providing a concrete link back to the controlled revision.

Implementing Git for Hardware Development in Altium 365

As the industry starts using revisions in Git for hardware development, both on-premises and in the cloud, it is important to understand the connection between the official PCB design release and the actual Git commit (hash) that exists within the version control system. The concept of Git hashing and how to use this feature when releasing a PCB design project within a version control system, we can maintain this linkage and keep the two processes (or systems) in sync.

Instead of using a 3rd party version control system, you can implement Git for hardware development with Altium Designer and the Altium 365 platform. This system replaces a cloud-based Git solution for version control and allows your team to instantly import projects into Altium Designer. Alternatively, you can deploy Altium Concord Pro on-premises, giving your team a complete set of version control and data management features that integrate with Altium Designer.

Altium Designer on Altium 365 is bringing an unprecedented amount of integration to the electronics industry, which has been relegated to the world of software development, allowing designers to work from home and reach unprecedented levels of efficiency.

We have only scratched the surface of what is possible to do with Altium Designer on Altium 365. You can check the product page for a more in-depth feature description or one of the On-Demand Webinars.