• Daniel (they/them)

Generated files best practices in Git for hardware


Generated files in git for hardware


Overview

One of the biggest differences between using git for software vs git for hardware is that software tends to use git as source control whereas hardware tends to use git as version control.


Source? Version? What’s the difference?


Source control

In a source control repo, you only track changes of original source files. If part of the toolchain generates files like object code, linked libraries, or executables, the generated files are not tracked.


The idea is that the same source files can always be used to consistently generate the same output files.


There are more mundane technical reasons like output files increasing the total file size of the repo. These extra files have to be pulled and increase the total time to synchronize with the repo. Many generated files aren’t human readable and it doesn’t make sense to include comparisons to different versions of the file, as humans can’t review them.


The compromise in source control is to create releases from specific tags and attach selected files for release. Release scripts can be created to override the downside of having to manually attach files.


Version control

In a version control repo, you track additional output files generated by the toolchain, at every commit. You don’t have to track all of the files at every commit, only the files necessary for your process.


Regulation

Some industries like medical and aerospace have very strict records keeping requirements and some of the output files from the PCBA process are required to be kept.


COGS and lead time

It’s fiscally responsible to track changes that can affect the bottom line of the PCBA. BOM changes are an early and frequent indicator of the cost of the product. Not only do components have a price tag, but they also cost money to place on the PCB. PCBs and fab costs can be approximated using the area of the board, number of cutouts, hole sizes, number of holes, total component count, number of unique components, and number of through hole and surface mount components.


Planning and purchasing are a huge part of electronic design and need access to your files that help them calculate price and lead time. Even if your BOM is hard to automatically parse, it’s still worthwhile for someone to have access and then manually produce a cost of goods sold (COGS).


Catching budget or schedule overruns early allows you to waste less time refactoring the board after you’ve sunk a lot of cost into the design.


Fabrication files

Output files like the gerbers and fab files are never too late to track. It’s incredibly easy to have a perfect PCB file, with all the traces, pads, holes, and fills where you want them, and then generate an incorrect gerber file. Layers can get merged or transposed. Elements that you thought were on the silkscreen layer could be on a documentation layer. Different layers might have different scale settings. Your tool might be outputting metric traces but the drill files could be in mills. There are dozens of problems with gerber files that can cause the wrong PCBA to be fabricated.


It’s also beneficial to check your gerbers early and often. It’s easier to fix silkscreen footprints and reference designators early before you’ve added too many footprints.

PCB board stack-up can be checked, both to evaluate cost, but also to make sure transmission lines, power distribution, and emissions are properly designed and routed.

Contract manufacturers (CM) don’t read your PCB files, they read your gerber files and fab files. If you don’t correctly mark traces for controlled impedance, or correctly specify the dielectric layers of the board stack-up, the manufacturer can’t guarantee your high speed or radio signals are going to transmit correctly.


The fab file contains a wealth of information about the various processes and options of the PCBA. You might have a perfectly good PCBA, except with the wrong finish or dielectric specified.


The drill files can be used to determine if you can save money by using fewer drill bit sizes.

The x/y position files can be used to see if any of the components are too close, or if there is a problem with mixing smt and through-hole components.


It’s important to use your CMs to your advantage during the design. If you only submit files at the end of the project, you have only a limited amount of time to integrate suggested changes, or to spot bugs in the files. It’s recommended to track these files and to submit them to a CM for review several times during the process for quote and for finding issues. Between formal submissions, having the files tracked means you can audit them and use the extra time to ensure correctness.


Design rules check (DRC)

It’s incredibly important and useful to track your design rules checks (DRC). At the beginning of the design, you have no DRC errors. As you add components, you’ll start to get more and more errors until the design starts to wrap up at the end. It’s a lot easier to tell the difference between DRC errors that are a problem and ones you can ignore if you track the changes and work on fixable errors when they’re committed. If you run the DRC and there are no new errors, then the changes you’ve committed have passed an integration test.


One of the most common errors is to accidentally move components and traces a small amount without realizing it. Sometimes when pushing and routing, a trace is moved outside the view window. It happens to everyone. By tracking the DRC and checking what fails, you’re able to spot errors as you inject them.


Simulation files

Simulation files don’t necessarily have to be generated or tracked at every commit. It may be important to be able to prove the functionality at different times during the design. If you don’t save the simulation outputs, it may be possible to revert to an earlier version of code and miss the differences that cause the environment to generate different simulation waveforms.


Prototyping files

Often some aspect of the design needs to be physically prototyped to ensure the circuit will work as intended. Bringup procedures, oscilloscope screen shots, and prototype firmware all should be tracked and captured. It’s not only a good basis and reference for validation and verification, but it also makes sure you can revisit your prototype testing if there are problems with the design.


Hiding diffs

If you’re concerned about your design reviews (PRs) have too many diffs that aren’t readable, you can hide the diff by adding specific filenames and filename patterns to the .gitattributes file and set the linguist-generated flag.


The file will still show up as having changes, but it will be collapsed in the web interface, meaning you can quickly skip over files that you can’t change.



Summary

There are many reasons to track your generated output files in a repo. It’s not a convention in software repositories, so it requires putting on a different hat to understand the cost and schedule savings to a project. After your first design cycle, you can decide if individual files are appropriate to track or not and whether they’ve saved you time, budget, and energy.



Git for hardware guide AllSpice ebook