Why use Git pros and cons

Legacy revision control - file systems

Hard drive, hard times. The original revision control was engineers keeping separate files with revision numbers and dates tacked onto the filename to differentiate versions. It was relatively easy to open up an old revision, make changes, and no one would know that the changes were there or if they were correct. It was up to the engineer to manage R1 vs R2 vs R23.

Uncontrolled network files can be worse than nothing. It was also very easy for a network version of the files to be downloaded to a local machine and have different designers make independent changes without knowing what the other team members were doing. When generating files for contract manufacturers, zip files might be updated many times to create changes for the CM, with no clear view onto which set of files was “correct.”

Product lifecycle management (PLM) systems

PLMs improved single source of truth: Major improvements came with PLM systems. Users could attach specific versions of files to a software system so that everyone could point to the exact files for a revision. It became much easier to share files with the confidence that any given file was the correct version.

Large monolithic reviews: One of the downsides to this approach is the need for monolithic reviews before the files could be released. Unless users were attaching incremental changes to their PLM systems, PCBAs need to have everything that changed reviewed at once. This leaves designs open for adding bugs as well as not implementing all of the new features intended for a new design.

Large reviews are slow: Design reviews tended to be multi-week events with spreadsheets to track comments, with no real link to individual issues and whether or not they got resolved. At some point, all the reviewers had to take the plunge to the next revision and push any missed changes to the next phase.

Source files aren’t tracked: A large downside to using only a PLM system is that although the deliverables and key revisions of files are indexed, the source files are not tracked. It is up to custom and manual communication as to who is the keeper of the files between releases. If a user’s local machine fails, the files and changes are gone. If the files are kept in a network folder, it can be easy to overwrite changes made by others.

Revision control using Git

With the adoption of git, users are able to gain the benefits of tracking releases, such as in a PLM, with the flexibility of a local file system that is also synchronized with a network copy. Users are able to perform iterative, atomic, and asynchronous changes to the source files. Much of this can be done offline and then pulled and pushed when a group of changes needs to be harmonized.

Atomic commits speed review

Small, focused changes are better than large, mixed commits. Although nothing is stopping users from creating one single commit after months of progress, the git way is to create atomic commits that corral changes to a specific section of the circuit. It may seem like atomic commits generate more work, requiring more time to create and review each commit, but they can save time in the long run.

Small changes are easier and faster to review. By only reviewing small changes, it is much easier to determine if a design has accurately changed and is bug free. The reviewer’s focus is on a small set of feature changes instead of jumping around among all the changes.

By adding well-formatted commit messages, the creator documents the intention of all of the changes, rather than a fraction of highlights.

Atomic commits speed revision

Small changes can be fixed quicker. When users check-in small changes, they are immediately available for a review. Designers can get feedback on their changes on the same day and start making corrections if anyone has feedback. Rather than adding layers of design sediment on top of one another, things that are recommended to change can be changed long before they accrue design momentum and affect adjacent subcircuits.

Small changes improve component reuse. This helps with things like users selecting new components when similar ICs have already been used in the organization. Component reuse affects volume purchasing and leverages existing design validation.

One designer might select a component with I2C communication without realizing that a majority of the team’s solutions have been using SPI, allowing the design to compound the gains of previous hardware projects.

Small changes get reviews while changes are still top of mind. Atomic commits allow you to revise designs while they are still fresh in your mind. If you get feedback that your DC to DC supply isn’t meeting the power requirements, it is easier to change then and there, rather than weeks later after dependent circuitry has been laid out.

Large changes might get scrapped. The advantage of small changes and reviews is dramatically increased with layout. Whereas schematic design is the logical selection of components that float in a virtual representation of the circuit, PCB layout is a literal 2D mapping of the components and traces, and changes to the design must rip up nets and topologies and force the designer to redo work.

Small changes mean better feedback, sooner. Test engineers can validate that test points are added and useful long before the design is close to completion when it can be cost prohibitive to change the layout design. Design for Manufacturing (DFM) changes can be requested and implemented in-step with the design, rather than late in the project when work must be repeated. High-speed digital circuits can be routed and approved early and as the rest of the topology is placed and routed, designers can give their feedback on circuits that affect the transmission lines or areas where the EMI can leak out.

Asynchronous reviews reduce meetings

In-person meetings are an opportunity cost. Whether it’s a room full of people in front of a projector or a daily stroll or video chat to a co-worker’s screen, asynchronous reviews cut down on in-person meetings. It’s hard enough to tie all of our schedules together, but meetings put a penalty on the opportunity cost of our free time. If we’re in a design review meeting, we can’t be anywhere else at that time. We can’t respond to fires, new opportunities, or the changing landscape of marketing features.

Cloud reviews receive more feedback. When a user commits and pushes their changes in git, you can react as soon as you see the notification, or when the time is most convenient for your brain-space. Even if everyone who would be in a meeting were conducting their reviews at the same time, the ability to think independently without a single speaker walking everyone through the design review allows developers to concentrate and focus on their expertise.

Asynchronous reviews let specialists be special. Different engineers have different specialties, and the people who need to spend their time reviewing the placement of components and vias in a voltage regulator circuit don’t need to spend their time during a meeting reviewing the high-speed digital circuitry. The mechanical engineer doesn’t have to sit through hours of meetings when they’re interested in ensuring mounting holes are in the correct location and that the keep-out and height restriction zones are correctly defined and run through a design rule checker (DRC).

Total change history

View every change and every revision. When using git, you have access to the total change history of a file. You can see who has worked on it, what changes have been made and when. It’s an important feature for your first revision of hardware, but it’s critical for long term designs that can be updated several times a year for many years. When a PCB is at revision 25, it is imperative that anyone who is using it can go into a system and determine what the form, fit, and functional changes are between rev 25 and rev 24 as well as between older versions.

Find and fix issues at any point in the design history. Sometimes circuit functionality is changed, but doesn’t manifest as a problem until future revisions, when new changes are added. With total change history, users can rewind to the time that the original circuit was modified to get an understanding of what the changes are and how they affect one another.

History lets you adapt to supply chain issues. Sometimes components are replaced due to a supply shortage, but it becomes necessary to revert back to the old designs when the shortage is gone, or it’s demonstrated that the replacement isn’t performant.

History lets you find the responsible engineer. Because each change is atomic, the commit message should describe what changed and why, but if that isn’t enough, each commit is unique to a user and you can seek them out to ask about the rationale or subtleties of a feature change.

Git issues and milestones simplifies requirements tracking

Track individual problems with ease. Git issues allows users to create requirements, bug fixes, and feature requests inside the revision control tool itself. Many engineering teams use an external tool like a spreadsheet, requirements document, or kanban to capture and track requirements. While this is decent project management, there is nothing to guarantee anyone is checking to make sure they are implemented at all, much less correctly.

Organize your issues. In git, you can create milestones that are collections of issues and design reviews. You track your desired outcomes in issues and implement the changes in design reviews (aka “pull requests”).

Keep issues from falling through the cracks. If you close out all of the design reviews in a milestone, but there are still open issues, then you know there is more work to be done. This brings the atomic nature of git to project management. Instead of having a monolithic spreadsheet, or a disjointed kanban, each issue is its own “file” and can describe specific requirements or changes. Each issue also has a history allowing people to discuss the issue describing possible implementations or whether the solutions are working on solving the issues. Issues can be re-opened if they are discovered to not solve the original problem.

Tight integration with repo. There is even automatic closing of issues if you refer to an issue number in a Design Review when you merge, using keywords like “fixes #287”, “closes #876”.

Plays nice with external issue tracking. While an organization may still opt to use an external tool for project management, the engineers can add issues and milestones into git and ensure they are implemented and have visibility to when and where the changes occur.

Git branching is more flexible

Git has an extremely flexible branching strategy that is both powerful, but gives you enough rope to trip over yourself.

The main branch is for releases and hardware that is ready for manufacturing. These are files that you know are solid and have been reviewed.

A second branch, the development branch, is for collecting the changes that lead up to major hardware revisions. A typical git flow strategy uses additional branches for new features. Because hardware files are often binary blobs, merging changes from multiple branches can cause problems. Unlike code, where you can slice and dice the text, hardware design files may require manual merging.

Divide up the work by file. If two designers are working on separate schematic files, it is very easy for them to have separate feature branches and merge without conflicts. On the other hand, if two designers are working on the same layout file, there is currently no text-based tool to chop up the changes and integrate them correctly, as both designers intended.

Prototype without overwriting main. This can be useful if you want to pursue prototypes with experimental features, while engineers keep developing the main hardware. Because each branch is separate, anyone can make changes and put together a proposed solution, without the revision control software gatekeeping file checkout. The downside to this approach is manual merging if the branch proves useful.

Git gives you the flexibility to create as many or as few branches as your team needs.

Git is faster

Git only transfers the parts of files that change. No matter which way you’re tracking files, you have to copy them to and from a server. Unlike legacy systems like plain old file systems, PLMs, or SVN which copy all of the files, when you push or pull files in git, you are only copying the changes. This can lead to extreme time savings over the lifecycle of the project. It doesn’t just save you time, it enables smaller changes more often. An engineer doesn’t have to wait for a large file push, if they’ve only added a handful of components.

Git has many software solutions

AllSpice Hub is specialized for hardware development. Although we recommend your next hardware project use AllSpice Hub and our hardware specific features like automatic visual diffs of schematics and layout and creating snippets of 2D files for discussion and issue resolution, there are dozens of solutions out there.

Many choices for git hosting. Cloud solutions like GitHub, Bitbucket, Perforce, Beanstalk, Amazon AWS CodeCommit, Phabricator, Microsoft Azure DevOps, SourceForge, GitLab, and Gitea offer a range of tools from fully managed servers to host-your-own server.

Use the git front-end that best works for you. Files can be managed by the command line and integrated into scripts, or checked in and out by desktop clients such as TortoiseGit, GitHub Desktop, GitKraken, GitCola, GitForce, VSCode to name a few.

Your most powerful users won’t feel held back by a specific tool and your newer users can use a desktop client and handwave away git’s deep feature base.

Git is complex

Git is simple when it's simple. Because of the vast array of features in git, it earns the reputation for having a bigger learning curve than other solutions. It’s relatively easy to get started and work on a small project with a small team and never encounter any of the complex merging issues that can crop up.

Git is complex when it’s complex. Unless all users maintain a relatively rigid self-enforced process, they might eventually encounter changes coming in the wrong order, merge conflicts, and an inability to effectively add changes until problems are resolved.

Learning the difficult bits makes you powerful. There are many good solutions for these problems like discarding local file modifications, resetting the head to undo local commits, reverting pushed commits, and bisecting and marking commits to find when the problem commit was merged. These solutions require a more sophisticated experience with git and can be disruptive to schedules while the problem is sorted out. Very often, however, once a mistake is made and identified, users can be educated on how to avoid the mistake without needing the complicated solution.

Merge conflicts

ECAD files are hard to merge. It is often mentioned in the hardware design process that it is difficult to merge two different developers’ changes to a single hardware file. This is a problem with all revision control approaches, and stems from the way ECAD tools store the data in files. All components, traces, nets, attributes and other file features are interwoven in a file, with no way to discern changes created by separate users on separate local file systems. This isn’t a downside of git, this is a downside of the ECAD file formats.

Although this problem won’t be fixed in the near future, the software industry has demonstrated significant productivity and reliability boosts by leveraging the ease of merging in text files. It is merely a matter of time before difficult merge problems are resolved and the same file can be worked on by multiple people simultaneously.

Vanilla git doesn’t show schematic and layout differences

AllSpice shows you object level schematics and layout. Because git was developed for software, the tool shows the difference between files in a text format. If you are using vanilla git, you will have to either pull the changes under review and open them in their native ECAD program or generate review PDFs. Both approaches have their drawbacks.

Vanilla git is hard to review hardware. The pulling solution limits review to only people who have the ECAD license. Those tools are expensive and are usually limited to the handful of engineers who are working on the changes. This often precludes mechanical engineers or planners from effectively reviewing changes.

PDF reviews are awkward. Generating PDFs either delegates the A/B comparison to the reviewer, or requires an engineer to compile a list of before/after slides in a review presentation. This is not only time consuming, it often leads to incomplete reviews, reviewer fatigue, or misunderstandings of changes.

Native diffs without opening ECAD software. AllSpice Hub solves this problem by automatically generating visual diffs of the schematics and layout files. The native ECAD formats are processed and generate files that everyone can read: SVGs. The files are hosted and anyone visiting the Design Review will see redline deletions, yellow changes, and green additions. BOM differences are easy to see and are ready to be sent to or reviewed by a manufacturer.

###### ![][image1]Bill of Material (BOM) redline diff shows the before and after

In this image, you can see that all the yellow components and nets changed values or position. The green components are new.

![][image2]

###### Schematic diff with changed components in yellow and new components in green

Git is revision control, not PLM

Git doesn’t replace PLM. It is wholly possible to use git without a PLM system. Users can grant contract manufacturers access to specific repos or releases. Many users, however, will still use both tools in tandem by leveraging git for the exceptional version control, and PLM systems with their integration into ERP systems and release file access.

Summary

Git reduces effort, improves accuracy, and lowers cost. There are many different revision control solutions for your hardware project. The drawbacks of using a plain-old-file-system should be clear. Using PLM systems by themselves are a good step in the right direction, but are updated too infrequently. Centralized solutions such as SVN contain many benefits, but lack the flexibility and speed of git. While we recommend AllSpice Hub for your next hardware project, git is a great platform, in general, to manage your changes and take a little bit of the hard out of hardware.