mirror of
https://github.com/go-task/task.git
synced 2025-04-25 12:25:07 +02:00
0e23404d23
* feat: specify init filename with --taskfile flag
previously, it was not possible to specify which filename to use when initializing a new Taskfile as it was hardcoded as "Taskfile.yml".
now the --taskfile flag specifies where to write the file to, and the first * contained in it will be replaced by "Taskfile", so `task -it *.yaml` will create a `Taskfile.yaml` file.
* docs: update CLI reference
* fix Flags header being inside tip admonition
* change -t flag's default column and add a description
* add Default Filenames section
* docs: revert adding Default Filenames section
I didn't realize it already existed elsewhere.
* refactor: use path instead of filepath on InitTaskFile
as requested to prevent ambiguity with the stdlib package.
* fix TestInit (incorrectly merged)
* docs: remove outdated info on --taskfile flag
* refactor task initialization changes
- remove const DefaultTaskInitFilename from taskfile/taskfile.go
- revert description of Entrypoint flag
- make InitTaskfile accept a path to either a file or a directory, and join the default Taskfile name+ext to it if it is a directory
- take the target file path from the first argument instead of the Entrypoint flag
- detect extension-only filenames (".yaml") instead of replacing "*" with "Taskfile"
- use different format in success log so that it makes sense at different paths than the current dir
* print colon instead of "at"
it's a lot cleaner in most cases.
* rewrite init tests
test both initializing to a directory path and a file path
* return final path from InitTaskfile
...and print it's relative representation
* fix lint error (ineffassign)
* use filepathext.TryAbsToRel() instead
* define and use filepathext.IsExtOnly()
* link to default filenames list in cli ref docs
(specifically in the --taskfile flag description)
121 lines
11 KiB
Plaintext
121 lines
11 KiB
Plaintext
---
|
|
slug: /reference/cli
|
|
sidebar_position: 1
|
|
---
|
|
|
|
# CLI Reference
|
|
|
|
Task CLI commands have the following syntax:
|
|
|
|
```shell
|
|
task [--flags] [tasks...] [-- CLI_ARGS...]
|
|
```
|
|
|
|
:::tip
|
|
|
|
If `--` is given, all remaining arguments will be assigned to a special
|
|
`CLI_ARGS` variable
|
|
|
|
:::
|
|
|
|
## Flags
|
|
|
|
| Short | Flag | Type | Default | Description |
|
|
| ----- | --------------------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `-c` | `--color` | `bool` | `true` | Colored output. Enabled by default. Set flag to `false` or use `NO_COLOR=1` to disable. |
|
|
| `-C` | `--concurrency` | `int` | `0` | Limit number tasks to run concurrently. Zero means unlimited. |
|
|
| `-d` | `--dir` | `string` | Working directory | Sets directory of execution. |
|
|
| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
|
|
| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
|
|
| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
|
|
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
|
|
| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
|
|
| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
|
|
| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
|
|
| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
|
|
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
|
|
| | `--sort` | `string` | `default` | Changes the order of the tasks when listed.<br />`default` - Alphanumeric with root tasks first<br />`alphanumeric` - Alphanumeric<br />`none` - No sorting (As they appear in the Taskfile) |
|
|
| | `--json` | `bool` | `false` | See [JSON Output](#json-output) |
|
|
| `-o` | `--output` | `string` | Default set in the Taskfile or `interleaved` | Sets output style: [`interleaved`/`group`/`prefixed`]. |
|
|
| | `--output-group-begin` | `string` | | Message template to print before a task's grouped output. |
|
|
| | `--output-group-end` | `string` | | Message template to print after a task's grouped output. |
|
|
| | `--output-group-error-only` | `bool` | `false` | Swallow command output on zero exit code. |
|
|
| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
|
|
| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
|
|
| `-y` | `--yes` | `bool` | `false` | Assume "yes" as answer to all prompts. |
|
|
| | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. |
|
|
| | `--summary` | `bool` | `false` | Show summary about a task. |
|
|
| `-t` | `--taskfile` | `string` | | Taskfile path to run.<br />Check the list of default filenames [here](../usage/#supported-file-names). |
|
|
| `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. |
|
|
| | `--version` | `bool` | `false` | Show Task version. |
|
|
| `-w` | `--watch` | `bool` | `false` | Enables watch of the given task.
|
|
|
|
## Exit Codes
|
|
|
|
Task will sometimes exit with specific exit codes. These codes are split into
|
|
four groups with the following ranges:
|
|
|
|
- Success (0)
|
|
- General errors (1-99)
|
|
- Taskfile errors (100-199)
|
|
- Task errors (200-255)
|
|
|
|
A full list of the exit codes and their descriptions can be found below:
|
|
|
|
| Code | Description |
|
|
|------|---------------------------------------------------------------------|
|
|
| 0 | Success |
|
|
| 1 | An unknown error occurred |
|
|
| 100 | No Taskfile was found |
|
|
| 101 | A Taskfile already exists when trying to initialize one |
|
|
| 102 | The Taskfile is invalid or cannot be parsed |
|
|
| 103 | A remote Taskfile could not be downloaded |
|
|
| 104 | A remote Taskfile was not trusted by the user |
|
|
| 105 | A remote Taskfile was could not be fetched securely |
|
|
| 106 | No cache was found for a remote Taskfile in offline mode |
|
|
| 107 | No schema version was defined in the Taskfile |
|
|
| 200 | The specified task could not be found |
|
|
| 201 | An error occurred while executing a command inside of a task |
|
|
| 202 | The user tried to invoke a task that is internal |
|
|
| 203 | There a multiple tasks with the same name or alias |
|
|
| 204 | A task was called too many times |
|
|
| 205 | A task was cancelled by the user |
|
|
| 206 | A task was not executed due to missing required variables |
|
|
| 207 | A task was not executed due to a variable having an incorrect value |
|
|
|
|
These codes can also be found in the repository in
|
|
[`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).
|
|
|
|
:::info
|
|
|
|
When Task is run with the `-x`/`--exit-code` flag, the exit code of any failed
|
|
commands will be passed through to the user instead.
|
|
|
|
:::
|
|
|
|
## JSON Output
|
|
|
|
When using the `--json` flag in combination with either the `--list` or
|
|
`--list-all` flags, the output will be a JSON object with the following
|
|
structure:
|
|
|
|
```json
|
|
{
|
|
"tasks": [
|
|
{
|
|
"name": "",
|
|
"desc": "",
|
|
"summary": "",
|
|
"up_to_date": false,
|
|
"location": {
|
|
"line": 54,
|
|
"column": 3,
|
|
"taskfile": "/path/to/Taskfile.yml"
|
|
}
|
|
}
|
|
// ...
|
|
],
|
|
"location": "/path/to/Taskfile.yml"
|
|
}
|
|
```
|