pkgmgr pkg diff
Report whether a package's copy in the catalog differs from the copy in the store it is compared against, and why
- Command version
0.0.0- Command configuration
pkgmgr:pkgmgr.pkg.diff@0.0.0
Arguments
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
--label | string | Yes | The package to compare, by its label in the catalog's index | |
--namespace | string | No | The namespace holding it. May be left out where one namespace holds that label |
It also takes the global arguments.
Output
It answers with a diff.Output.
Examples
pkgmgr pkg diff --label widgets --namespace acmeReport whether this catalog's copy of acme's widgets package differs from the configured store's, and why.
Errors
| Code | Meaning | Remedy |
|---|---|---|
CATALOG_INVALID | The target catalog's manifest does not load; the message says why. | Correct the manifest the message names. |
CATALOG_MANIFEST_FILE_NOT_FOUND | The target catalog holds no catalog manifest, so it is not a pkgmgr catalog. | Point the store at a pkgmgr catalog, or create one there with catalog create. |
CATALOG_TARGET_NOT_DIRECTORY | The catalog the configured store points at is not a directory. | Point the store at the directory of the target catalog in .pkgmgr/config.yml. |
GIT_COMMIT_READ_FAILED | The commit the package's checkout stands at could not be read; the message carries git's error. | Repair what git reports and run the command again. |
GIT_STATUS_READ_FAILED | The git status of the package's checkout could not be read; the message carries git's error. | Repair what git reports and run the command again. |
NAMESPACE_NOT_FOUND | The namespace named does not exist in the catalog the command reads. | Name an existing namespace -- namespace list shows them -- or create it with namespace add; where the command offers --force, that creates it. |
PKG_NOT_FOUND | The package does not exist in the namespace named. | Name a package the namespace holds -- pkg list shows them. |
Also every code of pkgmgr:pkgmgr
| Code | Meaning | Remedy |
|---|---|---|
CATALOG_HOLDS_REFERENCES | The catalog still holds entries that a checked-in catalog may not hold. | Clear them with the clear command the message is about -- pkgmgr catalog clear --ref-type sha for a whole catalog's builds -- then check the catalog in. |
CLEAR_RETENTION_INVALID | A retention given to clear by is not one that keeps anything: a negative --keep or a negative age. | Pass a count of 0 or more to --keep, or an age of zero or more. |
CLEAR_UNFILTERED | Clearing would remove entries from both sides of the index, versions and shas, and nothing narrowed it. | Pass --ref-type version or --ref-type sha to name one side, --dry-run to see the entries first, or --force to mean all of it. |
NAMESPACE_AMBIGUOUS | The package label is held in more than one namespace, so which one is meant cannot be told. | Pass --namespace naming one of the namespaces the message lists. |
NAMESPACE_NOT_FOUND | The namespace named does not exist in the catalog the command reads. | Name an existing namespace -- namespace list shows them -- or create it with namespace add; where the command offers --force, that creates it. |
NAMESPACE_REQUIRED | The catalog holds more than one namespace and the command was not told which one to use. | Pass --namespace naming one. |
STORE_LABEL_RESERVED | A store is configured under the label that names the catalog the command runs in, which is reserved. | Rename that store under pkgmgrConfig.stores. |
STORE_NOT_FOUND | A store named with --store is not configured. | Name one of the stores the message lists, or configure it under pkgmgrConfig.stores. |
STORE_REQUIRED | The operation needs a store outside this catalog to act on, and none is configured. | Configure one under pkgmgrConfig.stores in .pkgmgr/config.yml. |
STORE_SELECTOR_CONFLICT | Both --remote and --store were given, and each names where to read from. | Pass one of them. |
Also every code of pkgmgr:pkgmgr-store
| Code | Meaning | Remedy |
|---|---|---|
CATALOG_UPSTREAM_STORE_UNKNOWN | A catalog's configuration defers to a store by a label its own stores does not declare. | Declare the store under stores in that catalog's .pkgmgr/config.yml, or defer to one of the labels the message lists. |
STORE_LOCATION_NOT_PORTABLE | A store's location is a relative path that climbs out of the catalog naming it, which says something about one machine's layout rather than about the catalog. | Name the store by an absolute path or uri, or by a path beginning with ${CATALOG_ROOT}. |
STORE_LOCATION_VARIABLE_UNDECLARED | A store's location names an environment variable a store location may not name. | Use one of the variables the message lists -- ${CATALOG_ROOT} or ${CATALOG_REPO_ADAPTER} -- or write the location out. |
STORE_LOCATION_VARIABLE_UNSET | A store's location names a declared environment variable that nothing reads in place of when it is unset, and it is unset -- CATALOG_REPO_ADAPTER, the clone of an organization's repo adapter catalog, is one. | Set the variable the message names to the directory it stands for -- for CATALOG_REPO_ADAPTER, the clone of the organization's adapter catalog -- as a user or machine variable, or in the job's environment on a CI agent. |
STORE_LOCATION_UNREACHABLE | A store's location is not a directory that can be read now -- missing, unmounted, or served by an address that did not answer. | Make the location reachable, or point the store at one that is; the message says what kind of location the store's type takes. |
STORE_NOT_FOUND | The store named is not one the catalog's configuration declares. | Name one of the stores the message lists, or declare the store in the catalog's .pkgmgr/config.yml. |
STORE_AMBIGUOUS | More than one store is configured and the run did not say which one to use. | Pass --store naming one of the stores the message lists. |
STORE_FETCH_FAILED | A store that is fetched before it is read could not be fetched, so it is not read -- an earlier copy could answer with a release that has since been superseded. | Repair what the message quotes -- most often the network, or a credential the store's address needs -- and run the command again. |
STORE_ACCESS_REFUSED | A store served at an address refused the fetch -- 401 or 403 -- for want of a credential it takes or one that reaches the file; the message says whether a credential was given, and quotes what the server named. | Give the store a credential it takes, through whatever reads the store; the message names what the server said was wrong with the one given. |
STORE_DIRECTORY_OUTSIDE | A store fetched from a repository names a directory that is not inside that repository. | Write the store's directory relative to the root of the repository it is fetched from. |
STORE_ENTRY_OUTSIDE | A store's index records a path that is not inside the store, so nothing is fetched to it. | Report it against the store; its index is not one this tool will follow. |
STORE_ARTIFACT_DIGEST_MISMATCH | A file a store served is not the one its index records -- the sha256 differs -- so it was not kept. | Run the command again, in case the transfer was damaged; if it fails the same way, report it against the store. |
STORE_CREDENTIAL_INSECURE | A store was given a credential, and its address is not https:, so sending the credential would put it on the network in the clear. | Name the store by an https: address. |
STORE_UPDATE_NOT_A_CHECKOUT | A store asks to be brought up to date before it is read or written, and its directory is not a git checkout, so there is nothing to pull. | Clone the catalogs' repository at that directory, or drop the setting asking for the update from the store. |
STORE_UPDATE_NO_UPSTREAM | A store asks to be brought up to date, and the checkout holding it has no upstream branch to pull. | Check out a branch in that checkout that tracks the catalogs' remote. |
STORE_UPDATE_NOT_FAST_FORWARD | A store could not be brought up to date because pulling into its checkout does not fast-forward -- the checkout holds a change nobody else has. | Resolve the checkout by hand -- push or drop the local change -- and run the command again. |
STORE_READ_ONLY | The command would write to a store that is fetched and only ever read. | Write to a checkout of that store instead -- a local store whose location names the clone. |
COORDINATE_INVALID | A package was named by something that is not a coordinate. | Write it as namespace:name@major.minor.patch, the version in full, or as namespace:name or namespace:name@latest for the highest version held. |
COORDINATE_MUST_PIN | A coordinate names no version, and what was asked needs one. | Add the version in full, namespace:name@<major.minor.patch>. |
ARTIFACT_REGISTRATION_FAILED | An artifact could not be registered in the store; the message names the file and what failed. | Repair what the message names -- most often the artifact itself, or the store's permissions -- and register it again, with pkgmgr pkg register for a file you hold. |
VERSION_CLOBBER | The store already holds that version of the package with different content, and a version is written once. | Release the next version instead of rewriting this one. |
COPY_ENTRY_NOT_HELD | The store being copied from holds no entry for that version of the package. | Name a version the source store holds. |
COPY_ARTIFACT_MISSING | The source store indexes the version, but holds no files for it, so there is nothing to copy. | Clear the entry with pkgmgr pkg clear and register the version into the source store again with pkgmgr pkg register, or report it against that store. |
COPY_FAILED | Copying the entry's files into the target store failed; the message carries the operating system's error. | Repair what the message names -- most often space or permission on the target -- and copy again. |
AUDIENCE_UNKNOWN | The audience given is not one a release has. | Give one of the audiences the message lists. |
AUDIENCE_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record an audience on. | Register the version first, or name one the store holds. |
CLIENT_NOTES_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record client notes on. | Register the version first, or name one the store holds. |
DEPENDENCIES_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record its dependencies on. | Register the version first, or name one the store holds. |
LANGUAGE_VERSIONS_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record language versions on. | Register the version first, or name one the store holds. |
LANGUAGE_VERSIONS_INVALID | The language versions given are not a version range, so nothing was recorded. | Write a version (3.13), a list of them ([3.13, 3.14]), or bounds joined by a comma (>=3.13,<3.15). |
NOTES_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record release notes on. | Register the version first, or name one the store holds. |
README_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record a README on. | Register the version first, or name one the store holds. |
Also every code of cli:cli
| Code | Meaning | Remedy |
|---|---|---|
REPO_ROOT_VALIDATION_FAILED | The repository root the run was given, by --repo-root or by the directory it was started in, is not a directory that can be acted on. | Run the command from inside the repository, or pass --repo-root naming its root. |
RUNTIME_CONFIG_FAILED | A runtime configuration file the run reads -- the application's cli.config.yml at one of its scopes -- does not load, or sets an argument default a scope may not set. | Correct the file the message names; config init writes one that loads. |
COMMAND_CONFIG_FAILED | The configuration the command itself is declared by does not load, so the command cannot be run. This is a fault in the application as it was built, not in anything the person running it supplied. | Report it against the application's release, with the message; reinstalling the release with update --force replaces a damaged copy. |
MANIFEST_VALIDATION_FAILED | The command reads the repository's manifest.yml, and none was found at the root, or the one found does not load. | Run the command in a repository that has a manifest, pass --manifest naming one, or correct the manifest where the message says it does not load. |
APP_CONFIG_FAILED | The application's own configuration file in the repository does not load against the type the application declares for it. | Correct the file the message names; config init writes one that loads. |
INPUT_VALIDATION_FAILED | An argument the command line gave is not one the command accepts once it is read -- the wrong type, a value outside its choices, or one a rule on the input refuses. | Give the argument as the command's --help describes it. |
OUTPUT_VALIDATION_FAILED | The command answered with data that does not match the output it declares, so the answer was withheld. This is a fault in the command, not in how it was run. | Report it against the application's release, with the command line that produced it. |
PIPE_STDIN_NOT_PIPED | The command was asked to take its input from stdin, by --from-stdin or by - as a document input's value, and nothing is piped to it -- stdin is a terminal, or there is none. | Pipe in the output of a command run with --response-format json, or give the input another value. |
SECRET_NOT_GIVEN | The command takes a secret input, which is never typed on the command line, and nothing was typed at its prompt or piped to its standard input. | Run the command at a terminal and type the value at the prompt, or pipe it to the command's standard input, one line for each secret it takes. |
SECRET_STDIN_CLAIMED | The command takes a secret input from standard input, and standard input already carries its piped inputs -- --from-stdin, or a document input given - -- so there is nothing to read the secret from. | Run the command at a terminal to be asked for the secret, or give its other inputs on the command line. |
PIPE_STDIN_CLAIMED_TWICE | --from-stdin was given beside a document input given - or -:<path>, so the piped answer would be both the command's inputs and one of them. | Keep one of the two forms. |
PIPE_FIELD_NOT_FOUND | A document input given -:<path> names a field the piped answer does not hold -- a key no mapping on the way has, or an index past the end of a list or into something that is no list -- or the text after -: is no path. | Name a field the command before the pipe answers with, as keys joined by . with [<n>] picking an item from a list, as releases[0].notes. |
ENVELOPE_UNREADABLE | What was piped to the command is not an envelope a command writes, so there is no answer in it to take as input. | Run the command before the pipe with --response-format json, and pipe nothing else between the two. |
PIPE_UPSTREAM_FAILED | The command before the pipe refused, so there is no answer to take as input and this command did not run. Its own errors follow this one in the envelope. | Repair what the errors after this one name, in the command before the pipe, and run the pipeline again. |
PIPE_ANSWER_NOT_INPUTS | --from-stdin takes the piped answer as the command's inputs by name, and the answer is no mapping, or carries a field the command declares no input for. | Pipe in a command whose answer holds only this command's inputs, or give the answer to one document input with - instead. |
UNHANDLED_EXCEPTION | The command failed in a way nothing anticipated, and the message is the failure's own text. | Report it against the application's release, with the command line and the message. |
APPLICATION_RELEASE_NAME_UNKNOWN | The application could not tell which release it is -- the project it was released with, or which of that project's applications it is -- so it cannot look its releases up. | Run the application as it was installed, from the directory toolchain install placed it in, or report it against the release. |
Exit codes
| Code | Meaning |
|---|---|
0 | The command answered; the envelope's status is success and errors is empty. |
1 | The command or the framework refused; the envelope's status is error and errors names each code, with its message. |
2 | The command line could not be read -- an unknown command, a missing or unknown argument -- so nothing ran and no envelope was written; the usage is printed instead. |
Types
diff.Output
One of the types diff.checkedPackage, diff.diffFailed.
diff.checkedPackage
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
label | string | Yes | Label of the package compared | |
namespace | string | Yes | Label of the namespace holding it | |
dirty | boolean | Yes | Whether the package in the catalog the command ran in differs from its copy in the configured store, for the reasons dirtyReasons lists. A comparison that could not be made is not answered as dirty: the command fails, and its errors say what could not be read | |
dirtyReasons | list[string] | Yes | Why the package is dirty, as codes: LOCAL_PKG_MISSING, STORE_PKG_MISSING, CONTENT_HASH_MISMATCH, PKG_TYPE_MISMATCH where one side is a git repository and the other is not, LOCAL_GIT_STATUS_DIRTY and STORE_GIT_STATUS_DIRTY where a side has uncommitted changes, and GIT_COMMIT_MISMATCH. At least one where dirty is true, and empty for a clean package | |
localPath | string | Yes | Absolute path of the package's directory, at its latest version, in the catalog the command ran in | |
storePath | string | Yes | Absolute path of the package's directory in the configured store: at the same version where the store holds it, otherwise at the store's own latest | |
localExists | boolean | Yes | Whether localPath is a directory | |
storeExists | boolean | Yes | Whether storePath is a directory | |
localHash | string | No | SHA-256, in hexadecimal, over the relative path of everything under localPath and the content of each file. Absent where that directory does not exist, and where both directories exist and either is a git repository, which is compared by status and commit | |
storeHash | string | No | SHA-256, in hexadecimal, over the relative path of everything under storePath and the content of each file. Absent where that directory does not exist, and where both directories exist and either is a git repository, which is compared by status and commit | |
localCommit | string | No | Commit checked out at localPath. Present only where both sides are git repositories with no uncommitted changes, which is where the two sides are compared by commit: dirtyReasons holds GIT_COMMIT_MISMATCH where it differs from storeCommit | |
storeCommit | string | No | Commit checked out at storePath. Present only where both sides are git repositories with no uncommitted changes, which is where the two sides are compared by commit |