lang::lock

lang/src/lock.mo

typeGitPin#
pub type GitPin {
    tag (name : String),
    branch (name : String),
    rev (id : String),
    head,
}

What a git entry was asked to follow. head is the remote's default branch: a dependency that named no tag, branch or rev.

structLockedGit#
pub struct LockedGit {
    url : String,
    pin : GitPin,
    commit : String,
    /// The mote's directory inside the checkout. TOML text in the lock
    /// file; a `Path` once read, because that is what resolution joins.
    subdir : Option Path,
}

The git half of a lock entry. commit is always a full id: a tag or branch is resolved once, by monad fetch, and never moves afterwards.

structLockedMote#
pub struct LockedMote {
    name : String,
    version : String,
    checksum : String,
    git : Option LockedGit,
}

One [[mote]] entry. checksum is sha256:<hex> over the canonical tree digest of the mote's directory (ยง2b). git is none for a source that is not a git checkout.

structLockfile#
pub struct Lockfile {
    motes : List LockedMote,
}
typeLockRead#
pub type LockRead {
    loaded (lock : Lockfile),
    unsupported (version : I64),
}

A successfully read mote.lock: either one this reader understands, or the version it does not -- which the caller warns about and regenerates rather than failing on.

defLock.parse#
pub def parse (text : String) : Result String LockRead

Parse mote.lock text. err carries a message naming what is wrong.

defLock.subdir_path#
pub def subdir_path (o : Option String) : Option Path

A lock file's git_subdir is TOML text; this is the one conversion into a Path. Path.unsafe and not Path.of: an empty git_subdir parses today and must keep parsing (the renderer round-trips it), and a lockfile's subdir is validated where it is USED (Build.safe_subdir), not where it is read.

defLock.pin_of#
pub def pin_of (s : String) : Option GitPin

tag:<name> / branch:<name> / rev:<id> / head. An empty name is no pin at all, so it is rejected with the rest.

defLock.pin_to_string#
pub def pin_to_string (p : GitPin) : String

git_ref's spelling of a pin; the inverse of pin_of.

defLock.is_commit#
pub def is_commit (s : String) : Bool

SHA-1 repositories have 40-digit ids, SHA-256 ones 64. Public because build::git resolves a rev against exactly this rule -- one definition, so a commit the lock accepts is a commit the transport will look up.

defLock.render#
pub def render (lock : Lockfile) : String

The lockfile's text. Deterministic for a given set of entries, whatever order they arrive in.

defLock.source_of#
pub def source_of (g : LockedGit) : String

git+<url>?tag=v1&subdir=x#<commit>: the display spelling only.

defLock.read#
pub def read (path : Path) : IO (Result String (Option LockRead))

Read the lockfile at path: none when there is none (the ordinary first-fetch case), err when it exists but cannot be read or parsed.

defLock.write#
pub def write (path : Path) (lock : Lockfile) : IO (Result String Unit)

Write lock to path, replacing whatever is there.