Settings reference¶
Every tab and field in the Settings dialog (⚙️). The shipped tabs are Repository, Account, Preferences, Team & Sharing, Diagnostics.
Repository¶
| Field / action | Meaning |
|---|---|
| Active repository | The one repo GitM is currently working with. |
| Local working directory | Path on disk for the active repo. |
| Remote URL | The GitHub URL (e.g. https://github.com/org/repo.git). |
| Default branch | The branch GitM treats as the main line. |
| Test connection | Checks the remote is reachable. |
| Connect another repository… | Launches the wizard's connect/create flow and adds a repo. |
| Switch active repository | Select a previously-connected repo to make active (with open-document safety check). |
Account¶
| Field / action | Meaning |
|---|---|
| Preferred auth method | Git Credential Manager (recommended), Personal Access Token, or SSH. |
| GitHub username | Your GitHub login. |
| Personal Access Token | Masked; stored encrypted in Windows Credential Manager (DPAPI), never in plain JSON. |
| Test authentication | Verifies credentials work against the remote. |
| Commit Identity — Name | Name recorded on git commits (pre-filled from global git config if present). Stored per-machine. |
| Commit Identity — Email | Email recorded on git commits. Stored per-machine. |
| Edit Profile… | Opens the Profile dialog to set your display name, optional contact email, and avatar. Profile data is separate from git commit identity. See Set up your profile. |
Preferences¶
Scope: only this device.
| Field | Meaning |
|---|---|
| Lock File On Open | Always / Prompt / Never. Recommended: require an explicit Check Out before editing. |
| Check for Updates | Off / Every 1 minute / Every 5 minutes (recommended) / Every 15 minutes. Drives a background read-only fetch that checks GitHub for new content files and updates the count badge on the Get Latest icon. Never downloads files — Get Latest does that. Default: every 5 minutes. |
| Default Description Template | Default text for the check-in description (commit message), with tokens like {branch}, {summary}. |
| Include drawings when checking in models | Whether to include related drawings when checking in models. |
| Walk assembly references on check-in | Yes / Ask / No. |
| Squash before sync | When enabled, Check In offers to collapse multiple local commits into one clean commit. |
| Lightweight Connect | Download file contents on demand rather than on connect. When turned off and saved, the active repo is fully hydrated immediately. |
| Assembly Open Mode | Ask / Full / Lean — how to handle opening assemblies that contain placeholder components. |
| Auto-Free Unused Files | Currently disabled. |
Storage (subsection of Preferences)¶
| Field / action | Meaning |
|---|---|
| Version Retention | How many snapshots' LFS objects to keep locally. Older snapshots remain on GitHub but aren't cached locally. |
| Auto-prune after push | Whether to prune old LFS objects automatically after publishing. |
| Local LFS Cache size | Shows current disk usage; click Refresh to measure. |
| Prune LFS Cache Now | Remove LFS object data for snapshots older than your retention limit. Commits and tags remain; only the local file cache is trimmed. |
Team & Sharing¶
Scope: everyone in this repo. Requires Admin or Maintainer role.
| Field | Meaning |
|---|---|
| Auto-assign part numbers on check-in | Admin/Manager only. When enabled, files checked in without a part number receive one automatically. See Manage part numbers. |
File Policy (admin-only)¶
Defines which file types GitM tracks and how it classifies them into buckets.
Saved to the shared .gitm/repo-config.json and applied to everyone in the repo on their next
pull. Each field is a comma-separated list.
| Field | Meaning |
|---|---|
| Source (native SolidWorks) | Extensions that are locked on check-out, part-numbered, and in the BOM. Changing this affects locking — edit with care. |
| Derived (neutral / 2D exports) | Extensions tracked as derived outputs (not lockable, no part number). |
| Documents | Document extensions (binary → LFS, .txt/.md/.csv → plain git). |
| Images | Image extensions (LFS). |
| Library folders (read-only reference) | Folder prefixes whose contents are treated as read-only reference, regardless of file type. Default Library/. |
Sharing Policy (admin-only)¶
Controls supplier share links for the repo. Saved to the shared .gitm/exchange-config.json
and applied to everyone. See Share files with a supplier.
| Field | Meaning |
|---|---|
| Roles allowed to create share links | Engineer / Manager / Administrator / Owner checkboxes. Only checked roles see the Share button. |
| Allow sharing native SolidWorks files | When off, .sldprt/.sldasm (and other source files) are excluded from shares; derived/document/image files are always shareable by allowed roles. |
| Require a password on every share | Forces a password on each generated link. |
| Default expiry | The expiry pre-selected in the Share dialog (7 / 30 / 90 days). |
| Maximum expiry (cap) | The longest expiry a sharer may choose (7 / 30 / 90 days / 1 year / No cap). Longer options are removed from the Share dialog. |
Library Sources (Git) (admin-only)¶
Defines GitHub repos the team can copy standard parts from. They appear in the
Add Library Part dialog for everyone, saved to the shared
.gitm/library-sources.json. (Local-folder sources are per-machine and added in that dialog
instead.)
| Field / action | Meaning |
|---|---|
| Existing sources list | Each configured Git source (name + owner/repo/subfolder) with Remove. |
| A repo in this account | Load lists your account's repos; pick one as the source. |
| …or search public repos | Search GitHub's public repos and pick a result. |
| Library name | The Library/<name>/ subfolder the parts copy into. |
| Branch / Subfolder (optional) | Pin a branch/tag, and/or limit to a folder within the source repo. |
| Add source / Save | Add source stages it; Save writes the shared list to GitHub. |
Diagnostics¶
A list of system checks with green/red status:
- Git installed, Git LFS installed, LFS hooks registered.
- Local path is a valid repo, remote reachable, authentication working.
- .gitattributes has LFS + lockable rules for SolidWorks extensions.
- Open SolidWorks documents inside the working copy (relevant to branch/repo switches).
Actions: Run all checks, Export (sanitized report, no token).
Advanced (settings.json only)¶
These fields are not exposed in the Settings dialog. Edit %APPDATA%\GitM\settings.json directly
to change them. Incorrect values fall back to today's manual-refresh behavior — they cannot crash
the add-in.
| Field | Default | Meaning |
|---|---|---|
RealtimeSyncEnabled |
true |
Kill-switch for the Firebase realtime doorbell. Set false to disable live refresh and return to manual-refresh-only behavior. |
RealtimeDbUrl |
https://gitmcloud-default-rtdb.firebaseio.com |
URL of the Firebase Realtime Database instance. Change only if you have migrated to a different Firebase project. |
Notes¶
- Per-user settings persist in
%APPDATA%\GitM\settings.json. Shared team conventions live in the repo's.gitm.json— see Configure team settings.
Known limitations¶
- The original PRD described separate File Types and Profiles tabs. The shipped UI does
not have those as standalone tabs (file-type/tracking and profile concerns are handled via
.gitm.json, the wizard, and the Storage subgroup in Preferences). See Known limitations and discrepancies.