swarmops git export#

Send the store's history to git: every commit of --ref's history that the last export into --branch does not reach is written into the git repository at PATH, parents first, made durable, and --branch moves to the export of --ref's head, created if it does not exist.

The repository is written on this host, at PATH, relative to the working directory: a bare repository (git init --bare makes one), or a work tree, which holds .git and whose checked-out branch is refused (E_INVALID_ARG). A changeset imported from git exports to the commit it came from, byte for byte; one made in the store exports to a commit with its own signatures and SwarmOps-* trailers, the same commit every time. Run again, it writes only what the branch does not reach, and nothing when the branch is at the export of --ref's head. It needs no identity.

A branch at a commit that is no export of --ref's head or of an ancestor of it fails with E_GIT_EXPORT_DIVERGED (exit 3), details.reason saying why, and nothing is written; --force moves it all the same, still by compare-and-swap. Then git push sends the branch on.

Syntax#

swarmops git export [OPTIONS] <PATH>

Required arguments#

Optional arguments#

The command also takes the global options.

Examples#

swarmops --repo [tmp]/store git export [git]

{
  "ok": true,
  "op": "git_export",
  "api": 1,
  "result": {
    "exported": 1,
    "objects_written": 3,
    "head_changeset": "[c1]",
    "head_sha": "[id2]",
    "branch": "main",
    "branch_moved": true,
    "incremental": false,
    "rewritten": 0
  },
  "meta": {
    "repo": "[tmp]/store",
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {
      "main": "[c1]"
    },
    "auth": "trust"
  }
}

Details#

What a run does#

git export is a client-side command: it reads the store that --repo (else SWARMOPS_REPO) names and writes a git repository on this host. No server ever sees the request, and there is no MCP tool for it. A run goes in this order, each step done before anything of the next is written:

1. Check the names. --ref must be a ref name of the store (main or release/<name>), checked before the repository is opened. The repository is opened as the import opens one (isolated from global configuration and GIT_* variables, the same repositories refused), and --branch must be a branch name git takes.
2. Refuse a checked-out branch. In a work tree, the branch its HEAD names is refused with E_INVALID_ARG (exit 2, details.reason checked_out), with or without --force, before the store is read.
3. Read the head. The head of --ref is read in a committed snapshot, taken under the store's writer lock after the journal's tail check, so that nothing the export sends off the host can be taken back by a power loss or a failed sync.
4. Derive the export ids. The commit id each changeset exports to is derived from the store's own objects, for the head and the whole history below it.
5. Compare with the branch. A branch at the head's export is up to date, and nothing is written. A branch that exists must name the export of the head or of an ancestor of it, the base; anything else is E_GIT_EXPORT_DIVERGED, unless --force.
6. Write. The commits the branch does not reach, parents first; for each, the trees and blobs its first parent does not hold at the same path, then the commit. An object the repository holds in a pack is trusted; a loose one is read back, and written again if it is damaged.
7. Make it durable. Every object written or read back is fsynced.
8. Record. The ids of the commits made in the store go into the store's external id index, each naming its changeset.
9. Move the branch. The branch moves to the head's export by compare-and-swap, through git's own lock file refs/heads/<branch>.lock, or is created.

What the store records#

Nothing in its history. An export writes no journal frame, so it needs no identity, does not show in op log, and the page's metadata says mutates: false. Its writes to the store are two caches, the derived values and the external id entries. meta.resolved names the head the source ref held, under the ref's name, on success and on a divergence; meta.recovered says what the snapshot's tail check repaired, on success only.

Choose the source: --ref#

The store ref whose history goes out, main by default, or release/<name>. A ref the store does not have fails with E_REV_NOT_FOUND (exit 6), whose hint lists the refs; a name that is no ref name, such as feature/x, with E_REF_NAME_INVALID (exit 1).

Choose the branch: --branch#

The git branch written, refs/heads/<BRANCH>, main by default; name it after the remote's trunk (--branch stable), or after a branch that waits for review (--branch review). A branch that does not exist is created, and incremental is false. A name git does not take, such as a..b, fails with E_REF_NAME_INVALID, whose hint is git check-ref-format --branch <name>.

The repository must exist already: a path with no repository is E_GIT_NOT_A_REPO (exit 6), whose hint is git init --bare <path>. A bare repository has no checked-out branch, so it is the one to export into.

Replace a diverged branch: --force#

--force moves a branch that diverged all the same, replacing what git holds there, and adds a warning that says so (the branch <name> had diverged (<reason>), and the export moved it all the same). The move is still a compare-and-swap against the commit the export read, so a branch another writer moves meanwhile still stops it (moved_during_export). When the divergence found the branch at the export of a changeset of the history, the export goes on from there, writes only what the branch lacks and reports incremental: true.

--force never moves a checked-out branch, and does nothing for an E_GIT_WRITE.

What git gets#

• An imported changeset exports to the commit it came from, byte for byte, as long as nothing below it was imported with a loss.
• A changeset made in the store exports to a commit with its own author and committer, named <family>/<instance> with the address <instance>@<family>.swarmops.local, and a trailer block after its message: SwarmOps-Changeset: with the changeset's id, then SwarmOps-Land-Key: and SwarmOps-Squashed-From: for a landed change. The same store gives the same commit every time.
• A history imported with a loss exports as new commits, from the first lossy commit up: rewritten counts them, a warning says so, and the signature headers they keep no longer verify.

What git gets shows such a commit in git log.

Run it again#

The export is incremental: run again, it writes only what the branch's last export does not reach. With nothing new it writes nothing: exported 0, objects_written 0, branch_moved false.

exported counts the commits written that the repository did not hold, so exporting a history the repository holds already into a new branch writes no object and only creates the branch.

When the branch diverged#

E_GIT_EXPORT_DIVERGED (exit 3) means the branch names something other than the export of the head or of an ancestor of it. Nothing is written. details give the reason, the branch, the commit it names (git_head), the source's head (head_changeset) and, for branch_ahead, both_moved and source_moved_back, the changeset whose export the branch holds (exported_changeset). The hint is the next step:

Patterns#

Export to an empty repository. Make a bare one, export, and check it with git:

git init --bare ~/src/mirror.git
swarmops git export ~/src/mirror.git
git -C ~/src/mirror.git fsck --strict --no-dangling

Send landed work to review. Export into a branch of its own, push it, and move the trunk with git once the review passes (the daily loop):

swarmops git export ~/src/acme.git --ref main --branch review
git -C ~/src/acme.git push origin review

Continue a branch that people also push to. Fetch and import before agents land more, so that the next export continues the branch; when it stops with branch_ahead, run the import its hint names, then export again.

Undo a landed change, in git too. After swarmops op undo takes main back, the export stops with source_moved_back; --force moves the branch back to the export of the new head, and the push after it must be forced too.

Concurrency and interruptions#

• Agents. The committed snapshot is taken under the store's writer lock, so an export waits behind committing agents as a writer does, and past the lock's timeout fails with E_BUSY (exit 4, retryable). Agents commit while it writes git: the export sends the head it read.
• Git. The branch moves through refs/heads/<branch>.lock. A lock file that is there already is E_GIT_WRITE with details.reason ref_locked: another git process holds it, or an export that died left it. Remove it once no git process runs (known limitations).
• A cut-short export leaves loose objects that no branch reaches. The same export run again reads them back, writes again any that is damaged, and writes only what is still missing.

Failure cases#

Cost#

Each object an export writes is a loose file, fsynced on its own, so the first export of a long history writes one file and one fsync per object until git gc packs them. Every export, an incremental one included, derives the export id of each changeset below the head again from the store's objects. Known limitations gives both costs; the performance ledger has no measurement of the export yet.

Go further#

• Keep git: import, land and export runs the round trip, and When an export stops walks through branch_ahead.
• One writer per trunk keeps the review branch and the trunk apart.
• The git side says what to watch.
• Git export in the architecture overview walks through each step.

Return information#

result is a GitExportResp (swarmops schema GitExportResp prints its JSON Schema).

Envelope op: git_export.

Exit codes:

• 0: Success.
• 1: The operation failed.
• 3: The change conflicts with what it lands on: resolve it, then run the operation again.

Errors#

• E_GIT_EXPORT_DIVERGED (exit 3): git export: the branch holds commits that are not the export of the source ref's head or of an ancestor of it, so the branch did not move; there is no silent merge, and the request's force moves it anyway.
• E_GIT_WRITE (exit 1): git export could not write the repository; details.reason says what failed: io (the filesystem refused a write; details.path names the file, relative to the git directory), ref_locked (the branch's lock file, refs/heads/<branch>.lock, exists: another git process holds it, or an earlier export died holding it, and git itself says to remove it once no git process runs; details.path names it) or ref_name_conflict (an existing ref stands where the branch's name needs a directory, or the other way round; details.branch).

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).

See also#

• Operating SwarmOps: Send it to git for review
• swarmops git import
• CLI reference
• Error codes