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` module is a prefix of the import identity provides it; the rest of the identity is the path inside the 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>" { ref = "<ref>" }`	the version of a repository that files of this module import; the label is the repository alone, the ref 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"
}

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
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 entries this load used, sorted by repository

Checkouts live in $ZORDON_HOME/mod/<host>/<owner>/<repo>@<commit>.

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