diff --git a/docs/docs/api_reference.md b/docs/docs/api_reference.md index 87c39b71..19a476b1 100644 --- a/docs/docs/api_reference.md +++ b/docs/docs/api_reference.md @@ -35,7 +35,7 @@ variable | `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. | | `-o` | `--output` | `string` | Default set in the Taskfile or `intervealed` | 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-end` | `string` | | Message template to print after a task's grouped output. | | `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. | | `-s` | `--silent` | `bool` | `false` | Disables echoing. | | | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. | @@ -80,16 +80,16 @@ Some environment variables can be overriden to adjust Task behavior. | Attribute | Type | Default | Description | | - | - | - | - | | `version` | `string` | | Version of the Taskfile. The current version is `3`. | -| `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. | | `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. | | `method` | `string` | `checksum` | Default method in this Taskfile. Can be overriden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. | -| `silent` | `bool` | `false` | Default "silent" options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis. | -| `run` | `string` | `always` | Default "run" option for this Taskfile. Available options: `always`, `once` and `when_changed`. | -| `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). | -| `vars` | [`map[string]Variable`](#variable) | | Global variables. | -| `env` | [`map[string]Variable`](#variable) | | Global environment. | +| `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. | +| `vars` | [`map[string]Variable`](#variable) | | A set of global variables. | +| `env` | [`map[string]Variable`](#variable) | | A set of global environment variables. | +| `tasks` | [`map[string]Task`](#task) | | A set of task definitions. | +| `silent` | `bool` | `false` | Default 'silent' options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis. | | `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. | -| `tasks` | [`map[string]Task`](#task) | | The task definitions. | +| `run` | `string` | `always` | Default 'run' option for this Taskfile. Available options: `always`, `once` and `when_changed`. | +| `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). | ### Include @@ -98,8 +98,9 @@ Some environment variables can be overriden to adjust Task behavior. | `taskfile` | `string` | | The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile. | | `dir` | `string` | The parent Taskfile directory | The working directory of the included tasks when run. | | `optional` | `bool` | `false` | If `true`, no errors will be thrown if the specified file does not exist. | -| `internal` | `bool` | `false` | If `true`, tasks will not be callable from the command line and will be omitted from both `--list` and `--list-all`. | +| `internal` | `bool` | `false` | Stops any task in the included Taskfile from being callable on the command line. These commands will also be omitted from the output when used with `--list`. | | `aliases` | `[]string` | | Alternative names for the namespace of the included Taskfile. | +| `vars` | `map[string]Variable` | | A set of variables to apply to the included Taskfile. | :::info @@ -116,25 +117,26 @@ includes: | Attribute | Type | Default | Description | | - | - | - | - | -| `desc` | `string` | | A short description of the task. This is listed when calling `task --list`. | -| `summary` | `string` | | A longer description of the task. This is listed when calling `task --summary [task]`. | -| `aliases` | `[]string` | | Alternative names for the task. | +| `cmds` | [`[]Command`](#command) | | A list of shell commands to be executed. | +| `deps` | [`[]Dependency`](#dependency) | | A list of dependencies of this task. Tasks defined here will run in parallel before this task. | | `label` | `string` | | Overrides the name of the task in the output when a task is run. Supports variables. | -| `sources` | `[]string` | | List of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. | -| `dir` | `string` | | The current directory which this task should run. | -| `method` | `string` | `checksum` | Method used by this task. Default to the one declared globally or `checksum`. Available options: `checksum`, `timestamp` and `none` | -| `silent` | `bool` | `false` | Skips some output for this task. Note that STDOUT and STDERR of the commands will still be redirected. | -| `internal` | `bool` | `false` | If `true`, this task will not be callable from the command line and will be omitted from both `--list` and `--list-all`. | +| `desc` | `string` | | A short description of the task. This is displayed when calling `task --list`. | +| `summary` | `string` | | A longer description of the task. This is displayed when calling `task --summary [task]`. | +| `aliases` | `[]string` | | A list of alternative names by which the task can be called. | +| `sources` | `[]string` | | A list of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. | +| `generates` | `[]string` | | A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs. | +| `status` | `[]string` | | A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`. | +| `preconditions` | [`[]Precondition`](#precondition) | | A list of commands to check if this task should run. If a condition is not met, the task will error. | +| `dir` | `string` | | The directory in which this task should run. Defaults to the current working directory. | +| `vars` | [`map[string]Variable`](#variable) | | A set of variables that can be used in the task. | +| `env` | [`map[string]Variable`](#variable) | | A set of environment variables that will be made available to shell commands. | +| `silent` | `bool` | `false` | Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`. When combined with the `--list` flag, task descriptions will be hidden. | +| `interactive` | `bool` | `false` | Tells task that the command is interactive. | +| `internal` | `bool` | `false` | Stops a task from being callable on the command line. It will also be omitted from the output when used with `--list`. | +| `method` | `string` | `checksum` | Defines which method is used to check the task is up-to-date. `timestamp` will compare the timestamp of the sources and generates files. `checksum` will check the checksum (You probably want to ignore the .task folder in your .gitignore file). `none` skips any validation and always run the task. | +| `prefix` | `string` | | Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`. | +| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing commands. | | `run` | `string` | The one declared globally in the Taskfile or `always` | Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`. | -| `prefix` | `string` | | Allows to override the prefix print before the STDOUT. Only relevant when using the `prefixed` output mode. | -| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the commands. | -| `generates` | `[]string` | | List of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs. | -| `status` | `[]string` | | List of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`. | -| `preconditions` | [`[]Precondition`](#precondition) | | List of commands to check if this task should run. The task errors otherwise. | -| `vars` | [`map[string]Variable`](#variable) | | Task variables. | -| `env` | [`map[string]Variable`](#variable) | | Task environment. | -| `deps` | [`[]Dependency`](#dependency) | | List of dependencies of this task. | -| `cmds` | [`[]Command`](#command) | | List of commands to be executed. | :::info @@ -180,11 +182,11 @@ tasks: | Attribute | Type | Default | Description | | - | - | - | - | | `cmd` | `string` | | The shell command to be executed. | -| `defer` | `string` | | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`. | | `silent` | `bool` | `false` | Skips some output for this command. Note that STDOUT and STDERR of the commands will still be redirected. | -| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the command. | | `task` | `string` | | Set this to trigger execution of another task instead of running a command. This cannot be set together with `cmd`. | | `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to the referenced task. Only relevant when setting `task` instead of `cmd`. | +| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the command. | +| `defer` | `string` | | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`. | :::info diff --git a/docs/schema.json b/docs/schema.json new file mode 100644 index 00000000..fa9afba3 --- /dev/null +++ b/docs/schema.json @@ -0,0 +1,384 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "title": "Taskfile YAML Schema", + "description": "Schema for Taskfile files.", + "definitions": { + "3": { + "env": { + "$ref": "#/definitions/3/vars" + }, + "tasks": { + "type": "object", + "patternProperties": { + "^.*$": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "$ref": "#/definitions/3/task_call" + } + ] + } + }, + { + "$ref": "#/definitions/3/task" + } + ] + } + } + }, + "task": { + "type": "object", + "additionalProperties": false, + "properties": { + "cmds": { + "description": "A list of commands to be executed.", + "$ref": "#/definitions/3/cmds" + }, + "deps": { + "description": "A list of dependencies of this task. Tasks defined here will run in parallel before this task.", + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "$ref": "#/definitions/3/task_call" + } + ] + } + }, + "label": { + "description": "Overrides the name of the task in the output when a task is run. Supports variables.", + "type": "string" + }, + "desc": { + "description": "A short description of the task. This is displayed when calling `task --list`.", + "type": "string" + }, + "summary": { + "description": "A longer description of the task. This is displayed when calling `task --summary [task]`.", + "type": "string" + }, + "aliases": { + "description": "A list of alternative names by which the task can be called.", + "type": "array", + "items": { + "type": "string" + } + }, + "sources": { + "description": "A list of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs.", + "type": "array", + "items": { + "type": "string" + } + }, + "generates": { + "description": "A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs.", + "type": "array", + "items": { + "type": "string" + } + }, + "status": { + "description": "A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`.", + "type": "array", + "items": { + "type": "string" + } + }, + "preconditions": { + "description": "A list of commands to check if this task should run. If a condition is not met, the task will error.", + "type": "array", + "items": { + "$ref": "#/definitions/3/precondition" + } + }, + "dir": { + "description": "The directory in which this task should run. Defaults to the current working directory.", + "type": "string" + }, + "vars": { + "description": "A set of variables that can be used in the task.", + "$ref": "#/definitions/3/vars" + }, + "env": { + "description": "A set of environment variables that will be made available to shell commands.", + "$ref": "#/definitions/3/env" + }, + "silent": { + "description": "Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`. When combined with the `--list` flag, task descriptions will be hidden.", + "type": "boolean", + "default": false + }, + "interactive": { + "description": "Tells task that the command is interactive.", + "type": "boolean", + "default": false + }, + "internal": { + "description": "Stops a task from being callable on the command line. It will also be omitted from the output when used with `--list`.", + "type": "boolean", + "default": false + }, + "method": { + "description": "Defines which method is used to check the task is up-to-date. `timestamp` will compare the timestamp of the sources and generates files. `checksum` will check the checksum (You probably want to ignore the .task folder in your .gitignore file). `none` skips any validation and always run the task.", + "type": "string", + "enum": ["none", "checksum", "timestamp"], + "default": "none" + }, + "prefix": { + "description": "Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`.", + "type": "string" + }, + "ignore_error": { + "description": "Continue execution if errors happen while executing commands.", + "type": "boolean" + }, + "run": { + "description": "Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`.", + "$ref": "#/definitions/3/run" + } + } + }, + "cmds": { + "type": "array", + "items": { + "$ref": "#/definitions/3/cmd" + } + }, + "cmd": { + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "#/definitions/3/cmd_call" + }, + { + "$ref": "#/definitions/3/task_call" + } + ] + }, + "vars": { + "type": "object", + "patternProperties": { + "^.*$": { + "anyOf": [ + { + "type": ["boolean", "integer", "null", "number", "string"] + }, + { + "$ref": "#/definitions/3/dynamic_var" + } + ] + } + } + }, + "dynamic_var": { + "type": "object", + "properties": { + "sh": { + "type": "string", + "description": "The value will be treated as a command and the output assigned" + }, + "additionalProperties": false + } + }, + "task_call": { + "type": "object", + "properties": { + "task": { + "description": "Name of the task to run", + "type": "string" + }, + "vars": { + "description": "Values passed to the task called", + "$ref": "#/definitions/3/vars" + } + } + }, + "cmd_call": { + "type": "object", + "properties": { + "cmd": { + "description": "Command to run", + "type": "string" + }, + "silent": { + "description": "Silent mode disables echoing of command before Task runs it", + "type": "boolean" + }, + "ignore_error": { + "description": "Prevent command from aborting the execution of task even after receiving a status code of 1", + "type": "boolean" + }, + "defer": { + "description": "", + "type": "boolean" + } + }, + "additionalProperties": false, + "required": ["cmd"] + }, + "precondition": { + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "#/definitions/3/precondition_obj" + } + ] + }, + "precondition_obj": { + "type": "object", + "properties": { + "sh": { + "description": "Command to run. If that command returns 1, the condition will fail", + "type": "string" + }, + "msg": { + "description": "Failure message to display when the condition fails", + "type": "string" + } + } + }, + "run": { + "type": "string", + "enum": ["always", "once", "when_changed"] + } + } + }, + "oneOf": [ + { + "type": "object", + "properties": { + "version": { + "description": "Specify the Taskfile format that this file conforms to.", + "anyOf": [ + { + "type": "number", + "enum": [3] + }, + { + "type": "string", + "enum": ["3"] + } + ] + }, + "output": { + "description": "Defines how the STDOUT and STDERR are printed when running tasks in parallel. The interleaved output prints lines in real time (default). The group output will print the entire output of a command once, after it finishes, so you won't have live feedback for commands that take a long time to run. The prefix output will prefix every line printed by a command with [task-name] as the prefix, but you can customize the prefix for a command with the prefix: attribute.", + "type": "string", + "enum": ["interleaved", "group", "prefixed"], + "default": "interleaved" + }, + "method": { + "description": "Defines which method is used to check the task is up-to-date. (default: checksum)", + "type": "string", + "enum": ["none", "checksum", "timestamp"], + "default": "checksum" + }, + "includes": { + "description": "Imports tasks from the specified taskfiles. The tasks described in the given Taskfiles will be available with the informed namespace.", + "type": "object", + "patternProperties": { + "^.*$": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "object", + "properties": { + "taskfile": { + "description": "The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile.", + "type": "string" + }, + "dir": { + "description": "The working directory of the included tasks when run.", + "type": "string" + }, + "optional": { + "description": "If `true`, no errors will be thrown if the specified file does not exist.", + "type": "boolean" + }, + "internal": { + "description": "Stops any task in the included Taskfile from being callable on the command line. These commands will also be omitted from the output when used with `--list`.", + "type": "boolean" + }, + "aliases": { + "description": "Alternative names for the namespace of the included Taskfile.", + "type": "array", + "items": { + "type": "string" + } + }, + "vars": { + "description": "A set of variables to apply to the included Taskfile.", + "$ref": "#/definitions/3/vars" + } + } + } + ] + } + } + }, + "vars": { + "description": "A set of global variables.", + "$ref": "#/definitions/3/vars" + }, + "env": { + "description": "A set of global environment variables.", + "$ref": "#/definitions/3/env" + }, + "tasks": { + "description": "A set of task definitions.", + "$ref": "#/definitions/3/tasks" + }, + "silent": { + "description": "Default 'silent' options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis.", + "type": "boolean" + }, + "dotenv": { + "type": "array", + "description": "A list of `.env` file paths to be parsed.", + "items": { + "type": "string" + } + }, + "run": { + "description": "Default 'run' option for this Taskfile. Available options: `always`, `once` and `when_changed`.", + "$ref": "#/definitions/3/run" + }, + "interval": { + "description": "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.", + "$ref": "#/definitions/3/run" + } + }, + "additionalProperties": false, + "required": ["version"], + "anyOf": [ + { + "required": ["includes"] + }, + { + "required": ["tasks"] + }, + { + "required": ["includes", "tasks"] + } + ] + } + ] +}