Understand versions and snapshots¶
GitM tracks your work on two parallel timelines, and the difference is the key thing to understand:
- File versions — the fine-grained, everyday stream. Each time you Check In a file, that one file gets a new cloud version. This happens often.
- Snapshots — coarse, deliberate captures of the whole repository at a moment in time. You cut a snapshot with Publish Snapshot when you want to mark a milestone everyone can return to. This happens occasionally.
Snapshots are labels laid on top of the continuous file-version stream — git already records every file version for free; a snapshot just pins a name to the entire project's current state.
The levels of "saving"¶
| Action | Scope | Published to team? | Creates a snapshot? | Lock |
|---|---|---|---|---|
| Save in SolidWorks | Your disk only | No | No | Keeps lock |
| Save Local Version | Your local history | No | No | Keeps lock |
| Check In (right-click a file) | That one file → GitHub | Yes | No | Releases lock |
| Check In All (bottom bar, when pending) | All pending files → GitHub | Yes | No | Releases locks |
| Publish Snapshot (bottom bar or ⋯) | Whole repository → GitHub | Yes | Yes | Releases locks |
Local version (Save Local Version)¶
Save Local Version records a checkpoint in your local history without publishing it and without releasing your lock. Use it when you want a restore point mid-task but aren't ready to share. A file with unpublished local versions shows an L badge (e.g. L1, L2).
Local versions are per-machine and not yet on GitHub. If you release the lock or discard the file before publishing, unpublished local versions are discarded — GitM warns you before doing that.
Check In (one file, no snapshot)¶
Right-click a file → Check In publishes that single file to GitHub and releases its lock. This is the everyday action. It does not create a snapshot — it adds a new cloud version of just that file. Use it freely; it's meant to be frequent.
Check In All (all pending files, no snapshot)¶
The ☁ Check In All button at the bottom of the Files tab publishes every file with pending changes to GitHub and releases their locks. It is the primary bottom-bar action whenever you have uncommitted work. Like single-file Check In, it does not create a snapshot — it is not a milestone.
Publish Snapshot (a milestone of the whole repo)¶
☁ Publish Snapshot takes a snapshot of the entire repository's current state and records it as a numbered milestone (Snapshot 7, Snapshot 8, …). It pushes anything still unpublished first, then tags the current state as a snapshot. GitM shows a confirmation box listing what will be included before it cuts the snapshot.
Publish Snapshot is in the bottom bar's ⋯ overflow menu when Check In All is the primary action (i.e., when you have pending work). When the repository is already clean, Publish Snapshot becomes the primary button.
A snapshot captures every tracked bucket, not just source files — derived exports, documents, images, and library reference parts are all part of the release bundle (gitignored junk is not). When you Publish Snapshot, GitM sweeps in pending output/document changes (including newly added ones) automatically; only brand-new source parts still need an explicit Check In first, so they get a part number. The confirmation box shows a per-bucket breakdown of what will be included.
Cut snapshots deliberately and sparingly — they're milestones, not a record of every edit.
Version coordinates: Cx and Lx¶
Each file row shows where that file currently is on its own timeline:
- Cx — the cloud version you're on (e.g. C3 = the 3rd distinct published version of this file). A "version" is a distinct content state, so a file carried forward unchanged through a later snapshot does not gain a new number.
- Lx — local versions stacked on top, if any (e.g. C3 · L2 = two unpublished local versions on top of cloud version 3).
To see a file's full timeline, right-click it → Show Versions. The overlay lists every cloud and local version with a Restore action per version. See Open an earlier version.
The Snapshots tab¶
The Snapshots tab lists published snapshots, newest first, each with its author, time, description, and a short commit id. From a snapshot you can:
- Restore this Snapshot — reset your whole working project back to that snapshot, to review it or carry on from it.
- GitHub — open that snapshot's commit on github.com.
The amber banner at the top ("💾 …") appears when you have local versions not yet published.
The Snapshots tab is whole-repo only. To look at one old version of a single file, use the file's right-click Show Versions instead — see Open an earlier version.
Restoring: two scopes¶
Restore is non-destructive — it never rewrites history. It brings files back into your working project; you move forward by checking in or publishing again.
- Restore this Snapshot (Snapshots tab) — resets your whole project to that snapshot. Because a snapshot covers every bucket, this reverts documents, drawings, derived exports, and images too — not only source files. GitM shows a per-bucket summary of what will change before you confirm.
- Restore a single version (per-file Versions overlay) — brings back just that one file, leaving everything else untouched.
Get Latest pulls the published state, not just snapshots¶
Get Latest brings down the newest published state of the repository — that includes everyday per-file check-ins, not only snapshots. Snapshots are milestone markers on top of that state, not the unit of transfer.
Snapshots and GitMCloud¶
Each snapshot is recorded in the repository's .gitm/builds.jsonl, which the GitMCloud
viewer reads to show snapshot history in the browser without SolidWorks. GitMCloud also shows
the read-only Cx cloud-version badge per file. Because snapshots are now deliberate, the
GitMCloud Snapshots list shows fewer, more meaningful entries than a per-edit log.
This viewer requires GitMCloud — see GitMCloud docs.
Known limitations¶
- Local versions are fragile by nature. They live only on your machine until published. A machine loss loses unpublished local versions.
- Restoring changes your working files. Read Open an earlier version before using Restore so you understand what it touches.
- History is shown linearized (newest-first list), not as a full branch graph.