# 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`](https://swarmfile.com/docs/cli/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

```bash
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`](https://swarmfile.com/docs/cli/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](https://swarmfile.com/docs/guides/git-clone) and [Git and Swarmfile](https://swarmfile.com/docs/guides/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.