Version Control
Swarmfile versions every file the way a VCS versions code - except the files are whole binaries (video masters, CAD assemblies, GIS rasters) instead of text. There's no meaningful line-level diff for a 200GB ProRes file or a Revit model, so the model is built around whole-file commits and whole-file history instead of line hunks. If you're used to git or Perforce, the mental model carries over; the mechanics underneath don't.
Changesets#
A changeset is an atomic, named, revertable commit that can span multiple files, ordered in a DAG the same way git commits are. When a changeset lands, every file in it changes together or none of them do.
Swarmfile supports two ways of producing changesets, and you pick the one that matches how you work.
Mode A: auto-landed (default)#
By default, your saves land as commits automatically as you work. You don't open or close anything - edit a file in your native app, save it, and Swarmfile records a changeset for that save. This is the lower-friction mode and it's what most people want most of the time.
swarmfile commit -m "Color grade pass 2 on interview B-roll"
commit opens and submits a changeset in a single step - the Mode A pattern, useful when you want to attach a specific message to a specific save rather than relying on the automatic one.
Mode B: staged, explicit submit#
For work you want to land as one deliberate, reviewed unit - a multi-file asset swap, a batch of renders that only make sense together - open a changelist, stage saves into it, and submit (or cancel) the whole thing as one atomic transaction. It's the same shape as a git index: nothing is visible to teammates until you submit.
swarmfile changelist open -m "Swap all Act 2 plates to final grade"
# ...work happens, saves are staged into the open changelist...
swarmfile changelist status
swarmfile changelist submit
If you change your mind partway through, swarmfile changelist cancel discards the staged changes instead of submitting them.
Viewing history#
swarmfile changesets list shows the commit log, newest first. swarmfile log gives you the same history as a compact colored feed, closer to git log --oneline, when you just want a quick scan.
Checkout and restore#
swarmfile checkout --at-seq <N> restores a scope to how it looked at a past commit. The scope can be the whole project, a folder, or a single entry:
swarmfile checkout --at-seq 482 --path "Renders/Act2/final.mov"
This doesn't rewrite or destroy history - it creates a new commit that matches the old state and adds it to the log. If the restore turns out to be wrong, you can check out again to undo it; nothing is ever permanently lost by restoring.
Trash and per-file rollback#
Separate from the changeset system, every entry also has its own lightweight history: a per-user trash for soft-deleted files with a configurable retention window, and point-in-time rollback for individual files. It's simpler than a changeset - no multi-file atomicity, just "what did this one file look like at this timestamp." See Trash, History & Rollback for the full picture.
Where to go next#
- Branches & Merging covers forking a branch to isolate risky work and merging it back.
- CLI: swarmfile has the full command reference for
commit,changelist,changesets,log, andcheckout.