git-remote-swarmfile

git-remote-swarmfile is the small git remote helper behind git clone, git fetch and git push on a swarmfile:// URL. Git invokes it by name whenever it sees a swarmfile:// remote, so you never run it yourself; it re-execs the engine binary in git-remote mode and needs no running engine, no drive and no mount.

Every desktop installer puts it on PATH beside swarmfile (on macOS, /usr/local/bin; on Linux, /usr/bin). There's no separate download. If git says it can't find a helper for swarmfile, use swarmfile git clone, which finds the helper next to the swarmfile binary even when it isn't on PATH. Git 2.11 or later is required.

How git uses it#

git clone swarmfile://<org>/<project>
git remote add origin swarmfile://<org>/<project>
git fetch origin
git push origin main

<project> may be a bare project name or a project id. A bare name is qualified with the configured organization by swarmfile git url / swarmfile git clone. Git access is turned on per project - from the web project menu, the Desktop App's Project settings → Git access, or swarmfile git enable - and a clone of a project that hasn't enabled it is refused with no_git_view; the org's owners are nudged once, and swarmfile git status shows where a project stands.

What it serves#

Shallow clones with --depth, fetches, fast-forward pushes (merges land on auto-archived merged/<sha> branches), lightweight tag moves and deletes, and chunked resumable pushes above 5,000 paths. Force push is refused by default - a clone can opt in with git config swarmfile.force-forward true to translate plain --force/--force-with-lease into a forward commit (the same end state swarmfile git force-forward lands); annotated tags, octopus merges, submodules, end-to-end-encrypted projects and HTTPS remotes are refused, and --shallow-since/--shallow-exclude aren't supported. The full list, and the version-control model around it, is in Clone and push with git and Git and Swarmfile.

Credentials#

The helper looks for, in order:

1. SWARMFILE_API_KEY in the environment. A project API key wins over everything else, including a Desktop App session, and the helper says so when both are present.
2. A Desktop App session stored by the engine.
3. A project API key in git's credential store, stored with git credential approve for the Swarmfile host.

When something goes wrong#

A failed helper always prints its reason above git's fatal: remote helper 'swarmfile' aborted session line, and writes the same text to git-remote-last-error.log in the Swarmfile cache directory (~/.cache/swarmfile on macOS and Linux, %LOCALAPPDATA%\Swarmfile on Windows). The message names who can fix it; include that log in a bug report.