# Version control systems for hardware projects?

What are some of the good versioning systems for hardware projects? Is there equivalents of Google Code, CVS and SVN? Are such version control systems suitable for hardware projects involving PCB files, schematics..(even firmware code)?

• Great question! Would love to see some repository examples included in answers. – tyblu Jan 8 '11 at 23:10
• +1 For recognizing that the HW projects could benefit from source control. The guys I work with seem to have a tough time realizing this. – Nate May 26 '11 at 18:06
• I've been using Mercurial to version circuit boards for a while now, and it's saved my butt a couple times. Definitely a good idea. – Stephen Collings May 25 '12 at 17:56
• I use the gEDA suite of tools for EDA and track things in git. I recently wrote some git hooks that automatically generates .png images of any schematics or PCBs that have been modified and adds them to the commit. This allows me to take advantage of GitHub's image diff. PCB and gschem also have native diff tools that work with git that do something similar locally. My hooks are here: github.com/BenBergman/.git_hooks Example project that uses them: github.com/BenBergman/uJoypad – ben May 31 '12 at 16:15

Basically, all VCS systems can handle text & binary files gracefully. Of course you cannot merge binary ones.

So as long as you are not using obsolete things like CVS you will be good with ANY system.

• I use CVS for all my projects (software and hardware, with PCB, firmware, tools, etc.) and have no problem. Sure, CVS is obsolete, but I have 20 years of project history and no converter worked to migrate my repositories to Mercurial, or SVN. – Axeman Jan 9 '11 at 21:29
• Then a pragmatic way is simply too leave the old stuff in CVS, and then put new stuff in the new system... – Johan Jan 19 '11 at 15:14
• CVS a beautiful system when compared with the horror that is Microsoft Visual Source Safe, which I'm locked into for a project I'm working on at the moment. Blech. – Kevin Vermeer May 3 '11 at 16:19
• @Kevin Vermeer You know you are on the negative side on the scale when you are comparing two "not that nice" things with each other ;) – Johan May 26 '11 at 8:47
• @KevinVermeer, I had to use sourcesafe, the bane of the version control world. My last boss allowed complete neglect of version control because of it. – Kortuk May 26 '11 at 18:11

I've used Subversion with Altium before. It worked successfully, but at the time the lack of a diff tool made it less useful than version control is with code. I still think it was worth doing, even without diff capability.

For firmware, Subversion or Git are both great. If you haven't used Git before, try Subversion first (even though it will make learning Git later harder).

Altium has recently introduced a diff tool for schematics and PCBs, so I expect that Subversion would now be great, modulo the usual insanity that EDA vendors manage to build into their products.

I've been meaning to try this out with the new diff tool; if I do, I'll try to remember to post a link to the repo here as an example.

Update

I tried this out, and I have to say that I'm a little underwhelmed with the Altium diff tool. It's functional, but the changes between board revs are substantial enough that it's not that useful, at least for me. Having seen this, I've decided to forget about the diff tool and just use Github. Here's the repo if you're interested: https://github.com/rascalmicro/pcb

• Did you use the integrated SVN GUI (with Altium) or something external? – Nick T Jan 9 '11 at 2:29
• Newest Altium with SVN is great, although i'll add that PCB/schematic revisions aren't nearly as critical as they are in code. If you're dealing with more than 3-4 max schematic / PCB release revisions something probably when very wrong in the design or requirements phases. – Mark Jan 9 '11 at 2:31
• @Mark: Are you talking about the Release 10 beta, or Summer 09? – Nick T Jan 9 '11 at 2:51
• If the changes between board revs are substantial enough that it's not useful, you're not committing often enough. Commit early, commit often! Use tags to track board revs. – Kevin Vermeer Jan 10 '11 at 7:20
• I'm using SVN, and it is definitely worthwhile. My system is this: I hit the save button, I should proabably make a commit. I follow the changes by reading the commit messages like "Added part X to library" or "Added test pads to I2C and SPI busses." Releases sent out for fabrication are entirely different, use svn cp trunk/ tags/releaseX/ to take a snapshot of the release. You can then diff releaseX/file and releaseY/file if you want to see changes between releases, or you can browse the commit logs and see individual changes. Branches help modularize the flood of commits. – Kevin Vermeer Jan 10 '11 at 16:00

I use VisualSVN Server + TortoiseSVN client, and it works just fine

• If you are on windows this is a good solution. – Johan May 26 '11 at 8:48
• @Johan, if you are on linux/mac don't they come with SVN servers and clients built in? perhaps something like "sudo apt-get install subversion" should do the trick I reckon. Here's some ubuntu instructions I found with the Google: subversionary.org/howto/… – vicatcu May 27 '11 at 20:24

I use Google Code to host Super OSD, an electronics project of mine.

I exclusively use the gEDA suite to manage my schematics and PCBs. Usefully, gEDA produces text files (which are mostly human readable, although it's difficult to interpret them) for the schematics, instead of binary blobs, like Eagle. For example, this is a diff between two schematics, one about 5 days old and one I just pushed. It's not particularly useful as you can't actually see much changes in text files, but it can show relative change - i.e. massive rework, vs. single component change - and it does let you go back to prior versions.

• +1 for the use of text-based formats for files. Disk space is cheap, and compression of text is easy. I wish that binary blobs were less common. – Kevin Vermeer May 3 '11 at 16:20

Why not just use Google Code or a SVN repo? As this is a revision control system. There is no defined use for it. It is just incredibly useful for multiple developers and monitoring changes in source code.

• Have you done this? Putting binaries into SVN or Mercurial has turned out terribly for me. – tyblu Jan 8 '11 at 23:29
• No i haven't but i have used SVN for not just source code. Things Like PDFs and .txt files. – Dean Jan 8 '11 at 23:30
• @Tyblu what do you mean by terrible? I've done it with schematic and layout files and its worked great for me with subversion. – Kellenjb Jan 9 '11 at 0:20
• I can't follow changes to EAGLE files with Mercurial. It looks like the entire file is different. Do you have a repository I can peek at? – tyblu Jan 9 '11 at 0:23

The trick is to use something that works well with binaries. If you are using binaries a lot and sharing with others, it might be beneficial to implement a locking mechanism on those binary files. We've run into lots of issues with using Subversion with binary files and sharing with others that arose due to a lack of locking semantics and over-writing/merging binary files together. Adding a locking mechanism on those files removes human error in communication on who edited/changed the binary file.

If you haven't used version control before, I recommend reading up on the different ways they work, and select one to meet your needs that you and/or your team can be comfortable with. Distributed version control systems provide many benefits over client-server systems, but tend to be more complicated to work with.

Not a real version control system but Dropbox handles also revision of files an makes them available for different people on different OSes. - poor mans version control system ;)

svn, hg, and git all work just fine.

I've used Subversion with Altium before.

I do use SVN with Altium integration for schematic capture: it works well. I must say that the diff viewer is better than having nothing, because my SchDoc files are binary, ie impossible to compare otherwise! I use the SVN client integrated in Altium Designer in parallel with TortoiseSVN with no problem. Altium's client is a bit limited in terms of SVN features. I do my "tags" with Tortoise.

My opinion is based on Altium Designer 10 build 27009, and version 13.1 build 27559.

I was at the Maker Faire in San Mateo this past weekend and met some reps from a new (to me) company called Up-Verter. They are basically building an electrical CAD tool that runs in "the cloud" (i.e. in your browser) and is conceptually built around collaboration, so should deal with merge/diff and the usual versioning stuff.

I haven't tried it yet, and it looks a little bit green still (don't think you can actually do pcb layout yet, just schematics), but it's kind of intriguing. They claimed they could import Eagle files, which is a plus.

I also talked to the Eagle reps at the Element 14 tent, and they indicated that they are moving to an XML format, which is kind of a big step toward making versioning of schematics and layout more plausible... all interesting advancements on this front!

This is indeed a very good question. Since FPGAs fall into the category of "hardware", you might be interested in a version-control friendly project structure I propose for FPGA projects:

http://www.saardrimer.com/fpgaproj/

I think the ideas and concepts could easily be applies to other hardware projects, and in general. (Comments on this proposal are very welcome, btw.)

• The link isn't working anymore. – tyblu Apr 29 '12 at 9:51

Avoid git. It doesn't handle large repositories well. And your repositories will get large unless you

1. Have binary schematic files that only change somewhat when they change
2. Turn on treat binaries as text.
• Well... You should have many small repos, one repo per project. – Johan May 26 '11 at 8:49
• @Johan - ......Yeah.... Good luck with that maintenance nightmare. Anyways, I have 1 repo per client (about 4, repositories, now), with many sub-projects, and it works pretty well. SVN, at least, seems to be able to handle 5+ GB of binary data without too much trouble. – Connor Wolf May 27 '11 at 2:55
• @ConnorWolf I'd be interested to hear how you're doing that. We do one Git repository per project, and have had no problems. Not having a single repository per project sounds like a maintenance nightmare to me. – Matt Young Jul 15 '14 at 14:42
• @MattYoung - It's not a big deal. svnaccess.conf for ACL needs, and it works without major issue. And I don't have to be constantly creating new repos, which is kind of a PITA (apache mod-svn is cranky). The biggest repo DB on the server is 5.1 Gigabytes, ~930 revisions (and that's all me, too(. – Connor Wolf Jul 16 '14 at 0:40
• SVN, at least (probably git too) seems to store binary diffs, rather then complete copies of a file, so it's impressively space-efficient. – Connor Wolf Jul 16 '14 at 0:41

I've been using multiple Mercurial (HG) repos (one per project) for this but as most Version Control Systems will experience, the repos are getting larger and larger.

You should try Boar. It is designed ground-up to handle huge files and repositories. 100 GB or more of binary data is no problem.

I'd just like to add a link to HgInit, an excellent introduction to Mercurial if you decide to go that route. Personally I use Git, but they're very similar in terms of architecture (both are distributed version control systems). The distributed nature of them makes them great for working in well, "distributed" teams. :)

http://hginit.com/

• While Mercurial is a good source control system for 'pure' software projects, many of its advantages are lost on projects that deal with essentially purely binary files as it is unable to sensibly merge things. The lessons of HgInit will not make any sense unless you are only doing software. – whatsisname Jan 26 '15 at 21:44

OpenPLM seems to offer some aspects of what you are looking for although it does not seem to be in active development (http://www.openplm.org/trac/discussion/topic/93).

Maybe take a look at https://discuss.erpnext.com/t/erpnext-git-github-for-open-source-hardware-call-for-beta-user-s/18006 ("ERPNext: Git / Github for Open Source Hardware – Call For Beta User(s)")

This is worth thinking about for any ascii descriptions of hardware. Once a human readable description for the hardware is adopted any modern revision control system (RCS) works pretty well. Circuit layouts are typically fully described by Gerber files, UML describes other parts, which are fully ascii descriptions. Less standard ascii formats exist for schematics, mechanical layout and so on (KiCAD for instance).

Adoption is more a practical issue, it requires a recognized requirement for good revision control, including a meaningful diff. Which also often means giving up Word, Excel, PowerPoint, etc. A very difficult argument against managers and MBAs, but arguably regulated industries like Medical Devices, Aviation and Military already require good revision control.

As others have pointed out, most modern RCS will revision control binary files, which is very useful for archiving and identifying versions - but any electronic document management system (EDMS), Agile for instance, can assign a revision number to an arbitrary binary. Boring.

Although it is not free, and is hardly bug free, Altium vault does a sterling job; I can roll back to any commit point easily (just as any VCS should do) very easily.