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