dev gitignore gen
Write this repository's .gitignore from the shared set and its own additions
- Command version
0.0.0- Command configuration
dev-tool:dev.gitignore.gen@0.0.0
Arguments
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
--validate,--no-validate | boolean | No | false | Report whether the ignore file is what the declaration would write, and write nothing |
It also takes the global arguments.
Output
It answers with a gen.gitignoreGenSummary.
Examples
dev gitignore genWrite .gitignore from the shared set and this repository's own additions.
dev gitignore gen --validateFail where .gitignore is not what the declaration would write, and write nothing.
Errors
| Code | Meaning | Remedy |
|---|---|---|
GITIGNORE_ADAPTER_UNRESOLVED | A checkout's repo adapter could not be resolved, so the ignore rules its language leaves in a checkout are unknown and nothing is written. | Vendor the adapter in that checkout with dev vendor, then run dev gitignore gen again. |
GITIGNORE_WOULD_DROP_RULES | A checkout's .gitignore was written by hand, and generating it would drop rules it states, so nothing is written. | Add each rule the repository still needs to gitignoreAdditions in its .dev-tool/config.yml, delete the rest, and run dev gitignore gen again. |
GITIGNORE_OUT_OF_DATE | Under --validate, a checkout's .gitignore is not what the declaration writes. | Run dev gitignore gen and commit the result; a rule only one repository needs goes in its gitignoreAdditions. |
Also every code of dev-tool:dev-tool
| Code | Meaning | Remedy |
|---|---|---|
ADAPTER_CARRIES_THE_CONTRACT | The adapter being published carries its own copy of the adapter contract package, which a released tool has compiled in and which would shadow it, so it is refused rather than published. | Keep the contract package out of the adapter module's root and build again. |
ADAPTER_IMPORTS_BEYOND_THE_CONTRACT | The adapter being published imports a module that no tool built to the adapter contract carries, so a released tool would fail to load it. | Stop importing the module the message names, or add it to the contract's importable lists first so a tool is built carrying it. |
ADAPTER_CHECKOUT_MANIFEST_MISSING | The adapter checkout the tree pins holds no manifest that loads, so what it publishes cannot be read. | Run git submodule update --init --recursive in the tree's root. |
ADAPTER_COMMAND_FAILED | A process the repo adapter described for this command -- the linter, the test runner, the type checker -- exited with a failure; its own output above says why. | Repair what that tool's output names and run the command again. |
ADAPTER_PATH_NOT_FOUND | A path given with --paths does not exist. | Name a file or directory that exists in the repository. |
ADAPTER_PATH_OUTSIDE_REPOSITORY | A path given with --paths resolves outside the repository the command runs in. | Name a path inside the repository, or run the command in the repository that holds it. |
ADAPTER_REPOSITORY_DECLARES_NO_SOURCE | The repository pins other repositories and its ownRoots names no directory of its own, so a run naming no path has nothing to cover without crossing into them. | Declare the repository's own directories in ownRoots in .dev-tool/config.yml, or narrow the run with --modules or --paths. |
ADAPTER_SOURCE_PATH_HOLDS_A_REPOSITORY | A directory ownRoots names holds a pinned repository's checkout, so a run naming no path would cross into it. | Name only this repository's own directories in ownRoots; --recurse runs each pinned repository's own command in its checkout. |
ADAPTER_RUNTIME_INVALID | The repo adapter could not be asked for the command's process; the message carries its error. | Vendor the adapter again with dev vendor; if it persists, report it against the adapter's release. |
REPO_ADAPTER_COMMAND_NOT_IMPLEMENTED | The repository's repo adapter has no process for this command in this language. | Declare one under repoAdapterCommands in .dev-tool/config.yml, or use an adapter that implements it. Where the adapter is a configuration document, declare the verb under commands in that document, or leave the check out of the gate with gateOmissions in .dev-tool/config.yml. |
REPO_ADAPTER_COMMAND_MALFORMED | The repo adapter described a process for this command that cannot be run as written. | Report it against the adapter's release, with the message. |
REPO_ADAPTER_COMMAND_INVALID_PAYLOAD | The repo adapter answered this command with something that is not a process to run. | Report it against the adapter's release, with the message. |
REPO_ADAPTER_COMMAND_OVERRIDE_INVALID | The command declared for this verb under repoAdapterCommands in .dev-tool/config.yml cannot be rendered for this run. | Correct the declaration the message names. |
REPO_ADAPTER_PARAMETER_UNSUPPORTED | The run asks the adapter to leave something out -- a tier, an isolation -- that the adapter's command for it takes no parameter for, so it would cover what it was asked to leave out. | Vendor an adapter implementing the current contract with dev vendor, or run without the option. |
REPO_ADAPTER_PATH_SELECTION_UNSUPPORTED | The command declared for this verb under repoAdapterCommands does not read the run's paths, so it cannot be narrowed to the selected paths or to the repository's own roots. | Run without --paths, or declare the command so that it reads the paths it is handed. |
REPO_ADAPTER_CATALOG_MISSING | The repository's repo-adapter catalog does not exist and no store it defers to is reachable, so no adapter can be resolved. | Declare the adapter catalog in the manifest's catalogs with an upstream that holds the adapter, then run dev vendor. |
REPO_ADAPTER_CATALOG_INVALID | The repository's repo-adapter catalog, or the adapter coordinate the manifest names, cannot be read. | Correct the catalog declaration or the repoAdapter coordinate the message names in the manifest. |
REPO_ADAPTER_UNAVAILABLE | No build catalog this repository reads holds a build of its repo adapter, and no store its adapter catalog defers to holds a release of it. | Inside a tree run dev build --libraries-only --recurse in the tree's root; a clone standing alone sets CATALOG_ROOT to a checkout whose catalogs hold the adapter. |
REPO_ADAPTER_VENDOR_FAILED | The repo adapter was found but could not be copied into the repository's adapter catalog; the message says why. | Repair what the message names and run dev vendor again. |
REPO_ADAPTER_CONTRACT_UNMET | The resolved repo adapter does not implement the adapter contract this dev-tool calls, or cannot say whether it serves the repository's language version. | Vendor an adapter release built for this dev-tool with dev vendor, or update dev-tool. |
REPO_ADAPTER_LANGUAGE_VERSION_UNSERVED | No release of the repo adapter is for the language version the repository states it is written for. | Release the adapter for that version, or correct the version the repository states in the language's own file. |
RUNTIME_COORDINATE_UNAVAILABLE | A module resolved at run time names no version and the manifest states none, so there is nothing to publish it under. | State a version in the manifest, or give the module's runtimeCoordinate one. |
RUNTIME_ARCHIVE_FAILED | A module resolved at run time, such as a repo adapter, could not be archived for publishing; the message names the checkout and why. | Repair what the message names -- most often untracked source under the module root -- and build again. |
BUILD_CATALOG_COORDINATE_UNAVAILABLE | The manifest states no project or no version, so the build has no coordinate to register under. | State project and version in the repository's manifest. |
LIBRARY_LOOKUP_FAILED | The build catalog lists a library but names no file for it. | Publish the library again with dev build --libraries-only in the repository that holds it. A catalog you cannot rebuild from is repaired by clearing the entry with pkgmgr pkg clear --catalog-root <catalog> --label <name> --ref-type sha and registering the file again with pkgmgr pkg register. |
BUILD_ARTIFACT_DID_NOT_ANSWER | The executable just built did not answer the check run on it within the time allowed, which is as broken as failing it. | Pass --check-arg with something the executable can answer, or set checkArg to an empty list under the build command's argDefaults to turn the check off. |
BUILD_ARTIFACT_DID_NOT_RUN | The executable just built could not be started at all. | Repair what the message names, most often a missing file or permission at the artifact's path, and build again. |
BUILD_ARTIFACT_DID_NOT_START | The executable was built but exited with a failure on the check run on it; its output is in the message. | Repair what the output names -- most often a module or file the build left out of the executable -- and build again. |
RECURSE_WITHOUT_VALIDATE | --recurse runs the validation in every pinned repository, and this run validates nothing. | Pass --validate with --recurse. |
RECURSE_REPOSITORY_FAILED | The command, run in a pinned repository's own checkout under --recurse, failed there; the message names the repository and carries its output. | Run the command in that repository to see its own refusal, and repair it there. |
RECURSE_REPOSITORY_NOT_VENDORED | A pinned repository declares libraries to obtain and has none vendored, so its own command cannot run in its checkout. | Run dev build --libraries-only --recurse and then dev vendor --recurse in the tree's root. |
AFFECTED_CHANGES_UNREADABLE | git could not be run, or failed, while reading what changed, so what the change reaches cannot be worked out. | Repair what the message names -- often a --since reference git does not know -- or run with --select all. |
AFFECTED_INPUT_WITHOUT_AFFECTED | --changed-coordinates or --since says what changed, which only a run selecting by change reads, and this run does not select by change. | Pass --select affected with them, or leave them out. |
AFFECTED_SELECTION_NARROWED | The run both says what changed (--changed-coordinates or --since) and names what to cover outright (--modules or --paths). | Pass one or the other. |
AFFECTED_RECURSE_MODE_FULL | Selecting by change works from one repository's dependency graph, and --recurse-mode full is one run over every pinned repository, whose modules that graph does not hold. | Cross with --recurse-mode isolate, or pass --select all. |
TEST_NOT_IN_A_TIER | Test files sit in no directory named for a tier the repository's testTiers declares, so no run would collect them as a tier. | Move each test the message names into a tier's directory, or declare the tier in testTiers. |
TEST_TIER_NOT_COLLECTED | What the run names holds tests only in tiers the run does not collect, so it would run nothing. | Pass --tier naming the tier, --all-tiers, or name the test files themselves, which run whatever their tier. |
TEST_TIER_SELECTION_CONFLICT | --tier names tiers to collect and --all-tiers asks for every one. | Pass one or the other. |
TEST_FILE_PATTERNS_UNAVAILABLE | Which of the repository's files are tests cannot be asked, because the repo adapter its manifest names resolves neither through its own catalogs nor through those of a repository that pins it; a fixture cannot be told from a document it publishes. | Run dev vendor in the repository the message names, so its adapter catalog holds the adapter. |
TEST_TIER_UNKNOWN | --tier names a tier the repository's testTiers does not declare. | Name one of the tiers the message lists. |
TEST_TIER_NONE_DEFAULT | The repository's testTiers marks no tier default, so a run naming none collects nothing. | Name a tier with --tier, pass --all-tiers, or mark the tier a run after an edit is owed default in testTiers. |
SCHEMA_REGISTRATION_STALE | A schema registered in the schema store is not the document its source publishes, and every reference to it resolves to the stale copy. | Run dev schema gen --force to register the current document. |
SCHEMA_VENDORED_STALE | A schema vendored into a repository is not the document its source publishes, and the library's models were unpacked beside the stale copy. | Rebuild the package that publishes it with dev build --libraries-only and run dev vendor in the repository the message names. |
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
gen.gitignoreGenSummary
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
repositories | list[string] | Yes | Each repository whose ignore file is generated, as a path from the root the command ran in: . for that root, then each repository it pins that keeps a .dev-tool/config.yml | |
sharedCount | integer | Yes | How many ignore rules dev-tool states for every repository | |
ownCount | integer | Yes | How many rules the repositories state for themselves in gitignoreAdditions, summed over repositories | |
validateOnly | boolean | Yes | Whether the run was made with --validate, which compares and writes nothing | |
written | list[string] | Yes | The repositories whose ignore file the run rewrote, as repositories names them. Empty under --validate | |
outOfDate | list[string] | Yes | The repositories whose ignore file is not what would be generated, as repositories names them. Filled under --validate alone, which fails as GITIGNORE_OUT_OF_DATE where it names any |