Skip to content

zordon.work, zordon.mod and zordon.lock

Three small files decide where the code behind a remote import comes from. An import in an Alphasfile says what a stack uses; a require in zordon.mod, or in a file with no zordon.mod above it, says which version of a repository.

file lives committed written by
zordon.work anywhere above the working directory never you
zordon.mod at the root of a module: a repository or directory that holds one or more Alphasfiles yes the module's authors; zordon pkg get adds requires to an existing one
zordon.lock next to the entrypoint Alphasfile yes zordon

zordon.work

search "~/code/infra" {}
search "../checkouts" {}
rule behavior
content search "<dir>" {} blocks only; any other block or attribute is an error
directory absolute, ~/, or relative to the file's own directory; must exist
discovery zordon walks the physical path of the working directory, symlinks resolved, up to the filesystem root
more than one file an error that lists every zordon.work found on the way
repeated entry an error naming both entries
match by zordon.mod a directory whose zordon.mod (at the directory root or in a matching subpath directory) has a module that is a prefix of the import identity provides it; the rest of the identity is the path inside that module directory
match by layout a directory holding <host>/<owner>/<repo>/<path> for the imported identity provides it
two matching entries an error that lists both and says which rule matched
version the ref of the require is ignored; the directory's current files are used; the require is still needed
lock a search-resolved repository is not added to zordon.lock; a pin it already has stays untouched
unmatched entry ignored

zordon.mod

module = "github.com/acme/stack"

require "github.com/acme/infra" {
  ref = "v1.4.0"
}
rule behavior
content one attribute, module, and any number of require blocks
module a repository identity on github.com, gitlab.com or bitbucket.org, optionally followed by a path inside it; makes the directory match search entries by identity
require "<repo>[/<path>]" { ref = "<ref>" } the version of a repository or a subpath inside it that files of this module import, matched by longest prefix; the ref is a branch, a tag or a commit
scope every file below the zordon.mod up to the next one; inside a remote checkout the search stops at the checkout's root
file-level require an error in any file below a zordon.mod; a file with no zordon.mod above it declares its requires itself
repeated require an error naming both
dependencies zordon.mod pins versions only; imports in Alphasfiles say what is used

zordon.lock

# Generated by zordon. Commit it; `zordon pkg update` moves the pins.

repo "github.com/acme/infra" {
  ref    = "main"
  commit = "3fa7dbb8c2f3d539f6581087d94c9be899c88e1d"
}

source "github.com/acme/ui" {
  ref    = "HEAD"
  commit = "9b1e0f4c27d6a8e35f0c4b2d7a91e6c3f58d2b40"
}
rule behavior
key one repo block per repository that a loaded file imports remotely, including imports of modules outside the stack
missing entry zordon fetches the repository, resolves the ref, and adds the entry
changed ref a require that names another ref than the entry resolves again and replaces the entry
same ref the locked commit is used even if the branch moved; its checkout is reused without the network
zordon pkg update re-resolves every repository the stack imports, or only the named ones, to the newest commit of its ref, and prints what moved or that the lock is up to date
zordon start --pull=pkg does what zordon pkg update does for the invocation's Alphasfile, then starts
which lock only the entrypoint's lock is read; locks inside imported repositories are ignored
rewrite when an entry is added or moved, zordon rewrites the lock with only the repo entries this load used, sorted by repository; source entries are kept
source one block per repository and ref that a started service's git {} follows: one with a branch, or none and so the default branch, written HEAD; a source pinned by tag or rev needs no entry
missing source entry zordon start resolves the ref and adds the entry
locked source a service that was not picked into a workspace is cloned at the locked commit, so its code changes only when the lock does; services that build from one repository and ref share the entry; a picked or src {} checkout is yours and is never moved
zordon start --pull=srv moves the source entry of every service it starts to the newest commit of its ref; --pull=all, or a bare --pull, does that and --pull=pkg
behind zordon start counts, for every repo and source pin of each level it starts, the commits the ref has that the pin does not, in the bare clone and without the network, so the count is as of the last fetch of that repository: one by --pull, by a missing pin, or by a picked checkout
behind in status zordon status shows behind <ref> by <n> (fetched <time>) next to the pin; --format=json and --format=agent report it as behind and behind_ref on the service and as pins of the stack, which lists only what is behind; a repository never fetched, or a commit it has not fetched yet, is left out
concurrent starts every workspace of a project shares its zordon.lock; zordon serializes reading and rewriting it with a lock under $ZORDON_HOME/locks, so one start never drops another's pin

Checkouts live in $ZORDON_HOME/mod/<host>/<owner>/<repo>@<commit>. Host-wide advisory locks live in $ZORDON_HOME/locks/ (pins-<hash>.lock for zordon.lock updates, repo-<repo>.lock for bare repository fetches, mise.lock and tool-<tool>-<version>.lock for toolchain installs, and port-<port>.lock for ports reserved by zordon start and held by alpha).

See Remote imports for the import syntax, Use a package from another repository and Develop a dependency locally.