pkgmgr
The package manager for catalogs: it registers versioned packages into a catalog, finds and lists what a catalog and its stores hold, copies packages between them, and clears what is no longer wanted.
What it does
A package – a library, a schema, a built executable, a repo adapter, a template – is kept in a catalog: a directory with an index recording each package under its coordinate, by the release it is and by the source state it was built from. The other tools use catalogs as they work: dev vendor resolves what a repository declares out of one, and dev build files what it builds into one. pkgmgr acts on a catalog directly:
- ask whether a catalog or a store holds a package, and where its file is (
pkgmgr pkg find); - list what one holds (
pkgmgr pkg list,pkgmgr namespace list); - compare a catalog’s copy of a package with a store’s (
pkgmgr pkg diff,pkgmgr namespace diff); - register a package again, or under a coordinate of your choosing (
pkgmgr pkg register); - clear a stale entry, or prune old builds (
pkgmgr pkg clear,pkgmgr namespace clear,pkgmgr catalog clear); - copy packages and templates between a catalog and a store (
pullandpush).
Install it with toolchain install pkgmgr. It is run as pkgmgr:
pkgmgr --help
pkgmgr <group> <command> --help
Concepts
A catalog. A directory holding pkgmgr.manifest.yml, which says what the catalog holds and how its versions are written (versionShape: major, major.minor or major.minor.patch), and .pkgmgr/, its index. Packages sit beneath it as <namespace>/<name>/<version>/, unless an entry records a path of its own. Every command acts on the catalog it is placed in: the working directory, or the directory --catalog-root names. pkgmgr catalog create makes one.
A store. Another catalog, named in the catalog’s .pkgmgr/config.yml under a label. A store is a directory read and written where it is, a git repository fetched and only read, or an address its files are served under, fetched and only read. Commands that read a store take --store <label>; pull and push take the one store configured, and --remote on the listings means the same.
A namespace. The group a package is kept under, and the part of its coordinate before the colon.
A coordinate. How a package is named: <namespace>:<name>@<major>.<minor>.<patch> for one release, and <namespace>:<name> or <namespace>:<name>@latest for the highest version a store holds.
Two keys. An entry is held by its version, which is what a release is, and by the source state it was made from, which is what a build is: the commit of a clean checkout, or a digest of a checkout’s uncommitted changes or of a directory’s contents. The index keeps the two sides apart, versions and shas, and --ref-type version and --ref-type sha name them. A version is written once; a source state keeps one entry per build.
Finding out what a catalog holds
pkgmgr pkg find --coordinate acme:widgets@1.2.0
pkgmgr pkg find --coordinate acme:widgets --store released
pkgmgr pkg list --namespace acme --versions
pkg find answers whether the package is held and where its file is. A miss is an answer: it exits 0 and says the package is not held. With --source <directory> it looks for the build of that directory’s source state instead, and reports the key it worked the state out to whether or not anything was found. An entry whose file is gone is not held.
pkg list and namespace list list what each store named with --store holds, grouped by store, with local naming the catalog the command ran in. With no --versions or --shas they list names alone; --versions and --shas each take a pattern over that side’s keys, matched whole, and --latest narrows the versions to the highest.
pkg diff and namespace diff compare the catalog’s copy with the configured store’s, by commit where both are git checkouts and by a hash of their contents otherwise, and name each difference they found.
Repairing an entry
When a catalog holds an entry that is wrong – a build whose file is gone, a copy that no longer matches its source – clear it and register the package again:
pkgmgr pkg clear --label widgets --namespace acme --ref-type sha --dry-run
pkgmgr pkg clear --label widgets --namespace acme --ref-type sha
pkgmgr pkg register --coordinate acme:widgets@1.2.0 --pkgs dist/widgets.zip --source .
pkg register copies each file into the catalog and records it. A schema document is registered under the coordinate it declares; any other file is handed one with --coordinate, and --source keys it by the source state it was built from. Registering the same content again changes nothing. A version already held with different content is refused as VERSION_CLOBBER: a version is written once, so release the next one. A document marked as in development – its version ending in -dev – is not a release, and is registered again whenever it changes.
Clearing and pruning
pkgmgr catalog clear, pkgmgr namespace clear and pkgmgr pkg clear remove entries of one side of the index, with the files they name, from the whole catalog, one namespace or one package. Naming neither side is refused as CLEAR_UNFILTERED unless --force says both were meant, since clearing the version side takes releases with it. --dry-run reports what would go.
--keep <n> keeps each package’s newest entries on each side and clears the rest, and --older-than <duration> clears only what was registered longer ago than that – 30d, 12h, 6wk. Named together, an entry has to fail both to be cleared. A file another entry still names is left where it is.
--validate removes nothing and fails as CATALOG_HOLDS_REFERENCES where anything matched, which is how a check refuses a catalog that still holds development builds before it is committed:
pkgmgr catalog clear --ref-type sha --validate
Packages and templates
pkgmgr pkg add adds a package to a namespace, made from a template, copied from another package, or taken from a directory or a git repository; rename, update and rm change and remove one. pkgmgr pkg pull and pkgmgr pkg push copy a package between the catalog and the configured store, its files and its entry together. A template is a directory under the catalog’s templates/ that pkg add --template copies; the pkgmgr template commands add, list, rename, copy and remove them. pkgmgr pkg repair reports the git submodule records the catalog’s packages no longer account for and removes them with --apply.
What a refusal means
| Code | Meaning |
|---|---|
STORE_REQUIRED |
The command needs a store outside the catalog, and none is configured |
STORE_NOT_FOUND |
The store named is not configured; the message lists the ones that are |
STORE_AMBIGUOUS |
More than one store is configured; name one with --store |
STORE_LOCATION_UNREACHABLE |
A store’s location cannot be read now |
STORE_READ_ONLY |
The command would write to a store that is fetched and only read |
NAMESPACE_NOT_FOUND, NAMESPACE_REQUIRED, NAMESPACE_AMBIGUOUS |
The namespace given does not exist, or none was given where one is needed |
COORDINATE_INVALID, COORDINATE_MUST_PIN |
What was typed is not a coordinate, or names no version where one is needed |
VERSION_CLOBBER |
The version is held with different content; release the next one |
CLEAR_UNFILTERED |
A clear names neither side of the index |
CATALOG_HOLDS_REFERENCES |
--validate found entries of the side it was asked about |