How to setup your Altium project on git
Overview
Need a way to organize or collaborate on your schematic, PCB, and supporting files? 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. Either to back up your work, collaborate on a design, and/or segment and catalog 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 setup 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.
Curious about some of the other ways AllSpice can improve your hardware development? Let us know below so we can tackle them in a future post, or send us an email at info@allspice.io.
Kyle is an experienced electrical engineer with 10 years of experience launching mass-production consumer products. He holds a B.S. in Electrical Engineering from Northeastern and an M.S. in Engineering and an MBA from Harvard. Driven by his passion for innovation in hardware development and his big-picture mindset, Kyle co-founded AllSpice in 2020.
