← All posts

Version Control for STEP Files: A Clean Git Workflow for Mechanical Design

STEP files are the lingua franca of mechanical engineering. They disappear into chaos on shared drives fast. Here's how to version them with Git, keep full history, and see exactly what changed.

By Jon Klinger · Blue Dog

What a STEP file is and why it matters

A STEP file (.step or .stp) is a neutral 3D geometry format. It contains the full shape of a part or assembly: surfaces, solids, dimensions, tolerances, metadata. Unlike a SolidWorks part or a Fusion design, a STEP file doesn't live inside one vendor's ecosystem. It's a handoff format. When a supplier needs your bracket, you send STEP. When a contract manufacturer needs to review your assembly before quoting, they import STEP. When you're doing finite element analysis in a different tool from where you modeled the part, STEP is the bridge.

Because STEP files move around so much, they accumulate on shared drives and email inboxes. A single bracket design can become dozens of files in a project folder:

Bracket_v2.step
Bracket_v3.step
Bracket_v3_FINAL.step
Bracket_v3_FINAL_revised.step
Bracket_v3_FINAL_revised_JK.step
Bracket_3.1_withhole.step

It's obvious this is broken. Nobody is sure which one is current. If two engineers both export STEP from their local designs on the same day, one person's geometry quietly disappears. When someone asks for the full history of changes, there's nothing to show them.

The shared drive problem

The core issue is that STEP files on a shared drive have no version control. They have storage. That's different.

When you save a new STEP file to a shared drive, you're creating a snapshot in time. That file sits there unchanged until someone replaces it with a newer snapshot. There's no record of who made the change, when they made it, or why. If two people both export a new version at the same time, one silently overwrites the other without warning.

Real version control keeps every snapshot: every change, who authored it, when, and why. It tracks relationships between versions so you can move backward or sideways in time without losing anything. It stops you if two people try to commit conflicting changes at the same time, so overwrite collisions become visible problems you resolve immediately rather than losses you discover weeks later.

PDM and PLM systems (SolidWorks PDM, Windchill, Teamcenter) handle STEP files with formal version control. They work well if your team can justify the deployment cost and the workflow overhead. Many teams can't. For the rest, the shared drive is the only option, and the folder full of _FINAL_revised files is the cost of using it.

A Git and Git LFS workflow for STEP

Git was built for source code, where changes are lines of text that can be compared and often merged automatically. STEP files are binary. Flip one geometric feature and the entire file structure scrambles. Git's native text-based diffing can't read binary geometry.

The answer is Git LFS (Large File Storage), a Git extension that handles large binaries cleanly. Here's how to set up a working STEP version control workflow:

1. Initialize your repository

Start with a standard Git repository in your project directory:

git init
git config user.name "Your Name"
git config user.email "you@company.com"

2. Configure Git LFS for STEP files

Install Git LFS if you don't have it, then tell it to track STEP files:

git lfs install
git lfs track "*.step"
git lfs track "*.stp"

This creates a .gitattributes file that routes STEP files through LFS. Commit it:

git add .gitattributes
git commit -m "Configure Git LFS for STEP and STP files"

Now every STEP file you add will be stored in Git LFS. The file pointer (a small text file) goes into Git's regular storage, while the actual geometry lives in LFS. This keeps your repository lean while preserving full binary fidelity.

3. Add your STEP files

Move your STEP files into the repository and stage them:

git add *.step
git commit -m "Initial bracket and assembly STEP files"

Every file gets a commit hash. You now have a permanent record of this exact geometry at this exact moment.

4. Branch for design variants

When you need to explore a design variant, say testing a thicker wall or a different mounting pattern, branch from main:

git checkout -b feature/bracket-wall-thickness

Now you're in a private workspace. Export new STEP files from your CAD tool and commit them:

git add Bracket_v3.step
git commit -m "Increase wall thickness to 3mm for stress relief"

You can keep iterating, keep committing, and none of it touches what the main design is based on. The main branch stays stable.

5. Merge and commit as a unit

When your variant is ready, merge it back to main:

git checkout main
git merge feature/bracket-wall-thickness

If no one else has changed the same file, the merge completes cleanly. If someone did edit the same STEP file, Git flags it as a conflict and stops. You see both versions and decide manually which geometry is correct. This is the right behavior. Automatic merging of 3D geometry is unsolved. Flagging the conflict forces a human decision instead of silently corrupting your design.

6. See what changed

To see the commit history of a STEP file:

git log --oneline Bracket_v3.step

You get every commit that touched that file, with authors and messages. For regulated designs, this is your audit trail.

Git can't show you a visual diff of STEP geometry, but it can show you metadata. If you want to see the actual geometry differences side-by-side, tools like OpenVault add a visual 3D diff layer on top of Git, so you see exactly which features changed between revisions.

Why this matters

A Git and LFS workflow for STEP files gives you:

For teams that need more, a web UI with 3D preview, approval workflows, deeper CAD integration, automated BOM extraction, tools like OpenVault layer those features on top of Git. You keep the solid foundation and add the workflow tools you need.

Start small

You don't need a new PDM system to version your STEP files. You need Git, five minutes to configure LFS, and a discipline to commit with a message every time you export a new revision. The tooling is free and open source. The payoff is a design history you can trust and a record of every change that actually happened.

Version Control for STEP Files with Git and Git LFS | Blue Dog