3. Geometry Source File Version Control Set

Why geometry files need a different versioning strategy

CAD geometry is the heaviest artifact in a CAE project. A single STEP or native CAD part can easily reach 50–500 MB, and assemblies routinely exceed several gigabytes. Git stores every version of every tracked file as a compressed blob inside .git/objects. If you commit a 300 MB STEP file and then revise it five times, the repository grows by roughly 1.5 GB even though the working tree only shows one file. Cloning becomes slow, git gc runs for minutes, and the history is effectively unusable for anyone on a normal workstation.

Git LFS (Large File Storage) solves this by replacing the large binary in the commit with a small text pointer file (about 130 bytes). The actual content is uploaded to a separate LFS object store, and Git history only ever contains pointers. The repository stays lightweight while the geometry remains fully versioned and retrievable.

This case configures that workflow from scratch: install and initialize LFS, declare which geometry extensions are tracked, commit a baseline geometry file, and verify that the repository contains a pointer rather than the binary payload.

How the pointer mechanism works

The diagram below shows the split between what Git tracks and what LFS tracks. The commit object, the tree, and the pointer file all live in the normal Git object database. The binary payload is addressed by its SHA-256 hash and stored in the LFS cache and remote. On checkout, the LFS smudge filter reads the pointer and materializes the real file into the working tree.

Configuring the LFS workflow

The setup assumes a repository already initialized with git init and a project skeleton containing a geometry/ folder. The commands below are the complete sequence; each one is idempotent and safe to re-run.

# 1. Install Git LFS once per machine (verify with --version)
git lfs install

# 2. Declare which geometry extensions LFS should intercept.
#    .gitattributes is committed so every clone inherits the rule.
git lfs track "*.step"
git lfs track "*.stp"
git lfs track "*.iges"
git lfs track "*.igs"
git lfs track "*.sldprt"
git lfs track "*.CATPart"

# 3. Confirm the generated attributes file
cat .gitattributes

The resulting .gitattributes should contain one line per pattern, for example:

*.step filter=lfs diff=lfs merge=lfs -text
*.stp  filter=lfs diff=lfs merge=lfs -text
*.iges filter=lfs diff=lfs merge=lfs -text
*.igs  filter=lfs diff=lfs merge=lfs -text
*.sldprt filter=lfs diff=lfs merge=lfs -text
*.CATPart filter=lfs diff=lfs merge=lfs -text

Two details matter here. First, -text disables Git's line-ending normalization, which would otherwise corrupt binary CAD data. Second, the .gitattributes file must be committed before the geometry file is added; if a binary is staged first, Git records it as a normal blob and LFS never sees it.

Committing the baseline geometry

With tracking configured, place the baseline file in the geometry folder and commit it together with the attributes file. A meaningful commit message and an annotated tag make the baseline retrievable later.

# Stage the LFS rule and the baseline geometry
git add .gitattributes
git add geometry/bracket_v01.step

# Commit with a descriptive message
git commit -m "Add baseline geometry: bracket_v01.step (rev A, LFS-tracked)"

# Tag the baseline so downstream cases can reference it
git tag -a geom-baseline-v01 -m "Baseline CAD geometry for bracket assembly"

Verifying the repository stays lightweight

Verification has three independent checks. All three should pass before the baseline is considered accepted.

A fourth check confirms the payload is actually retrievable, which is the real test of a working LFS setup:

# Remove the working copy and restore it from LFS
rm geometry/bracket_v01.step
git checkout -- geometry/bracket_v01.step

# Confirm the restored file matches the recorded size
git lfs pointer --file=geometry/bracket_v01.step --check
ls -lh geometry/bracket_v01.step

The --check flag exits with status 0 when the working file matches its pointer's recorded size and OID. If it reports a mismatch, the smudge filter did not run or the LFS object is missing from the local cache.

Typical failure symptoms and fixes

• git lfs ls-files is empty after commit. The file was staged before .gitattributes existed, or the extension does not match any tracked pattern. Check git check-attr filter -- geometry/bracket_v01.step; it must report filter: lfs.
• Pointer file appears in the working tree instead of the binary. The smudge filter is not installed on this clone. Run git lfs install and then git lfs pull.
• Repository still large after adding LFS. Earlier commits already contain the binary. Use git lfs migrate import to rewrite history, or reset to a clean baseline commit.
• Push rejected with "this exceeds GitHub's file size limit". The file bypassed LFS. Verify the attributes rule and re-add the file with git add --renormalize ..

Baseline acceptance checklist

The following checklist captures the minimum evidence required to declare the geometry baseline accepted. It is intended to be filled in and attached to the baseline tag.

Once these checks pass, the repository holds a fully versioned baseline geometry with a lightweight history. Subsequent revisions of the same file will add only pointer-sized deltas to Git, while the LFS store accumulates the binary payloads under content-addressed hashes — the foundation for the mesh and solver-deck tracking that follows.