Search

How to setup your Altium project on git

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 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 3 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 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 without 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 "mono-repo" to manage entire all 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 (more on that in a future post). You can link together assemblies using git submodules (another topic we'll follow up on in the future).



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 setup 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 like 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 some day be possible.