Skip to content

Understand how GitM uses GitHub

GitM does not invent its own storage. Your team's data lives in an ordinary GitHub repository, and GitM drives standard Git and Git LFS underneath a PDM-shaped UI. This means your team keeps full ownership of the data and can always fall back to plain Git tools.

The repository is the store

  • The GitHub repository holds all tracked files and their full history.
  • Your local working folder (chosen during the wizard) is your copy on disk.
  • Git LFS stores the large binary CAD files, so the Git repository itself stays small and clones stay fast. Files can remain placeholders until needed.

.gitattributes: the rules that make locking work

Every GitM repository has a .gitattributes file that marks SolidWorks (and related) extensions as LFS-tracked and lockable:

*.sldprt   filter=lfs diff=lfs merge=lfs -text lockable
*.sldasm   filter=lfs diff=lfs merge=lfs -text lockable
*.slddrw   filter=lfs diff=lfs merge=lfs -text lockable

lockable is what makes files read-only on disk until checked out. If these rules are missing or wrong, locking breaks and large files get committed into Git instead of LFS. The first-run wizard writes .gitattributes when creating a new repository, and the Diagnostics tab can flag a repository whose rules are incomplete.

GitM also writes LFS rules for the other tracked buckets — derived exports, images, and binary documents are LFS but without lockable (they are never exclusively checked out). Text documents (.txt/.md/.csv) get no rule and stay as plain, diffable git blobs.

Keeping .gitattributes correct is the single most important thing for a healthy GitM repository. CAD admins should treat it as protected — see Set up a team repository.

.gitignore: keeping junk out

A matching .gitignore keeps SolidWorks backup and temp files out of the repository. Critically it includes ~$*, the temp files SolidWorks creates while a document is open — these must never be tracked or locked. It also excludes the junk bucket: simulation results (*.cwr, *Results/), backups (*.bak, *.swbak), and the SOLIDWORKS Data/ Toolbox cache — large or reproducible files that should never be tracked or captured in a snapshot.

The .gitm/ folder: GitM and GitMCloud metadata

GitM stores its own metadata under .gitm/ in the repository. The most important files:

File Purpose
.gitm/builds.jsonl The published snapshot history (Snapshots tab).
.gitm/partnumbers.json The part-number registry (remote-authoritative).
.gitm/bom/<assembly>.json Generated BOM for an assembly.
.gitm/assembly-tree.json The resolved assembly hierarchy for the browser viewer.
.gitm/milestones.json Snapshots marked as milestones.
.gitm/frozen.json Files frozen against further edits.
.gitm/repo-config.json The shared file-classification contract (File Policy) — read identically by GitMCloud.
.gitm/exchange-config.json The shared sharing policy (Sharing Policy) — enforced by GitM and GitMCloud.
.gitm/local-versions.json Per-machine, never tracked — your local Save Local Version index.

Several of these exist specifically so GitMCloud can show the same information in a browser without a SolidWorks session — the BOM, the assembly tree, the snapshot history, and part numbers.

The BOM, assembly tree, and part-number registry are read by GitMCloud — see GitMCloud docs.

Where GitMCloud fits

GitMCloud is a separate service, not part of the add-in. GitM touches it in a few places:

  • Onboarding access check — when you connect or create a repository, GitM asks GitMCloud whether your account is allowed. This fails closed: if GitMCloud can't be reached, onboarding is blocked.
  • Part-number registry — numbers can be allocated by GitMCloud and stamped into files by GitM, using a shared allocation algorithm.
  • Viewer — GitMCloud reads .gitm/ files to display BOMs, assembly trees, and snapshots in the browser.

GitMCloud has its own section in this site — see GitMCloud docs.

Known limitations

  • GitHub only. Other Git hosts (GitLab, Bitbucket) are not supported.
  • GitMCloud is currently required to onboard. Even though storage is plain GitHub, you cannot get through the connect/create wizard if GitMCloud is unreachable.
  • LFS storage currently uses GitHub's LFS backend. The code keeps the storage backend swappable, but no alternative backend ships today.