Git for Open Hardware Projects

Git has become the predominant version control software in Free and Open Source Software projects and communities. Git is excellent for tracking and managing changes to computer files and is especially powerful in managing source code. Although not as common, Git is also a worthy tool for managing the source of your hardware projects. It provides a clear time line of changes, log of contributors, and a system of synchronous development.

Git has become the predominant version control software in Free and Open Source Software projects and communities. Git is excellent for tracking and managing changes to computer files and is especially powerful in managing source code. Although not as common, Git is also a worthy tool for managing the source of your hardware projects. It provides a clear time line of changes, log of contributors, and a system of synchronous development.

The most basic explanation of Git is that it tracks snapshots of your source files. In Git, those snapshots are called commits. See the Getting Started chapter on git-scm.com for a more detailed explanation of how Git works and further documentation on using Git. Tutorials and courses on basic use of Git are available in a number of places so it is not covered here. Check out git-scm.com, Learn Git in 20 Minutes video, github.io resources, and Codecademy course to list a few to get you started.

Licensing

Once you have a basic understanding of Git and have started the repository for your project the next thing you should consider is licensing. If you plan to share your hardware project source for collaboration or to provide to customers, defining a clear Open Hardware license should be considered early on. Common practice is to place the license of your project in a LICENSE or COPYING file in your project source.

Which license you choose largely depends on the intentions of your project. There are a number of copy-left and permissive licenses to choose from including Creative Commons, TAPR OHL, CERN OHL, and GPL. However, it should be noted that these licenses cover the source files of your project but not necessarily the functional design, as explained better by the Open Source Hardware Association and opensource.com. I am not a lawyer and the legal precedence of Open Hardware isn’t well traveled so you may want to consider speaking with a lawyer.

Git Repository Hosting

An additional advantage of using Git for Open Hardware are the available hosting options. All basic Git hosting services and software will provide a remote centralized git repository for your team or collaborators to sync to. Other common features you will find are issue tracking, project documentation, and team permission management. The three most common Git hosting services are Github, GitLab, and Bitbucket. If you prefer a self-hosted FOSS Git host, Gitea and Phabricator are great options.

Binary Files

One catch to beware of when using Git is that is doesn’t cope with binary files very well. Git has significant support for dealing with clear text software source. However, when you start committing files that are compressed or not stored in clear text, Git loses some of the useful features in tracking changes.

A problem you will run into when you commit a binary file to your Git repository is that a whole new copy is stored in the Git history. For example, if you make three commits, each with a change to the same binary file, the Git history now contains three complete copies of the binary file. If your repository contains a long history and/or many binary files the repository will grow in size quickly. Before long, every time someone needs to clone the repository they will be downloading gigabytes of data.

One way of working around this issue is to use software that generates clear text files by default. There are a number of Free and Open Source Software alternatives that are more Git friendly.

• Circuit board design: KiCad project files are all clear text.
• Graphics: Inkscape uses SVG by default which is an XML based vector image format.
• Documentation: Markdown is an easy to learn markup language to quickly generate documents. It has wide usability with software available for desktop and web.
• Documentation: LaTeX is great for large documents as it provides endless tools to automate managing documents. Note, LaTeX can be daunting and has a bit of a learning curve.
• CAD: OpenSCAD is a script based CAD software that can generate 2D paths and 3D CAD drawings.

However, the reality is that your project is likely going to require using software that stores the data in binary files. Obviously others have run into this issue as the use of Git has grown. There are a number of tools that have been developed over the years with git-lfs being one of the more recent but quickly adopted tools that help dealing with binary files in Git.

Git-lfs (lfs = large file storage) stores the binary files in a separate location outside of the Git repository, only storing the cryptographic hash of the files in the repository. When cloning a repository using git-lfs, only the version of the binary files in that commit would be downloaded. If you git checkout another commit or branch, the version of the binary files in that commit would be downloaded and replace the other version. This greatly reduces the size of repositories that use a significant amount of binary files.

All of the major Git host service providers, including Gitea, support git-lfs and will store the lfs tracked files in a separate file storage. This allows quick and simple setup for git-lfs for your next project. For more info on setting up Git LFS I’ve written a guide on how to Start with Git Large File Storage.

Have anything to add, corrections, suggestions? @stabadie or dm me on Twitter.