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 index c60b6eab..fa9afba3 100644 --- a/docs/schema.json +++ b/docs/schema.json @@ -1,5 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema", + "title": "Taskfile YAML Schema", + "description": "Schema for Taskfile files.", "definitions": { "3": { "env": { @@ -37,40 +39,12 @@ "type": "object", "additionalProperties": false, "properties": { - "env": { - "description": "Environment variables for this task", - "$ref": "#/definitions/3/env" - }, - "desc": { - "description": "Provides a description for this task. Used by the --list/-l flag", - "type": "string" - }, - "summary": { - "description": "Provides a summary for this task. Used by the --summary flag", - "type": "string" - }, - "vars": { - "description": "Declare variables for this task", - "$ref": "#/definitions/3/vars" - }, - "label": { - "type": "string", - "description": "Override the task name print on summary, can be interpolated with variables" - }, - "run": { - "description": "Controls whether or not this task runs when called by multiple deps or cmds.", - "$ref": "#/definitions/3/run" - }, "cmds": { - "description": "A list of commands for this task", + "description": "A list of commands to be executed.", "$ref": "#/definitions/3/cmds" }, - "dir": { - "description": "Defines where the task will run. Defaults to the directory of the Taskfile", - "type": "string" - }, "deps": { - "description": "Declaring tasks here that should run automatically before this task", + "description": "A list of dependencies of this task. Tasks defined here will run in parallel before this task.", "type": "array", "items": { "oneOf": [ @@ -83,59 +57,97 @@ ] } }, + "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": "List the source files for this task. Will be used to prevent running the task again if nothing changed. Can be a file of a file pattern.", + "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": "List the files generated by this task. Will be used to prevent running the task again if nothing changed. Can be a file of a file pattern.", + "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": "Define a sequence of tests as status of this task. If no error is returned (exit status 0), the task is considered up-to-date", + "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" } }, - "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 will 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" - }, - "internal": { - "description": "Indicates that the task cannot be called directly by the user", - "type": "boolean" - }, - "silent": { - "description": "Silent mode disables echoing of commands before Task runs it", - "type": "boolean" - }, - "ignore_error": { - "description": "Prevent Task from aborting the execution of tasks even after receiving a status code of 1", - "type": "boolean" - }, - "prefix": { - "description": "Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is prefix", - "type": "string" - }, "preconditions": { - "description": "Defines a list of conditions to be true for the task to run", + "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": "Indicates that this task runs an interactive CLI application", + "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" } } }, @@ -210,6 +222,10 @@ "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, @@ -244,7 +260,6 @@ } } }, - "description": "JSON Schema for Taskfile files.", "oneOf": [ { "type": "object", @@ -262,19 +277,20 @@ } ] }, - "env": { - "description": "Declare environment variables globally", - "$ref": "#/definitions/3/env" + "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" }, - "dotenv": { - "type": "array", - "description": "Ask Task to include .env file", - "items": { - "type": "string" - } + "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 other tasks from the provided taskfile. The tasks described in the given Taskfiles will be available with the informed namespace.", + "description": "Imports tasks from the specified taskfiles. The tasks described in the given Taskfiles will be available with the informed namespace.", "type": "object", "patternProperties": { "^.*$": { @@ -286,11 +302,31 @@ "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": "On which directory the included Taskfile will run", + "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" } } } @@ -298,32 +334,35 @@ } } }, - "silent": { - "description": "Silent mode disables echoing of commands for all tasks", - "type": "boolean" - }, - "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" - }, "vars": { - "description": "Declare variables globally", + "description": "A set of global variables.", "$ref": "#/definitions/3/vars" }, + "env": { + "description": "A set of global environment variables.", + "$ref": "#/definitions/3/env" + }, "tasks": { - "description": "Defines your 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 behavior when tasks are executed as part of deps or other cmds", + "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" } }, @@ -341,6 +380,5 @@ } ] } - ], - "title": "Taskfile YAML Schema" + ] }