impl-tool issue prepare
Prepare an issue's worktree and branch without running the issue
- Command version
0.0.0- Command configuration
impl-tool:impl-tool.issue.prepare@0.0.0
Arguments
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
--issue | string | Yes | The issue to prepare for, by its bare id -- no queue entry is read, where issue run and session start take the entry under the same flag. Its worktree and the checkouts prepared beside it are all named from it, so it is the only thing the command needs | |
--path | path | No | "." | Directory to act on (default: current directory) |
--repo-name | string | No | Name the remote repository is created under when the directory has no remote (default: the directory's name) | |
--branch | string | No | Branch to prepare and push, taken literally. Defaults to impl-tool/<issue>, created off the target directory's current tip when the issue has never run. The workspace worktree keeps the issue's name either way | |
--base | string | No | Branch pull requests are opened relative to (the checkout's configured default branch when not given). Recorded for the observer this preparation points; it never resets anything | |
--seed | string | No | Branch whose tip the prepared branch is reset to, for a world built to start from a state you staged. The prepared branch's push may then rewrite its remote copy (force-with-lease). Without it nothing is ever reset | |
--skip-install,--no-skip-install | boolean | No | false | Prepare the worktree and branch and install nothing. A session needs only those; the install is for launching with an executable built from this issue's own checkout |
--keep-uncommitted,--no-keep-uncommitted | boolean | No | false | Prepare around uncommitted work the worktree already holds instead of refusing. Without it, a preparation over a worktree with uncommitted changes in the superproject or any submodule refuses and names them. With it, nothing they touch is reset -- a dirty submodule stays at its checkout even when its parent records a later commit -- and the answer lists what was kept. A seeded preparation refuses either way, because the seed resets the worktree |
--observe,--no-observe | boolean | No | false | Point the main checkout's observer branch at this issue and keep it there -- a branch named for the bare issue id, created in the superproject and every submodule and advanced on every later run of this issue |
It also takes the global arguments.
Output
It answers with a prepare.issuePrepareSummary.
Examples
impl-tool issue prepare --issue PROJ-0000123Make the issue's worktree and branch, push the branch, and install the runner there, without starting a session.
impl-tool issue prepare --issue PROJ-0000123 --seed experiment/baseline --skip-installPrepare the issue's branch reset to another branch's tip, installing nothing.
Errors
| Code | Meaning | Remedy |
|---|---|---|
TARGET_PATH_NOT_DIRECTORY | The path --path names is not a directory. | Pass --path naming the checkout to act on, or leave it out to act on the current directory. |
ISSUE_FORMAT_INVALID | The issue id does not match the format the configuration's issueFormat requires. | Give the issue id as issueFormat spells one, such as CMD-0000002. |
UNCOMMITTED_WORK | The checkout holds uncommitted work the preparation would carry into the issue's branch or lose. | Commit or set the work aside, or pass --keep-uncommitted to carry it into the issue's worktree. |
REMOTE_NOT_FOUND | The git remote the issue's branch is pushed to does not exist in the checkout. | Add the remote the configuration names, or set remote in .impl-tool/config.yml to one the checkout has. |
ISSUE_PREPARE_FAILED | Preparing the issue's worktree failed -- a git step, or vendoring its libraries; the message carries the failure. | Repair what the message names and run issue prepare again. |
NO_TOOL_SOURCE | The worktree is built, but no workspacesRoot is configured, so the tool's source has nowhere to be exported to or installed under. | Set workspacesRoot in the configuration and run issue prepare again, or install the tool by hand. |
CHECKOUT_DOES_NOT_START | The tool, run from the checkout before anything was replaced, does not start, so the install was left as it was. | Obtain what the checkout depends on -- vendor its libraries, sync its environment -- and run the command again. |
TOOL_ENVIRONMENT_IN_USE | A running process holds the environment the tool is installed in, so it could not be replaced. | Wait until nothing is running from the tool's environment and run the command again. |
EXECUTABLE_DOES_NOT_BOOT | The tool was installed, but its executable does not start, so the issue has nothing to be launched with. | Read what the executable prints when started, repair the checkout it was installed from, and run the command again. |
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
prepare.issuePrepareSummary
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
prepared | issuePrepared | No | {} | What was prepared for the issue: its worktree and branch, its exported source and tools directory, the executable its runs are made with, and the reason where there is no executable |
launchCommand | string | No | "" | The command line that runs the issue with its own executable, written out to copy, with a placeholder where the issue's entry goes. Empty where no executable was installed |
durationSeconds | number | No | 0 | Seconds the command took, rounded to a tenth |