Coming from Git

If you know Git, you already know most of Swarmfile. The vocabulary is deliberately familiar - commit, branch, merge, log, revert, tag all mean what you expect. This page maps your Git habits onto Swarmfile and, more importantly, flags the few places where the mental model genuinely differs.

Swarmfile is its own tool, not a Git front-end. But the instincts carry over, and where a Git command has no equivalent, typing it anyway prints a one-line pointer instead of an error - so you can learn by doing.

The one big shift: mount instead of clone, and no save step#

This is the whole difference in two sentences:

Your project is a live mounted drive, not a cloned copy. For day-to-day work there's nothing to clone, pull, or push. Files stream from the cloud on demand; you open and save them like any local file, and other people's changes appear as you read. (When you genuinely want a git repository of a project - for git tooling, a build that expects one, or an offline archive - an owner can turn on git access and you can git clone it, and even git push commits back to it. The drive stays where day-to-day work happens.)
Saving is automatic. There's no add / commit / push ceremony to make your work durable and shared - the moment you save, it starts syncing. Git fuses saving and naming into one mandatory step; Swarmfile splits them, so naming a commit is optional, and you can do it whenever - even after the fact.

Everything below follows from those two facts.

Cheat sheet#

In Git	In Swarmfile	Notes
`git clone <url>`	(nothing) - just mount · or `git clone swarmfile://<org>/<project>`	Projects appear as a mounted drive once the app is running; `swarmfile status` shows where it's mounted. If the project has git access turned on, `git clone swarmfile://…` gives you a real git repository of it - see Cloning a Project with Git.
`git pull` / `git fetch`	(nothing) - or `git fetch` in a `swarmfile://` clone	The drive is live - a teammate's changes appear as you open files. `swarmfile log` shows recent commits. Note `swarmfile fetch` is not Git's fetch: it pulls a byte range of one file (including one still uploading).
`git push`	(nothing) - or `git push` from a `swarmfile://` clone	Saves stream to the cloud automatically. `swarmfile status` shows what's still uploading. A git clone of a git-enabled project can push commits back, fast-forward only.
`git add <path>`	`swarmfile add` (opens a changelist if none)	No staging for everyday work - just save. `add` is idempotent: it opens a changelist so subsequent saves stage into it (and this mount stays in staged mode until you `commit`), and it exits 1 on a path that doesn't resolve. For a deliberate multi-file batch that lands all at once, see Version Control.
`git commit -m "…"`	`swarmfile commit -m "…"`	Names a specific save. You don't have to - unnamed autosave commits happen for you as you work.
`git commit --amend -m "…"`	`swarmfile commit --amend -m "…"`	Renames the most recent commit. Message-only and non-destructive - contents and history are untouched (Swarmfile never rewrites commits).
`git status`	`swarmfile status` (mount/engine) · `swarmfile changelist status` (staged) · `swarmfile diff` (branch vs base)	`swarmfile status` is not Git's working-tree status - it reports the mount, peers, and settings. There's no "modified but unsaved" state to show: saves sync immediately. Use `changelist status` for staged work and `conflicts` for blocked files.
`git log`	`swarmfile log`	Compact, `--oneline`-style feed.
`git show <commit>`	`swarmfile show <N>`	Whole-file: shows which files changed (A/M/D/R), not a line diff - Swarmfile versions binaries.
`git diff main...`	`swarmfile diff [<branch>]`	Previews what a branch would merge into its base - files added/modified/deleted/renamed, plus conflicts. Whole-file (no line diff).
`git diff A B`	`swarmfile diff <A> <B>`	Files changed between two commits (each a number, `HEAD~N`, tag, or branch). Whole-file.
`git blame <file>`	`swarmfile blame <path>`	Who last changed the file + its version history with authors - one row per saved version, not per line.
`git switch <branch>`	`swarmfile switch <branch>`	Hot, in-process - no restart.
`git checkout <branch>`	`swarmfile switch <branch>`	`swarmfile checkout <branch>` also works (it's a shim); `switch` is clearer.
`git checkout -b <name>` / `git switch -c <name>`	`swarmfile checkout -b <name>` / `swarmfile switch -c <name>`	Creates the branch (forked from your current one - or, like git, from `checkout -b <name> <start-point>`) and switches to it in one step.
`git restore <path>` / `git checkout <commit> -- <path>`	`swarmfile restore <N> --path <path>`	Rolls a file, folder, or the whole project back to a past commit, landed as one undoable commit.
`git revert <commit>`	`swarmfile revert <N>`	Lands a new commit undoing an old one. Non-destructive and itself undoable.
`git branch`	`swarmfile branch list`
`git branch --merged`	`swarmfile branch merged`	Branches with nothing left to land (branch-vs-base diff empty); `swarmfile branch prune` archives them after confirming, and never archives a branch an open mount on this machine is working on.
`git add --resolved` (staging resolved conflicts)	`conflicts resolve <path> --auto`, `--winner S`, `--tool`	There's no index to stage into, and a conflicted file can't be saved until it's resolved - so a leftover-marker commit can't happen. Resolve, then saves sync. `--auto` already refuses (exit 2) if a merge leaves a real conflict.
`git tag <name>`	`swarmfile tag create <name>`	An immutable, named pointer to a commit - handy for "branch from here later."
`git merge`	`swarmfile merge`, or a merge request: `swarmfile mr create`	Whole-file merge with conflict detection. See Branches & Merging.
`git mergetool`	`swarmfile conflicts resolve <path> --tool`	Uses your git mergetool configuration, unless a `mergetool_cmd` is set in the engine's own config - that takes precedence over git config.
(auto-merge)	`swarmfile conflicts resolve <path> --auto`	Let the engine merge it (diff3 for text) with no external tool - exits 2 if a real conflict remains, so a script can fall back. `--all --auto` sweeps every conflicted file in one pass.
`git rm <path>`	(do it on the drive)	Delete the file on the mounted drive; it syncs like any other save and lands in Trash.
`git mv <a> <b>`	(do it on the drive)	Rename/move on the mounted drive. The entry keeps its id, so history, comments, and locks move with it.
`git worktree add`	`swarmfile mounts open <path>`	One engine can hold several full mounts at once - the reason you reached for a worktree. Use `--project <id>` for a different project (same org).
`git grep`	`swarmfile-search`	Project-content search lives in the standalone binary (or the dashboard's search box).
`git clean -fd`	(nothing needed)	Ignored paths are already kept off the hub. To remove content that synced before a rule existed, use `swarmfile ignore-clean`.
`git reflog`	`swarmfile log` / `swarmfile activity list`	History isn't rewritten, so there's no reflog - `log` lists commits, `activity` shows who changed what and when.
`git init` / `git remote`	(nothing)	There's no repo to initialize and no remotes - the drive is the project.
`.gitignore`	`.gitignore` / `.swarmfileignore`	Honored on sync. See Sync Exclusions.

<N> is a commit number - the #N shown by swarmfile log. Anywhere a commit is expected (show, restore, revert, describe, checkout <commit>) you can also use HEAD, HEAD~N / HEAD^ (N commits back), a tag name, a branch name (its head), a changeset id, or a 64-hex commit hash - just like Git. A seq:/head:/branch:/tag:/changeset:/hash: prefix forces which kind is meant.

log is per-branch, and shows a branch's own commits. swarmfile log (and HEAD/HEAD~N) reflect the branch this mount is on. Note one difference from Git: a branch's log shows the commits made on that branch since it forked - not the shared history from before the fork point. Switch to main to see the mainline history.

Your Git aliases work. If your ~/.gitconfig defines [alias] co = checkout, st = status, etc., swarmfile co / swarmfile st expand the same way - Swarmfile reads your git aliases for any command name it doesn't already have.

Three habits to unlearn#

Don't reach for add / commit / push to "save and share." Just save the file. It's durable and syncing before you'd have finished typing git add.
Don't clone or pull to get to work. The drive is the project, always current. swarmfile status tells you where it's mounted and what's in flight. A git clone of a git-enabled project is there for git tooling, archives and git-based workflows; it can push commits back, but it isn't the live drive.
You don't have to name a commit when you make it. Work all day; name the moments that matter afterward (see below). A blank autosave isn't a mistake - it's the default.

Naming work - now, or later#

Because saving and naming are separate, you have three ways to put a name on history, and you can mix them freely:

Name as you go: swarmfile commit -m "Grade pass 2" files your recent saves under that message.
Name after the fact: swarmfile describe <N> -m "v2 delivery to client" names any past commit - including an autosave that landed with no message. swarmfile commit --amend -m "…" does the same for the most recent one. Both change only the message.
Mark a milestone: swarmfile tag create <name> pins an immutable, memorable name to a commit.

In the desktop app and the web dashboard, the same thing is a pencil/Add description on any commit row - no command needed.

The two commit modes (30-second version)#

Mode A (default, autosave): saves land as commits automatically; a burst of edits becomes one commit, the next burst another. You do nothing. This is what an office worker who's never heard of Git gets, and it's fine.
Mode B (explicit): open a changelist, stage a set of saves, and submit them as one atomic unit - the analog of the Git index, for work that only makes sense landing together.

They're not a setting you choose - open a changelist and you're in Mode B for those saves; otherwise you're in Mode A. Full detail in Version Control.

What genuinely has no equivalent#

git rebase / history rewriting - Swarmfile history is an append-only server-side DAG of whole-file commits. It isn't rewritten. To put a name on the past, use describe or tag.
git reset (index-moving forms) - swarmfile reset --hard <rev> does work, mapping to restore <rev>. But bare reset, --soft/--mixed, and reset <path> have no equivalent: saves sync immediately, so there's no unstaged state to move. To undo, land a revert (undo one commit) or a restore (roll a scope back to a point in time) - both move history forward rather than erasing it.
git stash - actually maps onto Swarmfile's parked work: swarmfile stash runs changelist park (set staged work aside, kept on the hub), stash pop resumes it, stash list/show lists it, stash drop discards it. Parked work is a set, not a stack - pop restores all parked work for the branch, and a bare drop discards all of it, so it asks first; stash list numbers the entries and stash drop stash@{1} (or drop 1) discards just that one. In-progress saves are already auto-saved, so there's nothing lost either way.
File plumbing (rm, mv, cp, mkdir, touch) and grep - these aren't CLI verbs. You do file operations on the mounted drive itself, and content search is swarmfile-search.

Type any of these (swarmfile rebase, swarmfile rm, swarmfile worktree, swarmfile shortlog, swarmfile fsck, …) and Swarmfile will print the one-line reason and the thing to do instead. (swarmfile add, swarmfile stash, and swarmfile reset --hard <rev> don't just explain - they run the mapped command.)

The on-ramp: bring the git you already use (git-LFS)#

For the side-by-side of every way git and Swarmfile meet - git-LFS, git clone swarmfile://, and the CLI's git-style commands - see Git and Swarmfile.

You don't have to move a whole team at once. Step one is to keep your source in the git you use today - GitHub/GitLab/self-hosted - and route only the large binary assets to Swarmfile, where Swarmfile acts as a git-LFS server: the big files get real storage, dedup, encryption (on most upload paths - see the caveat below), and quota instead of bloating your git host.

In the dashboard, open your project → git-LFS tab → Generate git-LFS credential.
Commit the .lfsconfig it shows to your repo.
Run the setup commands it shows once in your working copy (they store the credential and force basic auth).

After that, git lfs push / pull / checkout move big files through Swarmfile with no change to your VCS or workflow. git-LFS works on managed-key and unencrypted projects; it isn't available on end-to-end encrypted projects (a plain git-lfs client can't hold the per-user key).

A few things worth knowing up front (all covered in the Git-LFS guide):

Pushes over ~100 MB - which stock git-LFS can't send through our network edge in one request - work once the small transfer agent is installed; it ships with the desktop app, or install it standalone on a machine without one. Up to 256 GiB per object. Pulls of any size need no agent.
Locking - git lfs lock / unlock / locks work, including for files that live only in git and were never written to the drive.
No lock-in - git lfs fetch --all pulls every object back with stock git-LFS and no Swarmfile software, so you can repoint .lfsconfig at any other LFS host and leave. Your source was never in Swarmfile to begin with.
Onto the drive - run swarmfile-lfs reflect after a push to have those pushed objects appear as first-class files on the mounted Swarmfile drive (reusing the uploaded blocks, no second copy).
Encryption posture - git-LFS is the one surface where a managed project can hold plaintext by design: a stock git-lfs push (presigned direct PUT) and the desktop agent's ≥ 64 MiB multipart path store plaintext; the chunked block paths (the agents' ordinary-size uploads, and the standalone agent generally) are encrypted. The guide has the full path-by-path table.
GitHub, a little more automatic - on a GitHub remote, the git-LFS tab can install the Swarmfile GitHub App, open the .lfsconfig pull request for you, and reflect each push onto the drive without a local reflect (rolling out per deployment).

The bridge is where you start, not where you stop. The fuller destination is making Swarmfile the home for the whole project: native version control - branch, merge, history and rollback - over a drive you mount and open files from, so nothing has to live behind a clone. Move at your own pace; the LFS on-ramp buys you the storage win today.