Revision control concepts: Git for hardware

Git for hardware is decentralized version control for schematics, PCB layouts, BOMs and the output files generated from them. Each change lives on a branch, goes through a design review, merges after approval and ships as a tagged release. That way, every board revision traces back to the files that built it.

The hardware engineering discipline has come a long way over the last half-century. Gone are the days of taping out a PCB design and keeping designs in a physical flat-file cabinet. New solutions throughout the decades required IT staff to create and manage network locations to store designs.

Still, the maintenance and upkeep of the designs were on the honors system, and each design was only as reliable as the weakest member of the team. Even if files had an ultimate destination, they were often passed around on “sneakernet” with code reaching systems on floppy disks or thumb drives. Many engineers used informal and ad-hoc release processes where they would zip their files and tack on revision numbers whenever they forgot something and needed to add it later.

Revision control has made huge strides in the past 15 years. File repos no longer need dedicated IT employees to set up and maintain servers. Numerous providers offer turnkey solutions for revision control.

The tool most of these providers build on is Git.

Because Git started as open source, anyone can create interoperable tools. Dozens of companies offer Git platforms for you to keep your file changes. Although there are many different Git solutions with their own features added on, they all have the same fundamental functionality and basic usage set.

‍

Why hardware files need version control, not just software

Hardware files need version control because a board is built from binary source files and generated outputs that many people besides the designer depend on. Git for hardware addresses four problems that come up throughout this article:

• Binary ECAD files cannot be merged line by line, so the history has to show who changed which file and when.
• Prototype history, including white wires, flying leads and prototype firmware, has to stay traceable to a design revision.
• Generated outputs drift from their sources when they are regenerated months later or on a differently configured ECAD tool.
• Stakeholders beyond the designer, including purchasing, mechanical, test and manufacturing engineers, need to work from the same files.
  ‍

A Git workflow for hardware design files

The five steps below put the concepts in this article in order, using Git for hardware design files. For a longer walkthrough, see our Git design workflow for hardware guide.

1. Create a branch for each change

Start every bugfix, feature or experiment on its own branch off main. The main design files stay untouched while you work, and other engineers can commit to their own branches without short-term conflicts.

2. Commit schematic, layout and output files together

Make small, related commits, each with a message that says what changed. Check in the BOM, netlist and fabrication outputs at the time you generate them, so they match the source files in the same commit.

3. Open a design review

When the branch is ready, open a design review, which is what Allspice calls a pull request. Invite every stakeholder who builds from the files. Reviewers can comment, request changes or block the merge.

4. Merge after approval

Keep pushing commits to the branch to address requested changes until the review is approved. Plan merges for binary schematic and layout files before work starts, because Git cannot combine two people's edits to the same file.

5. Tag and release fabrication files

Tag the commit that marks a finished design. Then create a release from that tag and attach the production or prototype files that manufacturing will build from.

‍

Decentralized

One of the biggest changes and advantages of Git is that it is decentralized. Previous revision control software and strategies relied on a single source of truth. Centralization has certain advantages, like everyone having access to the exact same set of files and the final released files being unambiguous.

There are a lot of downsides, though. In order to make a change to a file, you either use a system with the first change to a file going through, or you need to use a checkout/check-in process. Locking files can prohibit productivity and can often prevent people from contributing their changes while someone else works on the design.

Centralized revision control also limits the types of changes you make to the design. It can be prohibitive to create an alternate design with prototype or experimental changes.

Decentralized revision control gives everyone equal footing to look at and make changes to the design. Because everyone has a copy of the design on their local filesystem, they can make whatever changes they want to the files and push them to the server when it makes the most sense. Some might think that a centralized design would create a process that is more rigorous and produces the correct intended design, but with a decentralized approach, every change must be reviewed before being merged into the design.

Users of a decentralized system push their changes to the server, and the maintainers decide which of the changes get accepted into the repository.

Decentralization may seem backward to some, but the added flexibility allows for more people to participate more frequently.

‍

Source files and output files

Modern revision control separates files into source files and output files. Source files are things like source code that compiles into an executable, which is an output file.

Firmware is no different, with source files that get compiled into an output binary file that gets uploaded to the microcontroller, microprocessor, or FPGA. With hardware designs, the source files are schematics, PCB layouts, 3D CAD files, and cable wiring harnesses, to name a few.

In a traditional software development Git repo, the only files tracked are the human-generated source files. The output files are not tracked, as the source code changes and are only attached or associated with the project upon release.

There is a very strong argument in a hardware design process to keep many of these output files in the repo. Some people think the process is source control, and only track the source files. What’s really happening is revision control, where you track the revision of the files.

It may make a lot of sense to track output files. Bills of Material (BOM) can be checked-in to run planning activities like generating cost of goods sold (COGS), as the IRS defines it in Publication 334, or finding the availability of parts or even replacements. Gerber files can be used by a mechanical engineer to determine if there is interference with fasteners, the enclosure, other PCBAs, or internal wiring.

Fabrication packages can be circulated to contract manufacturers to obtain quotes and feedback into board stack-up, blind/hidden vias, or soldering processes that require parts to be moved. Saving netlists can allow people to run automated tests or checks against the design that would have to be manually run against a 2D schematic file.

Checking in the output files also guarantees that everyone has access to the same outputs. Two different users might have their ECAD tools set up differently and generate files in a different way or with different features.

There is also the matter of re-generating output files at a later date. With software, the argument is the files can always be re-created whenever you need them, but the same engineer generating the same files months apart might include unintended changes. The best time to capture the output files is the same time they are generated.

A final argument for capturing output files is hardware prototypes differently than software. With software, you can create tests and run them, but with hardware, you need to physically make the changes to a device. If you are capturing the changes as you go, you can follow along with what happened to the PCBAs in the lab as prototype firmware, white wires, and circuits attached with flying leads are added and tested.

‍

How schematic version control tracks design changes

With Git for hardware, schematic version control turns every design change into a commit you can inspect later. Because the outputs are committed with the sources, that history covers what was built as well as what was drawn. Here is what the record holds for a single change, such as a new value for R148:

• Each commit records which schematic or PCB layout files changed, plus a message saying why, such as "Set R148 to 4.7 kΩ."
• The BOM, netlist and Gerbers are committed alongside the sources, so each output matches the source revision that produced it.
• Allspice Design Reviews show object-level visual diffs, with green for new objects, red for deleted ones and yellow for changes.
• Clicking into a change shows exactly what differed, down to attribute-level changes such as R148's value or a swapped part number.
• Reviewers comment on specific design objects, such as R148 itself, so feedback stays attached to the part it describes.
  

Commit, push, branches

With Git, your changes to the design and files are captured in commits. Each time you make small and related changes to the file, you can create a commit with a message of what happened. The changes aren’t available to anyone besides those who have access to your local filesystem.

Because Git is decentralized, the committed changes must be pushed to the repo in order for anyone else to see or use them. Commits are pushed to branches.

If you have a single branch system (which is not advised), all of your pushed commits will be to the main branch and considered “released”. If you use more than one branch, changes can be pushed to a development or feature branch and reviewed before being allowed in a main branch.

The use of branches allows segmentation of work into bugfixes, or the development of specific features. Different users might have their own branches so they can commit changes without a short-term conflict on files.

Branches also allow users to run experiments or create proof of concept designs without messing up the main design files. We’ll cover best practices for commits, pushing, and branches in later posts, but for now, all you need to know is that file changes are pushed to a branch.

‍

Pull requests/design reviews

In Git, the changes accumulated in a branch can only be merged into other branches using a pull request (PR). For example, if you created a branch to eliminate noise from an amplifier circuit and pushed all of your changes to a dev branch, you would need to create a PR and approve it for the files to get merged into the main branch.

At Allspice, because we focus on hardware development, we call our PRs Design Reviews. PR can potentially be a confusing label. It isn’t just a request to pull the changes from the branch but to review them in a formal process like a hardware design review.

Most electrical engineers are very familiar with a design review process and understand that it is more than an attempt to merge files. Design reviews are an opportunity to make sure the intended changes work as designed and have no other side effects.

Design reviews in Git allow users to comment, request changes, or block the process. Once a design review is started on a branch, new commits can keep coming in to fix requested changes until the design review is completed and the files are merged. After the design review is approved, any new commits to that branch must be merged using a new design review.

Some Git processes ask or require that you delete a branch after merging and create a new branch for future changes. We do not recommend this for a hardware design and will cover more in the chapter on branching.

You should invite all stakeholders to a design review. In legacy hardware development, design reviews can take several days of meetings towards the end of the design calendar.

By breaking up the changes into smaller chunks and reviewing them sooner, the reviewers can make sure their change requests have more impact on the project. Instead of carrying on for weeks with hardware that needs to change, your team members can digest the changes and make their needs known before it costs a lot of money and time to change.

Planners and purchasers need to be added to design reviews. Hardware designs should generate an accurate BOM and COGS as soon as possible, even if the design is only fractionally complete. Catching expensive components or circuits early gives your team time to meet cost objectives.

Marketers should also be kept in the loop and on design reviews. One of the other common frictions in hardware development is marketing requirements not being met.

Whether it’s cost per channel, output current, measurement fidelity or speed, UX features, radio output, or heat generated, someone should be reviewing the marketing specifications in addition to the team’s design specifications. It’s much easier to determine that you need to design a different radio if the marketing department sees that the range on the amplifier isn’t what’s been decided to be built.

Mechanical engineers are a no-brainer to include on changes, being able to ensure board outline, part fencing, and keep-outs are met, components aren’t too tall, and heat is properly dissipated.

Experienced engineers on other projects can also be added to reviews. Design reuse is important, and a reviewer from another project might notice that the designer is reinventing the wheel, when there is already an equivalent subcircuit on an older design that can be copied. When new components are added to the library, engineers can review them and recommend other components in order to not pull new part numbers.

Manufacturing engineers can identify things like single or low quantity parts that can cause additional costs to the design, when a similar part can be reused. Performing design reviews early and often allow the PCB traces to be evaluated early and offer views into whether the board will need to grow layers or add expensive and slow complexities like buried and blind vias.

Test engineers are often invited to contribute very late in the development, but adding them to all the design reviews allows them to specify test points and the addition of built-in self-test (BIST) designs. It’s easier to write test firmware in lock-step with the design than at the end when everyone must perform manual tests until the test code is completed. The test engineer can even work independently from the production firmware developer and add a separate firmware build for use in validation or verification.

‍

Merging

Why binary ECAD files are hard to merge

One of the caveats of using Git for hardware is that merging files has an added complication. Unlike software, hardware source files are often binary blobs. Schematics are 2D pictures of circuits that are stored as non-human readable text.

With software, individual functional components would have their own files separate from their connections, so it is easy to make changes to a specific functionality without affecting the operation of any other component. The way most ECAD programs structure their designs, it is hard for multiple people to make changes to a design without stepping on each other.

It is possible to open up some designs in a text editor or script, but it isn’t feasible for more than a fraction of the design to be done this way. When two different people make edits to the same schematic or layout file, it can be extremely difficult to reconcile the differences.

Very often, if two different subcircuits are on the same file, the easiest way to merge changes is to take one user’s changes via Git and then manually edit the files in the ECAD program. The future will give us more adept ECAD tools, but for now, if more than one person edits one file, one of their changes will have to be copied and pasted using a graphical editor.

How to plan file ownership before work starts

We recommend tackling your merging strategy before the work is done. It is much easier for someone to check out incremental work and make their additions, knowing there is no more work to be done than to have someone manually copying and pasting changes. A plan for Git for hardware projects covers four things:

1. Assign file or sheet ownership before work starts, so each engineer knows which files are theirs to edit.
2. Lock binary files with Git Large File Storage (LFS). The Git LFS project documents how this works in its Git LFS file locking guide.
3. Use project management software or plain old communication to see who should or shouldn’t be working on a file.
4. When two people must edit one file, take one set of changes via Git and re-enter the other in the ECAD tool.
   ‍

Releases

Releases aren’t part of Git proper but are an addition that have been adopted by many tool providers. Tags are a formal part of Git and are used to tag specific commits of code. Releases expand this by adding the ability to add files to the tagged design.

Although we recommend adding many of your output files to your tracked files that get commit to the project, releases are an opportunity to mark production or prototype-ready files. It may take several commits to fix up your design once you think you are finished.

It may take a couple of days of small changes to clean up silkscreens, move reference designators, or update fab files based on your final PCB stack-up or specification. Releases are a special way of marking the final files that other people will refer to when manufacturing your device.

If you use a separate PLM or ERP system, releases are where to store the files before they get uploaded to your planning or purchasing system. It’s up to your team whether you want to use the PLM as the final source of truth and only have your users pull files from the PLM system. It may also be advantageous to give read-only accounts to your non-design team in order for them to do their jobs more efficiently.

‍

Git for hardware replaces emailed files with one design history

When design files travel by email and revisions hide in zip archives with numbered folder names, every engineer has to guess which version is current. Git gives hardware teams a shared, traceable history of every design change instead. Simply put, Git is a decentralized version control system for your source and output files.

The flow is the same on every project. You commit small, related changes and push them to a branch, then open a design review so stakeholders can weigh in. After approval, the branch merges and you tag that commit for a release that holds the files you send out.

Git has many complexities and earns its reputation for a steep learning curve. Getting started is relatively easy, though. A team can begin with that one flow and pick up the finer points of branching and merging as they come up.

‍

FAQs

What is Git for hardware?

Git for hardware is decentralized revision control for both source files and output files, such as schematics, PCB layouts, BOMs, netlists and Gerbers. Engineers push commits to a branch, review the changes in a design review, merge them after approval and tag the result. Releases then attach the files sent to fabrication.

Can one version control system handle multiple ECAD tools?

Yes, Allspice is an ECAD-agnostic revision control system built specifically for hardware. It works with native design files from Altium Designer, OrCAD, Cadence and KiCad. Teams that use more than one ECAD tool can keep history, visual diffs and Design Reviews in one place.

How do teams automate design review and release?

Allspice Automations and Actions run CI/CD-style checks, such as BOM validation, on each change in a Design Review. Releases with approvals then mark the files manufacturing uses, and PLM/ERP sync keeps planning and purchasing systems on those same files. See Allspice Automations for hardware DevOps for more detail.

‍