Remote repos over SSH

Mergepond opens repositories that live on another machine over SSH: a dev box, a build server, a Linux VM. Git runs there, on the files that are there. Nothing is cloned or synced to your Mac. The window works the same as for a local repo.

Where to find it

File › Open Repository…, or ⌘O, then type host:path.
Sidebar › Remote hosts: the hosts you have connected to, each with its repositories.
Empty window › Open repository….
From a shell: mergepond dev-box:~/src/api.

A repository on dev-box open in Mergepond, with the host listed under Remote hosts in the sidebar.

The Open sheet

The sheet is headed "Open a repository" with the line "Type a path on this Mac, or host:path for a machine you reach over SSH." Its field takes either, with the placeholder ~/src/api or dev-box:~/src/infra.

You type	Mergepond opens
`~/src/api` or `/Users/you/src/api`	A folder on this Mac.
`dev-box:~/src/api`	`~/src/api` on the host `dev-box`.
`dev-box:src/api`	A relative path, taken from the SSH user's home: `~/src/api`.
`dev-box:`	The SSH user's home folder.
`alice@dev-box:~/src/api`	The same, as a different user.
`ssh://dev-box/~/src/api`	The same, in URL form.

HTTP URLs and Windows drive paths are rejected. As you type a host, the hint under the field reads "Opens path on host, already connected." or "…, connecting over SSH as you."

Under the field is Hosts from ~/.ssh/config: every Host alias in your SSH config (and files it Includes), with its user@hostname and a Connected mark where a connection is open. Click one to fill the field. Wildcard entries (*, ?, !) and Match blocks are skipped. If the config has no hosts, the sheet says "There are no hosts in ~/.ssh/config. Type user@host:path to reach any machine."

A note explains the first connection: "On first connect Mergepond copies pond-agent to the host. It runs Git there as your SSH user and opens no ports." See The remote helper.

Buttons: Choose folder… (a Finder picker for local repos), Cancel, and Open repository, which reads "Connecting…" then "Opening…" while it works.

How a connection is made

Mergepond uses your system ssh, so your SSH config, keys, agent and jump hosts apply exactly as in Terminal. It runs ssh -T with BatchMode=yes (so it never prompts for a password; set up a key first), a 10 second connect timeout, and keep-alives every 15 seconds. One connection is opened per host and shared by every repository on it. Only one host connects at a time.

On connect Mergepond checks the host's OS and architecture with uname -sm, looks for the helper under ~/.mergepond/agent/, uploads it if it isn't there or is a different version, and starts it. Linux and macOS on x86_64 and ARM are supported.

Error	What it means
Couldn't connect to host: …	SSH failed. The rest of the line is SSH's own message.
Git isn't installed on host. Install it there and try again.	The helper started but found no `git`.
Mergepond can't open repositories on host (uname): it supports Linux and macOS on x86_64 and ARM.	Unsupported platform.
pond-agent X on host speaks protocol N, Mergepond Y needs M.	A helper from another Mergepond version is running. Reconnecting replaces it.
The connection to host closed.	The SSH session dropped (sleep, a network change, a reboot). Windows showing that host's repositories refresh, which reconnects or shows why it can't, and the open repositories are watched again.

Working with a remote repository

Everything on the History, Changes and Worktrees tabs works as it does locally; Git runs on the host. A few things differ:

The repository tab and the switcher prefix the name with the host: "dev-box: api".
Repository › Open in Terminal opens a Terminal window that runs ssh -t host and changes into the folder.
Repository › Show in Finder says "That folder is on host, so Finder can't show it. Open it in Terminal instead."
Worktree removal on a remote repository uses git worktree remove rather than the local trash folder.
File changes are noticed by polling on the host every two seconds, not by a file watcher.

Sidebar › Remote hosts lists every host you have connected to, with a dot that reads Connected or Not connected, and the repositories opened on it underneath. Right-click a host for Open a repository on host… and Disconnect. Disconnecting closes the SSH session; the helper on the host exits when its connection ends.

Workspace rules can match on SSH host, so repositories on dev-box can all land in one workspace. See Workspaces and windows.