Page kind: Reference
swarmops serve#
Serve the stores under --root to stock git: fetch, clone and push over ssh as a forced command, or over smart HTTP as a CGI program. One process per connection, no daemon.
Over ssh, an authorized_keys line runs it: command="swarmops serve --root /srv/so --as person/ada",restrict ssh-ed25519 .... The client's git-upload-pack '<store>.git' or git-receive-pack '<store>.git' (SSH_ORIGINAL_COMMAND) names a store by its directory under --root. With --cgi, a web server runs it for smart HTTP, its PATH_INFO starting with the store's name; TLS and authentication are the web server's.
The caller is named by --as alone, or with --cgi by --user-family <family> as <family>/$REMOTE_USER: the global --as default, $SWARMOPS_AGENT, does not apply to serve, nor does $SWARMOPS_RUN_ID, so that the serving account's environment names no caller. A connection that names none is refused with E_AUTH (details.reason no_identity), whatever it asks for. The store's access.toml grants read, push, force and land; a caller it names but does not grant is refused with E_POLICY_DENIED.
The branches are served as refs/heads/<name>, main among them, and the tags as refs/tags/<path>. A push moves a store ref by compare-and-swap: main only forward along first parents. A push with one refused ref is refused whole, inside git's quarantine: every ref gets pre-receive hook declined, a remote: line per ref says why, and no object of it enters serve.git. A push to refs/land/<target> lands its commits onto <target> as swarmops land does, and reports a conflict on git's remote: lines.
A refusal before git starts prints one ERR pkt-line on stdout, which git shows as remote error: <CODE>: <message>, and the envelope on stderr; with --cgi, a Status: header and the same text. --hook pre-receive and --hook proc-receive are the entries git runs inside a push, from the hook files serve writes; they take no --as. --stdio, the store-to-store sync, is not served yet.
A connection whose store has not moved since serve.git's last export takes no lock: git/serve.state names that export. serve --prepare makes serve.git ready for the store --repo names before a client connects, so that the connection finds it current and exports nothing; it needs no --root. With --seed-from <GIT_DIR>, the repository a git import read, it first fetches the imported commits' objects from it and packs them with a bitmap, so that the first clone after an import writes no object. --prepare-wait zero gives up at once when another refresh holds serve.git's lock, and marks it for that one to run again. It prints {"op": "serve_prepare", ...} on stdout, and exits 0 when it was skipped or found the lock held. Without the store's memo key, on a store whose main head is no imported commit, it exports nothing and warns: run it as the account the agents and serve run as.
- Group
server- Since
0.7.0- Mutates
- yes
- Identity required
- no
- MCP tool
- none
- Envelope op
serve- Exit codes
- 0
- Errors
- none
Syntax#
swarmops serve [OPTIONS] [GIT_ARGS]...Required arguments#
None.
Optional arguments#
The command also takes the global options.
Syntax: --root <DIR>.
The directory whose subdirectories are the stores served, each by its name.
Syntax: --cgi.
Serve one CGI request: smart HTTP behind a web server.
Syntax: --user-family <FAMILY>.
With --cgi: name the caller <FAMILY>/$REMOTE_USER, the user the web server authenticated.
Syntax: --hook <HOOK>.
Run as a hook git runs inside a push (pre-receive, proc-receive: from the hook files serve writes) or a fetch (pack-objects: from the setting serve gives git). Values: pre-receive: git's pre-receive: it refuses the whole push while its objects are quarantined; proc-receive: git's proc-receive: it decides each command of a push; pack-objects: git's pack-objects hook: it answers a fetch's pack from the pack cache.
Syntax: <GIT_ARGS>.
With --hook pack-objects: the pack-objects line git appends.
Syntax: --stdio.
Serve the store-to-store sync on stdin and stdout: not served yet.
Syntax: --prepare.
Make serve.git of the store --repo names ready before a client connects, then exit.
Syntax: --seed-from <GIT_DIR>.
With --prepare: the git repository an import read, to take the history's objects from.
Syntax: --prepare-wait <WAIT>.
Default: bounded.
With --prepare: how long to wait for serve.git's lock. Values: zero: Not at all: a held lock is marked for its holder to run again; bounded: As long as a refresh waits, then E_BUSY.
Examples#
No recorded example yet.
Return information#
swarmops serve prints no envelope on stdout, which carries git's protocol: a refusal before git starts is one ERR pkt-line there (with --cgi, a Status: header and its text), and the envelope goes to stderr, as for a command line it refuses.
Envelope op: serve.
Exit codes:
0: Success.
Errors#
No golden step shows this command failing yet.
Any command that opens a store may also fail with a store error, such as E_NOT_A_REPO, E_IO or E_STORE_CORRUPT; a command line the grammar refuses is E_INVALID_ARG (exit 2).