Overview

Need to organize schematic, PCB and supporting files? Here are some ways to do so more easily by setting up your Altium project on Git.

Git may be ubiquitous in the software world, but it is also rapidly growing in popularity for electronics design. In this article, I’ll show you how Git can be set up to work for electronics files with Altium Designer, and what you can expect.

Why Git?

If you need a revision control solution but aren’t ready for a large PLM system, Git may be the right fit.

I’m assuming if you’re reading this you’ve already decided you have a need for a revision control system. Whether you are backing up your work, collaborating on a design,segmenting or cataloging your design changes over time, revision control keeps documents organized. If your project or company is too small (or too busy) to take on the effort of purchasing and maintaining a proprietary vault or PLM system, there are three major alternatives: Git, Subversion (SVN), and Mercurial. I’ll focus on Git and Subversion first since (to my knowledge) there are no major circuit designs in Mercurial.

SVN vs. Git = storage vs. speed

The biggest reason some proponents recommend SVN over Git is that checking out a design with SVN only pulls the requested version from the server to the local repository, whereas Git records the entire revision history locally. For binary files like an Altium schematic or PCB doc, this can mean the repository could grow rather large if that file is changed repeatedly. However, we tend to find that as long as there aren’t any embedded images in a schematic or 3D step models in a PCB, the repo size is still quite reasonable. For instance, a typical Altium schematic file is about 300KB. If this design is committed (checked in) 100 times over the life of a design, the repository is going to be ~30MB. PCBs are slightly larger. Archimajor, a fairly complex Altium design, with 11 schematic pages and 176 commits runs about 450MB.

On the plus side, once you have the entire history in Git, synchronizing is quite fast. Because only modified files are checked in and out, and since the whole branch history is synced locally, it’s fast and easy to hop back and forth between versions. To combat the size of large binary files, Git LFS has been designed to help.

Steps to set up an ECAD project on Git

1. Create a Git repository

This can be in GitHub, GitLab, Bitbucket, or any other Git hosting service of your choice. I haven’t found any strong reason to prefer one vs. another specifically for hardware designs. If your company is already using Git, you can work with the software team to create a repository for EE files within the same organization.

Note on organizing repositories:

Although some companies use a single “monorepo” to manage entire PCBAs in a product or even their entire EE PCBA catalog, I find that it’s typically best to create an individual repository for each PCBA, and a separate repo for component libraries if you will be managing those in Git as well. You can link together assemblies using Git submodules.

2. Initialize a .gitignore

A .gitignore file tells Git to not track and store certain types of files. In the case of an Altium project, this applies to temporary, auto-generated, and most build/exported files. To create a .gitignore file, create a new text file named just `.gitignore` and include the directories and extensions you wish not to track. Save the file in the top-level directory, where the .git file is.

Here’s an example .gitignore we use with AllSpice:

3. Make your first commit

Now that you’re set up, you should be able to follow many standard guides for using Git, if you’re already familiar with the syntax.

What you can/can’t do with Git for ECAD projects

After you set up a project in Git, you’ll be able to rev control your designs software-style, but there are still some limitations that come with ECAD file types.

CAN: add + commit

You can add and commit revisions normally as you would code.

CAN: diff

Base Git does not support diff for ECAD files. You can, however, diff with AllSpice.

CAN’T: branch + merge

In an ideal world, you and a coworker would be able to work on the same design, each on your own computer, and then at the end upload the two independent revisions and merge the changes. This ideal world is, unfortunately, far away. ECAD files are too complex and have too many dependencies to allow for it. We dream this may someday be possible.