Skip to content

Commit a160baa

Browse files
pd93pd93
committed
chore: update schema/docs to match
- Also reorder them both to match the struct definitions. This makes it easier to compare them
1 parent f408e8f commit a160baa

File tree

2 files changed

+114
-83
lines changed

2 files changed

+114
-83
lines changed

‎docs/docs/api_reference.md

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ variable
3535
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
3636
| `-o` | `--output` | `string` | Default set in the Taskfile or `intervealed` | Sets output style: [`interleaved`/`group`/`prefixed`]. |
3737
| | `--output-group-begin` | `string` | | Message template to print before a task's grouped output. |
38-
| | `--output-group-end ` | `string` | | Message template to print after a task's grouped output. |
38+
| | `--output-group-end` | `string` | | Message template to print after a task's grouped output. |
3939
| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
4040
| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
4141
| | `--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.
8080
| Attribute | Type | Default | Description |
8181
| - | - | - | - |
8282
| `version` | `string` | | Version of the Taskfile. The current version is `3`. |
83-
| `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. |
8483
| `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. |
8584
| `method` | `string` | `checksum` | Default method in this Taskfile. Can be overriden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. |
86-
| `silent` | `bool` | `false` | Default "silent" options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis. |
87-
| `run` | `string` | `always` | Default "run" option for this Taskfile. Available options: `always`, `once` and `when_changed`. |
88-
| `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). |
85+
| `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. |
8986
| `vars` | [`map[string]Variable`](#variable) | | Global variables. |
9087
| `env` | [`map[string]Variable`](#variable) | | Global environment. |
91-
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
9288
| `tasks` | [`map[string]Task`](#task) | | The task definitions. |
89+
| `silent` | `bool` | `false` | Default "silent" options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis. |
90+
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
91+
| `run` | `string` | `always` | Default "run" option for this Taskfile. Available options: `always`, `once` and `when_changed`. |
92+
| `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). |
9393

9494
### Include
9595

@@ -98,8 +98,9 @@ Some environment variables can be overriden to adjust Task behavior.
9898
| `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. |
9999
| `dir` | `string` | The parent Taskfile directory | The working directory of the included tasks when run. |
100100
| `optional` | `bool` | `false` | If `true`, no errors will be thrown if the specified file does not exist. |
101-
| `internal` | `bool` | `false` | If `true`, tasks will not be callable from the command line and will be omitted from both `--list` and `--list-all`. |
101+
| `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`. |
102102
| `aliases` | `[]string` | | Alternative names for the namespace of the included Taskfile. |
103+
| `vars` | `map[string]Variable` | | A set of variables to apply to the included Taskfile. |
103104

104105
:::info
105106

@@ -116,25 +117,26 @@ includes:
116117
117118
| Attribute | Type | Default | Description |
118119
| - | - | - | - |
119-
| `desc` | `string` | | A short description of the task. This is listed when calling `task --list`. |
120-
| `summary` | `string` | | A longer description of the task. This is listed when calling `task --summary [task]`. |
121-
| `aliases` | `[]string` | | Alternative names for the task. |
120+
| `cmds` | [`[]Command`](#command) | | A list of commands to be executed. |
121+
| `deps` | [`[]Dependency`](#dependency) | | A list of dependencies of this task. Tasks defined here will run in parallel before this task. |
122122
| `label` | `string` | | Overrides the name of the task in the output when a task is run. Supports variables. |
123-
| `sources` | `[]string` | | List of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. |
124-
| `dir` | `string` | | The current directory which this task should run. |
125-
| `method` | `string` | `checksum` | Method used by this task. Default to the one declared globally or `checksum`. Available options: `checksum`, `timestamp` and `none` |
126-
| `silent` | `bool` | `false` | Skips some output for this task. Note that STDOUT and STDERR of the commands will still be redirected. |
127-
| `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`. |
123+
| `desc` | `string` | | A short description of the task. This is displayed when calling `task --list`. |
124+
| `summary` | `string` | | A longer description of the task. This is displayed when calling `task --summary [task]`. |
125+
| `aliases` | `[]string` | | A list of alternative names by which the task can be called. |
126+
| `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. |
127+
| `generates` | `[]string` | | A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs. |
128+
| `status` | `[]string` | | A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`. |
129+
| `preconditions` | [`[]Precondition`](#precondition) | | A list of commands to check if this task should run. If a condition is not met, the task will error. |
130+
| `dir` | `string` | | The directory in which this task should run. Defaults to the current working directory. |
131+
| `vars` | [`map[string]Variable`](#variable) | | A set of variables that can be used in the task. |
132+
| `env` | [`map[string]Variable`](#variable) | | A set of environment variables that will be made available to shell commands. |
133+
| `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. |
134+
| `interactive` | `bool` | `false` | Tells task that the command is interactive. |
135+
| `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`. |
136+
| `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. |
137+
| `prefix` | `string` | | Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`. |
138+
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing commands. |
128139
| `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`. |
129-
| `prefix` | `string` | | Allows to override the prefix print before the STDOUT. Only relevant when using the `prefixed` output mode. |
130-
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the commands. |
131-
| `generates` | `[]string` | | List of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs. |
132-
| `status` | `[]string` | | List of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`. |
133-
| `preconditions` | [`[]Precondition`](#precondition) | | List of commands to check if this task should run. The task errors otherwise. |
134-
| `vars` | [`map[string]Variable`](#variable) | | Task variables. |
135-
| `env` | [`map[string]Variable`](#variable) | | Task environment. |
136-
| `deps` | [`[]Dependency`](#dependency) | | List of dependencies of this task. |
137-
| `cmds` | [`[]Command`](#command) | | List of commands to be executed. |
138140

139141
:::info
140142

‎schema/taskfile-schema.json

Lines changed: 88 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
{
22
"$schema": "http://json-schema.org/draft-07/schema",
3+
"title": "Taskfile YAML Schema",
4+
"description": "Schema for Taskfile files.",
35
"definitions": {
46
"3": {
57
"env": {
@@ -37,40 +39,12 @@
3739
"type": "object",
3840
"additionalProperties": false,
3941
"properties": {
40-
"env": {
41-
"description": "Environment variables for this task",
42-
"$ref": "#/definitions/3/env"
43-
},
44-
"desc": {
45-
"description": "Provides a description for this task. Used by the --list/-l flag",
46-
"type": "string"
47-
},
48-
"summary": {
49-
"description": "Provides a summary for this task. Used by the --summary flag",
50-
"type": "string"
51-
},
52-
"vars": {
53-
"description": "Declare variables for this task",
54-
"$ref": "#/definitions/3/vars"
55-
},
56-
"label": {
57-
"type": "string",
58-
"description": "Override the task name print on summary, can be interpolated with variables"
59-
},
60-
"run": {
61-
"description": "Controls whether or not this task runs when called by multiple deps or cmds.",
62-
"$ref": "#/definitions/3/run"
63-
},
6442
"cmds": {
65-
"description": "A list of commands for this task",
43+
"description": "A list of commands to be executed.",
6644
"$ref": "#/definitions/3/cmds"
6745
},
68-
"dir": {
69-
"description": "Defines where the task will run. Defaults to the directory of the Taskfile",
70-
"type": "string"
71-
},
7246
"deps": {
73-
"description": "Declaring tasks here that should run automatically before this task",
47+
"description": "A list of dependencies of this task. Tasks defined here will run in parallel before this task.",
7448
"type": "array",
7549
"items": {
7650
"oneOf": [
@@ -83,59 +57,97 @@
8357
]
8458
}
8559
},
60+
"label": {
61+
"description": "Overrides the name of the task in the output when a task is run. Supports variables.",
62+
"type": "string"
63+
},
64+
"desc": {
65+
"description": "A short description of the task. This is displayed when calling `task --list`.",
66+
"type": "string"
67+
},
68+
"summary": {
69+
"description": "A longer description of the task. This is displayed when calling `task --summary [task]`.",
70+
"type": "string"
71+
},
72+
"aliases": {
73+
"description": "A list of alternative names by which the task can be called.",
74+
"type": "array",
75+
"items": {
76+
"type": "string"
77+
}
78+
},
8679
"sources": {
87-
"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.",
80+
"description": "A list of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs.",
8881
"type": "array",
8982
"items": {
9083
"type": "string"
9184
}
9285
},
9386
"generates": {
94-
"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.",
87+
"description": "A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs.",
9588
"type": "array",
9689
"items": {
9790
"type": "string"
9891
}
9992
},
10093
"status": {
101-
"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",
94+
"description": "A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`.",
10295
"type": "array",
10396
"items": {
10497
"type": "string"
10598
}
10699
},
107-
"method": {
108-
"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",
109-
"type": "string",
110-
"enum": [ "none", "checksum", "timestamp" ],
111-
"default": "none"
100+
"preconditions": {
101+
"description": "A list of commands to check if this task should run. If a condition is not met, the task will error.",
102+
"type": "array",
103+
"items": {
104+
"$ref": "#/definitions/3/precondition"
105+
}
112106
},
113-
"internal": {
114-
"description": "Indicates that the task cannot be called directly by the user",
115-
"type": "boolean"
107+
"dir": {
108+
"description": "The directory in which this task should run. Defaults to the current working directory.",
109+
"type": "string"
110+
},
111+
"vars": {
112+
"description": "A set of variables that can be used in the task.",
113+
"$ref": "#/definitions/3/vars"
114+
},
115+
"env": {
116+
"description": "A set of environment variables that will be made available to shell commands.",
117+
"$ref": "#/definitions/3/env"
116118
},
117119
"silent": {
118-
"description": "Silent mode disables echoing of commands before Task runs it",
119-
"type": "boolean"
120+
"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.",
121+
"type": "boolean",
122+
"default": false
120123
},
121-
"ignore_error": {
122-
"description": "Prevent Task from aborting the execution of tasks even after receiving a status code of 1",
123-
"type": "boolean"
124+
"interactive": {
125+
"description": "Tells task that the command is interactive.",
126+
"type": "boolean",
127+
"default": false
128+
},
129+
"internal": {
130+
"description": "Stops a task from being callable on the command line. It will also be omitted from the output when used with `--list`.",
131+
"type": "boolean",
132+
"default": false
133+
},
134+
"method": {
135+
"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.",
136+
"type": "string",
137+
"enum": [ "none", "checksum", "timestamp" ],
138+
"default": "none"
124139
},
125140
"prefix": {
126-
"description": "Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is prefix",
141+
"description": "Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`.",
127142
"type": "string"
128143
},
129-
"preconditions": {
130-
"description": "Defines a list of conditions to be true for the task to run",
131-
"type": "array",
132-
"items": {
133-
"$ref": "#/definitions/3/precondition"
134-
}
135-
},
136-
"interactive": {
137-
"description": "Indicates that this task runs an interactive CLI application",
144+
"ignore_error": {
145+
"description": "Continue execution if errors happen while executing commands.",
138146
"type": "boolean"
147+
},
148+
"run": {
149+
"description": "Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`.",
150+
"$ref": "#/definitions/3/run"
139151
}
140152
}
141153
},
@@ -244,7 +256,6 @@
244256
}
245257
}
246258
},
247-
"description": "JSON Schema for Taskfile files.",
248259
"oneOf": [
249260
{
250261
"type": "object",
@@ -291,6 +302,25 @@
291302
"dir": {
292303
"description": "On which directory the included Taskfile will run",
293304
"type": "string"
305+
},
306+
"optional": {
307+
"description": "If `true`, no errors will be thrown if the specified file does not exist.",
308+
"type": "boolean"
309+
},
310+
"internal": {
311+
"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`.",
312+
"type": "boolean"
313+
},
314+
"aliases": {
315+
"description": "Alternative names for the namespace of the included Taskfile.",
316+
"type": "array",
317+
"items": {
318+
"type": "string"
319+
}
320+
},
321+
"vars": {
322+
"description": "A set of variables to apply to the included Taskfile.",
323+
"$ref": "#/definitions/3/vars"
294324
}
295325
}
296326
}
@@ -341,6 +371,5 @@
341371
}
342372
]
343373
}
344-
],
345-
"title": "Taskfile YAML Schema"
374+
]
346375
}

0 commit comments

Comments
 (0)