Git and Swarmfile
Swarmfile isn't a git host, and it isn't a git front-end. But plenty of teams that use it live in git too, so there are three separate ways the two meet. They solve different problems, and you can use any combination:
| What it's for | Where your source lives | |
|---|---|---|
| Swarmfile as your git-LFS server | Keep your repo on GitHub/GitLab/your own git host; send the big binary files to Swarmfile. | Your git host |
git clone swarmfile:// | Get a real git repository of a Swarmfile project, for git tooling, CI, or an offline archive, and push commits back. | Swarmfile (the mounted drive) |
The swarmfile CLI's git-style commands | Do version control on the mounted drive with the verbs you already know. | Swarmfile (the mounted drive) |
1. Swarmfile as your git-LFS server#
Point git-LFS at a Swarmfile project, and git lfs push/pull move your large files through Swarmfile while everything else stays in your existing git host. You get storage, deduplication and quota without bloating the host, pushes up to 256 GiB per object with the transfer agent, git lfs lock that is the same lock as a lock on the drive, and an exit with no lock-in: git lfs fetch --all with stock git-LFS pulls everything back. Pushed objects can also be reflected onto the mounted drive as ordinary files.
Encryption at rest depends on the upload path: objects uploaded directly by the stock git-LFS client, and uploads of 64 MiB or more through the Desktop App's built-in agent, are stored without application-layer encryption, and git-LFS isn't available on end-to-end-encrypted projects.
Start with Git-LFS.
2. git clone of a Swarmfile project#
Once an owner turns on git access for a project, anyone who can read all of it can run:
git clone swarmfile://<org>/<project>
and get every branch and tag as real git history, with large files as LFS pointers served by Swarmfile. git fetch brings it up to date, and git push sends new commits back as Swarmfile commits with their git ids unchanged. Pushes are fast-forward only, a push to a protected branch opens a merge request instead, an existing repository can be pushed whole into a new project, and a pushed commit must look exactly like what a clone would produce (no executable bit, large files as LFS pointers) - the guide has the rules.
Start with Cloning a Project with Git.
3. The swarmfile CLI speaks git#
On the mounted drive, the swarmfile CLI uses git's vocabulary where the meaning carries over - and where it doesn't, it tells you instead of failing.
Commands that work the way you expect: commit (including --amend, message-only), log, show, diff, branch, switch, checkout, restore, revert, merge, tag, describe and more. Your ~/.gitconfig aliases work too (swarmfile co, swarmfile st). Coming from Git has the full cheat sheet.
Git habits that run the real thing:
| You type | It runs |
|---|---|
swarmfile add | Opens a changelist (if one isn't open), so your next saves are staged into it. |
swarmfile stash / stash push / stash save | Parks the open changelist (changelist park). |
swarmfile stash list / stash show | Lists parked work (changelist parked). |
swarmfile stash pop / stash apply | Resumes parked work (changelist resume). |
swarmfile stash drop / stash clear | Discards parked work (changelist discard), asking first. |
swarmfile reset --hard <rev> | swarmfile restore <rev> - one undoable commit, not a history rewrite. |
swarmfile clone <project-id> <path> | Opens a mount of that project at that path (-b <branch> pins a branch; --checkout writes a plain directory instead). |
Git habits that print guidance instead: push, pull, clone (with anything other than a project id and path), rebase, cherry-pick, rm, mv, cp, mkdir, touch, worktree, grep, init, remote, clean, reflog, mergetool, difftool, shortlog, submodule, bisect, gc, prune, fsck, archive and notes each print a one-line reason and what to do instead - push and pull explain that saves already sync, worktree points at swarmfile mounts open, grep at swarmfile-search, mergetool at swarmfile conflicts resolve --tool. These work even when the Desktop App isn't running. The CLI reference has the details.
Compatibility at a glance#
| You want to… | Today |
|---|---|
| Keep source in GitHub/GitLab and store big files in Swarmfile | Works - git-LFS server |
git lfs lock files, including files only in git | Works |
| Leave with all your LFS objects using stock git-LFS | Works - git lfs fetch --all |
git clone a Swarmfile project | Works, once git access is on for the project - guide |
git fetch / git pull new commits into that clone | Works, incrementally |
git clone --depth N (shallow) | Works, once the project's commits are indexed; --shallow-since/--shallow-exclude don't |
git push to a Swarmfile project | Works, fast-forward only, on managed and unencrypted projects - rules: deleting a branch archives it, lightweight tags become Swarmfile tags (--force moves one and :refs/tags/<tag> deletes one, unless a release was published from it), a push to a protected branch opens a merge request, and an existing repository can be pushed into a new project in batches of up to 100 commits; force pushes to a branch and annotated tags are refused |
Partial clone (--filter) | Not supported - large files already arrive as LFS pointers |
| Clone over an HTTPS URL | Not supported - use swarmfile:// |
| Clone an end-to-end-encrypted project | Not yet - mount it, or use swarmfile materialize |
| Fetch an arbitrary commit by id | Not supported - branches and tags only |
| Executable bit and empty folders in a clone | Not carried - every file arrives non-executable; empty folders are dropped |
| Submodules | Not supported in Swarmfile's own version control - swarmfile submodule prints guidance |
| Rebase, cherry-pick, history rewriting | Not supported by design - Swarmfile never rewrites commits; commit --amend changes only the message |
Which one should I use?#
- Your source code already lives in git and you're happy with that → the git-LFS server on-ramp. Nothing about your workflow changes except where big files go.
- Your project lives on the Swarmfile drive, and some tool needs a git repository →
git clone swarmfile://. - You're doing version control on the drive and your fingers type git → the CLI, with Coming from Git open in a tab.
- CI that builds from a branch → you may not need a clone at all: Runner (Headless CI) runs jobs against a branch directly, and
swarmfile materializewrites any ref to a plain directory.