Skip to content

Known limitations and discrepancies

This is the honest list for internal use: where the product has gaps or rough edges, and where the PRD or installer disagrees with the actual code. Where sources disagree, the code is treated as the truth and the conflict is flagged here.

PRD / installer vs. code conflicts

1. Git and Git LFS are NOT bundled (installer)

  • PRD says (§5.9.3, §13 #2 and #7): the installer bundles the official Git and Git LFS installers and runs them silently if missing, for a one-run experience.
  • Code does: GitM.iss InitializeSetup() checks for git, git-lfs, and .NET 4.8, and aborts with an error and download links if any is missing. The installer package contains no vendor installers and no prerequisites/ folder.
  • Impact: on a fresh/non-technical machine, someone must install the three prerequisites by hand first. Documented in Review prerequisites and Review prerequisites (IT).

2. BOM is shipped though the PRD lists it out of scope

  • PRD says (§11): "BOM extraction and management" is explicitly out of scope for v1.
  • Code does: there is a full BOM tab, a BOM extraction service, .gitm/bom/*.json output, CSV export, and a DESIGN_BOM.md. GitMCloud displays the BOM.
  • Resolution: documented as a real, shipped feature in Generate a BOM.

3. Part-number generation is shipped though not in the PRD

  • PRD says: item management / numbering is out of scope (§11, non-goals).
  • Code does: a part-number registry (.gitm/partnumbers.json, remote-authoritative), an admin-gated auto-assign toggle, and a shared allocation algorithm mirrored by GitMCloud.
  • Resolution: documented in Manage part numbers.

4. GitMCloud is a hard dependency but absent from the PRD

  • PRD says: nothing — GitMCloud does not appear in the PRD at all.
  • Code does: the wizard's connect/create flow calls a GitMCloud access endpoint (https://gitmcloud.gojain.com/api/check-access) and fails closed — onboarding is blocked if GitMCloud is unreachable or the user isn't allowlisted. GitMCloud also backs the part-number registry and the BOM/assembly viewer.
  • Impact: GitMCloud readiness is a blocking prerequisite for any rollout. Documented in Prepare GitMCloud before installing and Connect to GitMCloud.

5. Settings tabs differ from the PRD

  • PRD says (§5.2): tabs include separate File Types and Profiles tabs.
  • Code does: the shipped tabs are Repository, Authentication, Identity, Behavior, Storage, Diagnostics. There is no standalone File Types or Profiles tab; those concerns live in .gitm.json, the wizard, and the Storage tab.
  • Resolution: Settings reference documents the actual tabs.

6. Top-bar actions differ from the PRD

  • PRD says (§5.1): the two primary top-bar buttons are Get Latest and Sync.
  • Code does: the top bar exposes Get Latest, refresh, settings, help, and a notification bell. Publishing is done through the per-file/batch Check In, not a single "Sync" button. The raw Advanced (Fetch/Pull/Push) menu described in the PRD is not a prominent surface.
  • Impact: minor; the PDM verbs the user actually needs (Get Latest, Check In) are present.

7. Version numbering

  • The version is defined once in Directory.Build.props (<Version>). The add-in assemblies, the in-app ? version (GitMVersion), and the installer (GitM-Setup-<ver>.exe, which reads it back off GitM.Core.dll) all derive from it, so they are always in lockstep. Bump that one line to cut a release — it is never auto-incremented on a build.
  • Build identity (which exact binary) is tracked separately as a git hash + date stamped into the assembly's InformationalVersion; ? → Version surfaces it, e.g. V1.5.0 (423dd75 · 20260615).
  • The latest installer is 1.5.0 (GitM-Setup-1.5.0.exe); earlier 1.2.0, 1.3.0 and 1.4.0 builds also exist in the Output folder. It upgrades any earlier install in place.
  • Impact: when reporting issues, capture the ? → Version build stamp — it pins the exact build.

8. Tech stack differs from the PRD (not user-facing)

  • PRD suggests: LibGit2Sharp for status, Octokit.NET for GitHub, System.Text.Json for settings.
  • Code does: Git via the git CLI (not LibGit2Sharp), and Newtonsoft.Json for serialization (System.Text.Json ships as a transitive dependency but is avoided for settings because it caused binding conflicts in the SolidWorks process).
  • Impact: none for users; relevant to contributors.

9. "Vault" terminology

  • The PRD uses "vault" for the repository-as-store concept. The product UI never uses the word. Docs avoid it; see Terminology.

Product limitations (by design or current scale)

  • "Free up space" temporarily removed. The action that removes a file's local bytes and leaves a placeholder behind has been disabled while OID-verified hydration stabilises. The risk it posed (setting skip-worktree, which silently prevented correct bytes from being written on restore/pull) is eliminated in its absence. It will be revisited once the hydration layer is proven stable.
  • Pessimistic locking only. No optimistic/multi-editor mode for CAD files. Binary files can't be merged; conflicts are "use mine / use theirs."
  • GitHub only. No GitLab/Bitbucket.
  • One active repository at a time. No simultaneous multi-repo tabs.
  • No auto-update. New versions are a new installer .exe.
  • No selective/sparse hydration ("Focus on assembly") — deliberately deferred until repos reach tens of thousands of files.
  • Network-dependent operations (locks, push, LFS) are slow on poor connections; GitM favors correct-but-slow over fast-but-wrong (no short timeouts on local metadata ops).
  • Unsigned installer during development — expect SmartScreen warnings until code-signed.

Rough edges / bugs observed (status)

These were seen during development; most have fixes. Listed so they're not surprises.

Area Symptom Status
Lock scan All files showed "Not Locked" due to a stdin/stdout pipe-buffer deadlock in the file scan. Fixed.
Local version badge L badge / "unpublished local version" warning stuck after a clean check-in (stale count not reset to 0). Fixed.
Hydration "Make Available on this PC" did nothing on skip-smudge repos (needed fetch+checkout, not pull). Fixed (OID-verified make-current + pre-open gate; see docs/design/hydration-contract.md).
Open Right-click → Open didn't surface the file in SolidWorks (needed activate after open). Fixed.
Push Recurring "fetch first" / non-fast-forward rejections, worsened by out-of-band part-number commits. Mitigated: auto-assign off by default + pull-rebase retry on push.
Settings dialog Crash on open due to a missing XAML converter. Fixed.
UI flicker File list rebuilt on every refresh; transient messages shifted layout; Versions loading bar flashed. Fixed (diff-patch list, toast/bell overlays, delayed loading bar).

How to keep this page honest

When you change the code in a way that resolves or adds one of these, update this page in the same change. This is internal documentation; an out-of-date limitations list is worse than none.