mirror of https://github.com/jdx/mise
docs: update task documentation (#3651)
* docs: update task documentation * fix * [autofix.ci] apply automated fixes * update documentation * fix * typo * fix --------- Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
This commit is contained in:
Hugues Verlin
GitHub
parent
a4ab246493
commit
903563d6eb
10
docs/faq.md
10
docs/faq.md
|
|
@ -182,3 +182,13 @@ We also urge users to look after the plugins they use, and urge plugin authors t
|
|||
the users they serve.
|
||||
|
||||
For more details see [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md).
|
||||
|
||||
## What is usage?
|
||||
|
||||
usage (<https://usage.jdx.dev/>) is a spec and CLI for defining CLI tools.
|
||||
|
||||
Arguments, flags, environment variables, and config files can all be defined in a Usage spec. It can be thought of like OpenAPI (swagger) for CLIs.
|
||||
|
||||
`usage` can be installed with `mise` using `mise use -g usage` and is required to get the autocompetion working. See [autocompletion](/installing-mise.html#autocompletion).
|
||||
|
||||
You can leverage usage in file tasks to get auto-completion working, see [file tasks arguments](/tasks/file-tasks.html#arguments).
|
||||
|
|
|
|||
|
|
@ -23,8 +23,6 @@ You can verify the installation by running:
|
|||
|
||||
- `~/.local/bin` does not need to be in `PATH`. mise will automatically add its own directory to `PATH`
|
||||
when activated.
|
||||
- mise respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like
|
||||
to change these locations.
|
||||
|
||||
== Brew
|
||||
Using [brew](https://brew.sh/) package manager
|
||||
|
|
@ -41,6 +39,7 @@ winget install jdx.mise
|
|||
```
|
||||
|
||||
```shell [scoop]
|
||||
# https://github.com/ScoopInstaller/Main/pull/6374
|
||||
scoop install mise
|
||||
```
|
||||
|
||||
|
|
@ -60,7 +59,7 @@ sudo apt install -y mise
|
|||
```
|
||||
|
||||
```sh [arm64]
|
||||
sudo apt update -y && apt install -y gpg sudo wget curl
|
||||
sudo apt update -y && sudo apt install -y gpg sudo wget curl
|
||||
sudo install -dm 755 /etc/apt/keyrings
|
||||
wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
|
||||
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
|
||||
|
|
@ -70,6 +69,9 @@ sudo apt install -y mise
|
|||
|
||||
:::
|
||||
|
||||
`mise` respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like
|
||||
to change these locations.
|
||||
|
||||
## 2. Activate `mise`
|
||||
|
||||
Now that `mise` is installed, you can optionally activate it or add its [shims](dev-tools/shims.md) to `PATH`.
|
||||
|
|
@ -118,14 +120,14 @@ echo 'eval "$(/opt/homebrew/bin/mise activate zsh)"' >> ~/.zshrc
|
|||
```
|
||||
|
||||
- Activation will be handled automatically if you use `fish` shell and installed via `homebrew`. This can be disabled with `set -Ux MISE_FISH_AUTO_ACTIVATE 0`.
|
||||
- Make sure you restart your shell session after modifying your rc file in order for it to take effect.-
|
||||
- Make sure you restart your shell session after modifying your rc file in order for it to take effect.
|
||||
|
||||
== Windows
|
||||
|
||||
Only shims are supported for now on Windows.
|
||||
|
||||
- When using `scoop`, the shims are automatically added to your `PATH`.
|
||||
- With `winget`, Add this directory to PATH: `<homedir>\AppData\Local\mise\shims`.
|
||||
- With `winget`, you need to add `<homedir>\AppData\Local\mise\shims` to your `PATH`.
|
||||
|
||||
```powershell
|
||||
$shimPath = "$env:USERPROFILE\AppData\Local\mise\shims"
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ In addition to defining tasks through the configuration, they can also be define
|
|||
- `.mise/tasks/:task_name`
|
||||
- `.config/mise/tasks/:task_name`
|
||||
|
||||
Note that you can include additional directories using the [task_config](/tasks/#task-configuration) section.
|
||||
Note that you can include additional directories using the [task_config](/tasks/task-configuration.html#task-config-options) section.
|
||||
|
||||
Here is an example of a file task that builds a Rust CLI:
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ of course they'll need to find a different way to install their dev tools the ta
|
|||
|
||||
## Task Configuration
|
||||
|
||||
The same configuration options as for [TOML tasks](/tasks/toml-tasks.html) are supported.
|
||||
All configuration options can be found here [task configuration](/tasks/task-configuration)
|
||||
You can provide additional configuration for file tasks by adding `#MISE` comments at the top of the file.
|
||||
|
||||
```bash
|
||||
|
|
@ -58,18 +58,21 @@ You can also use it to run the script with various programming languages.
|
|||
|
||||
```js [node]
|
||||
#!/usr/bin/env node
|
||||
//MISE description="Hello, World in Node.js"
|
||||
|
||||
console.log("Hello, World!");
|
||||
```
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python
|
||||
#MISE description="Hello, World in Python"
|
||||
|
||||
print('Hello, World!')
|
||||
```
|
||||
|
||||
```ts [deno]
|
||||
#!/usr/bin/env -S deno run --allow-env
|
||||
//MISE description="Hello, World in Deno"
|
||||
|
||||
console.log(`PATH, ${Deno.env.get("PATH")}`);
|
||||
```
|
||||
|
|
@ -87,9 +90,7 @@ File tasks in `mise-tasks`, `.mise/tasks`, `mise/tasks`, or `.config/mise/tasks`
|
|||
sub-directories which will automatically apply prefixes to their names
|
||||
when loaded.
|
||||
|
||||
### Example
|
||||
|
||||
With a folder structure like below:
|
||||
**Example**: With a folder structure like below:
|
||||
|
||||
```text
|
||||
mise-tasks
|
||||
|
|
@ -120,6 +121,8 @@ The `usage` CLI is not required to execute mise tasks with the usage spec.
|
|||
However, for completions to work, the `usage` CLI must be installed and available in the PATH.
|
||||
:::
|
||||
|
||||
### Example file task with arguments
|
||||
|
||||
Here is an example of a file task that builds a Rust CLI using some of the features of usage:
|
||||
|
||||
```bash [mise-tasks/build]
|
||||
|
|
@ -141,11 +144,68 @@ fi
|
|||
cargo build --profile "${usage_profile:-debug}" --target "$usage_target"
|
||||
```
|
||||
|
||||
Completions will now be enabled for your task. In this example, `mise run build --profile <tab><tab>`
|
||||
will show `debug` and `release` as options. The `--user` flag will also show completions generated by the output of `mycli users`.
|
||||
If you have installed `usage`, completions will be enabled for your task. In this example,
|
||||
|
||||
- `mise run build --profile <tab><tab>`
|
||||
will show `debug` and `release` as options.
|
||||
- The `--user` flag will also show completions generated by the output of `mycli users`.
|
||||
|
||||
(Note that cli and markdown help for tasks is not yet implemented in mise as of this writing but that is planned.)
|
||||
|
||||
:::tip
|
||||
If you don't get any autocomplete suggestions, use the `-v` (verbose) flag to see what's going on.
|
||||
For example, if you use `mise run build -v` and have an invalid `usage` spec, you will see an error message such as `DEBUG failed to parse task file with usage`
|
||||
:::
|
||||
|
||||
### Example of a NodeJS file task with arguments
|
||||
|
||||
Here is how you can use [usage](https://usage.jdx.dev/cli/scripts#usage-scripts) to parse arguments in a Node.js script:
|
||||
|
||||
```js [mise-tasks/greet]
|
||||
#!/usr/bin/env -S node
|
||||
//MISE description="Write a greeting to a file"
|
||||
//USAGE flag "-f --force" help="Overwrite existing <file>"
|
||||
//USAGE flag "-u --user <user>" help="User to run as"
|
||||
//USAGE arg "<output_file>" help="The file to write" default="file.txt" {
|
||||
//USAGE choices "greeting.txt" "file.txt"
|
||||
//USAGE }
|
||||
|
||||
const fs = require("fs");
|
||||
|
||||
const { usage_user, usage_force, usage_output_file } = process.env;
|
||||
|
||||
if (usage_force === "true") {
|
||||
fs.rmSync(usage_file, { force: true });
|
||||
}
|
||||
|
||||
const user = usage_user ?? "world";
|
||||
fs.appendFileSync(usage_file, `Hello, ${user}\n`);
|
||||
console.log(`Greeting written to ${usage_file}`);
|
||||
```
|
||||
|
||||
Run it with:
|
||||
|
||||
```shell
|
||||
mise run greet greeting.txt --user Alice
|
||||
# Greeting written to file.txt
|
||||
```
|
||||
|
||||
If you pass an invalid argument, you will get an error message:
|
||||
|
||||
```shell
|
||||
mise run greet invalid.txt --user Alice
|
||||
# [greet] ERROR
|
||||
# 0: Invalid choice for arg output_file: invalid.txt, expected one of greeting.txt, file.txt
|
||||
```
|
||||
|
||||
Autocomplete will show the available choices for the `output_file` argument if `usage` is installed.
|
||||
|
||||
```shell
|
||||
mise run <TAB>
|
||||
# > greeting.txt
|
||||
# file.txt
|
||||
```
|
||||
|
||||
## CWD
|
||||
|
||||
mise sets the current working directory to the directory of `mise.toml` before running tasks.
|
||||
|
|
|
|||
|
|
@ -43,7 +43,27 @@ description = 'Cut a new release'
|
|||
file = 'scripts/release.sh' # execute an external script
|
||||
```
|
||||
|
||||
## run
|
||||
## Adding tasks
|
||||
|
||||
You can edit the `mise.toml` file directly or using [`mise tasks add`](/cli/tasks/add)
|
||||
|
||||
```shell
|
||||
mise task add pre-commit --depends "test" --depends "render" -- echo pre-commit
|
||||
```
|
||||
|
||||
will add the following to `mise.toml`:
|
||||
|
||||
```shell
|
||||
[tasks.pre-commit]
|
||||
depends = ["test", "render"]
|
||||
run = "echo pre-commit"
|
||||
```
|
||||
|
||||
## Common options
|
||||
|
||||
For an exhaustive list, see [task configuration](/tasks/task-configuration).
|
||||
|
||||
### Run command
|
||||
|
||||
Provide the script to run. Can be a single command or an array of commands:
|
||||
|
||||
|
|
@ -62,8 +82,6 @@ run = [
|
|||
]
|
||||
```
|
||||
|
||||
### run_windows
|
||||
|
||||
You can specify an alternate command to run on Windows by using the `run_windows` key:
|
||||
|
||||
```toml
|
||||
|
|
@ -72,7 +90,7 @@ run = 'cargo test'
|
|||
run_windows = 'cargo test --features windows'
|
||||
```
|
||||
|
||||
## dir
|
||||
### Specifying which directory to use
|
||||
|
||||
Tasks are executed with `cwd` set to the directory containing `mise.toml`. You can use the directory
|
||||
from where the task was run with `dir = "{{cwd}}"`:
|
||||
|
|
@ -85,17 +103,19 @@ dir = "{{cwd}}"
|
|||
|
||||
Also, `MISE_ORIGINAL_CWD` is set to the original working directory and will be passed to the task.
|
||||
|
||||
## description
|
||||
### Adding a description and alias
|
||||
|
||||
You can add a description to a task:
|
||||
You can add a description to a task and alias for a task.
|
||||
|
||||
```toml
|
||||
[tasks.build]
|
||||
description = 'Build the CLI'
|
||||
run = "cargo build"
|
||||
alias = 'b' # `mise run b`
|
||||
```
|
||||
|
||||
The description will for example be displayed when running [`mise tasks ls`](/cli/tasks/ls.html) or [`mise run`](/cli/run.html)` with no arguments.
|
||||
- This alias can be used to run the task
|
||||
- The description will be displayed when running [`mise tasks ls`](/cli/tasks/ls.html) or [`mise run`](/cli/run.html)` with no arguments.
|
||||
|
||||
```shell
|
||||
❯ mise run
|
||||
|
|
@ -105,7 +125,7 @@ Tasks
|
|||
# test Run the tests
|
||||
```
|
||||
|
||||
## depends
|
||||
### Dependencies
|
||||
|
||||
You can specify dependencies for a task. Dependencies are run before the task itself. If a dependency fails, the task will not run.
|
||||
|
||||
|
|
@ -117,41 +137,9 @@ run = 'cargo build'
|
|||
depends = ['build']
|
||||
```
|
||||
|
||||
## wait_for
|
||||
There are other ways to specify dependencies, see [wait_for](/tasks/task-configuration.html#wait-for) and [depends_post](/tasks/task-configuration.html#depends-post)
|
||||
|
||||
If a task must run after another task, you can use `wait_for`:
|
||||
|
||||
```toml
|
||||
[tasks.clean]
|
||||
run = 'cargo clean'
|
||||
|
||||
[tasks.build]
|
||||
run = 'cargo build'
|
||||
wait_for = ['clean']
|
||||
```
|
||||
|
||||
## hide
|
||||
|
||||
You can hide a task from the list of available tasks by setting `hide = true`:
|
||||
|
||||
```toml
|
||||
[tasks.cleancache]
|
||||
run = "rm -rf .cache"
|
||||
hide = true # hide this task from mise tasks ls / mise run
|
||||
```
|
||||
|
||||
## alias
|
||||
|
||||
You can specify an alias for a task. This alias can be used to run the task:
|
||||
|
||||
```toml
|
||||
[tasks.build]
|
||||
description = 'Build the CLI'
|
||||
run = "cargo build"
|
||||
alias = 'b' # `mise run b`
|
||||
```
|
||||
|
||||
## env
|
||||
### Environment variables
|
||||
|
||||
You can specify environment variables for a task:
|
||||
|
||||
|
|
@ -166,7 +154,7 @@ cargo clippy
|
|||
"""
|
||||
```
|
||||
|
||||
## sources / outputs
|
||||
### Sources / Outputs
|
||||
|
||||
If you want to skip executing a task if certain files haven't changed (up-to-date), you should specify `sources` and `outputs`:
|
||||
|
||||
|
|
@ -180,7 +168,7 @@ outputs = ['target/debug/mycli']
|
|||
|
||||
You can use `sources` alone if with [`mise watch`](/cli/watch.html) to run the task when the sources change.
|
||||
|
||||
## shell / shebang
|
||||
## Specifying a shell or an interpreter
|
||||
|
||||
Tasks are executed with `set -e` (`set -o erropt`) if the shell is `sh`, `bash`, or `zsh`. This means that the script
|
||||
will exit if any command fails. You can disable this by running `set +e` in the script.
|
||||
|
|
@ -334,7 +322,7 @@ Example: `#!/usr/bin/env -S python -u` will run Python with unbuffered output.
|
|||
|
||||
:::
|
||||
|
||||
## file
|
||||
## Using a file or remote script
|
||||
|
||||
You can specify a file to run as a task:
|
||||
|
||||
|
|
@ -356,21 +344,6 @@ file = "https://example.com/build.sh"
|
|||
Currently, they're fetched everytime they're executed, but we may add some cache support later.
|
||||
This could be extended with other protocols like mentioned in [this ticket](https://github.com/jdx/mise/issues/2488) if there were interest.
|
||||
|
||||
## raw
|
||||
|
||||
Stdin is not read by default. To enable this, set `raw = true` on the task that needs it. This will prevent
|
||||
it running in parallel with any other task. A RWMutex will get a write lock in this case.
|
||||
|
||||
```toml
|
||||
[tasks.build]
|
||||
raw = true
|
||||
run = 'echo "Enter your name:"; read name; echo "Hello, $name!"'
|
||||
```
|
||||
|
||||
## quiet
|
||||
|
||||
Set `quiet = true` to suppress mise additional output.
|
||||
|
||||
## Arguments
|
||||
|
||||
By default, arguments are passed to the last script in the `run` array. So if a task was defined as:
|
||||
|
|
|
|||
|
|
@ -126,9 +126,11 @@ _See [Environments](/environments/) for more information on working with environ
|
|||
|
||||
## Tasks
|
||||
|
||||
Tasks are defined in a project to execute commands. They are defined in `mise.toml`:
|
||||
Tasks are defined in a project to execute commands.
|
||||
|
||||
```toml
|
||||
You can define tasks in a `mise.toml`:
|
||||
|
||||
```toml [mise.toml]
|
||||
[tasks]
|
||||
build = "npm run build"
|
||||
test = "npm test"
|
||||
|
|
@ -149,35 +151,47 @@ mise run test
|
|||
```
|
||||
|
||||
:::tip
|
||||
`mise run` setups up the "mise environment" before running the task (tools and environment variables).
|
||||
`mise run` sets up the "mise environment" before running the task (tools and environment variables).
|
||||
So if you'd rather not activate mise in your shell, you can use `mise run` to run tasks, and it will
|
||||
have the tools in PATH and the environment variables from `mise.toml` set.
|
||||
:::
|
||||
|
||||
mise is paired with [usage](https://usage.jdx.dev) which provides lots of features for documenting and running tasks.
|
||||
`mise` is paired with [usage](https://usage.jdx.dev) which provides lots of features for documenting and running tasks.
|
||||
|
||||
Here is an example of a task with usage spec:
|
||||
|
||||
```bash [mise-tasks/users]
|
||||
#!/bin/bash
|
||||
#USAGE flag "-f --force" "Force the greeting to be displayed"
|
||||
#USAGE flag "-u --user <user>" "The user to greet"
|
||||
#USAGE flag "-p --port <port>" default=8080 "The port to listen on"
|
||||
#USAGE flag "-c --color <color>" "The color to use" {
|
||||
#USAGE choices "red" "green" "blue"
|
||||
#USAGE }
|
||||
#USAGE arg "message" "The message to greet the user with"
|
||||
#USAGE complete "user" run="mycli users"
|
||||
```bash [mise-tasks/greet]
|
||||
#!/usr/bin/env bash
|
||||
set -e
|
||||
|
||||
echo "Hello, $usage_user! Your message is: $usage_message"
|
||||
#MISE description="Greet a user with a message"
|
||||
#USAGE flag "-g --greeting <greeting>" help="The greeting word to use" {
|
||||
#USAGE choices "hi" "hello" "hey"
|
||||
#USAGE }
|
||||
#USAGE flag "-u --user <user>" help="The user to greet"
|
||||
#USAGE flag "--dir <dir>" help="The directory to greet from" default="."
|
||||
#USAGE complete "dir" run="find . -maxdepth 1 -type d"
|
||||
#USAGE arg "<message>" help="Greeting message"
|
||||
|
||||
echo "all available options are in the env with the prefix 'usage_'"
|
||||
env | grep usage_
|
||||
|
||||
echo "$usage_greeting, $usage_user! Your message is: $usage_message"
|
||||
```
|
||||
|
||||
The options will all be passed as environment variables prefixed with `usage_` like `usage_user`.
|
||||
Help is available with `mise run my-task --help` and will show the options defined in the task.
|
||||
Completions are available like you'd expect, so typing `mise run my-task --color <tab>` will show "red", "green", and "blue"
|
||||
as options. `mise run my-task --user <tab>` will execute `mycli users` and use the output as completions.
|
||||
This task can be run like so:
|
||||
|
||||
No extra setup is required for completions so long as [mise completions](/cli/completion) are otherwise set up.
|
||||
```shell
|
||||
mise run greet --user jdx -g "hey" "How are you?"
|
||||
```
|
||||
|
||||
- The options will all be passed as environment variables prefixed with `usage_` like `usage_user`.
|
||||
- Help is available with `mise run greet --help` and will show the options defined in the task.
|
||||
- Completions are available like you'd expect, so typing `mise run greet --greeting <tag>` will show `hi`, `hello`, and `hey`
|
||||
as options.
|
||||
- [Custom completion](https://usage.jdx.dev/spec/reference/complete) can be provided by a CLI. `mise run greet --dir <tab>` will execute `find . -maxdepth 1 -type d` to provide completions.
|
||||
|
||||
To get the autocopletion working, set up [mise autocompletions](/installing-mise.html#autocompletion).
|
||||
|
||||
_See [Tasks](/tasks/) for more information on working with tasks._
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue