go/task
go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2025-04-23 12:18:57 +02:00
Code Issues Releases Activity

Update docs to account for new feature

Browse Source
This commit is contained in:
tylermmorton 2022-01-15 23:37:39 -05:00
parent c73a2c8f84
commit 66748ab5e5
1 changed files with 75 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
docs/usage.md
View File

@ -8,7 +8,7 @@ The example below allows compiling a Go app and uses [Minify][minify] to concat
and minify multiple CSS files into a single one. and minify multiple CSS files into a single one.
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
build: build:
@ -40,7 +40,7 @@ If you omit a task name, "default" will be assumed.
You can use `env` to set custom environment variables for a specific task: You can use `env` to set custom environment variables for a specific task:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
greet: greet:
@ -54,7 +54,7 @@ Additionally, you can set globally environment variables, that'll be available
to all tasks: to all tasks:
```yaml ```yaml
version: '3' version: "3"
env: env:
GREETING: Hey, there! GREETING: Hey, there!
@ -86,12 +86,12 @@ ENDPOINT=testing.com
```yaml ```yaml
# Taskfile.yml # Taskfile.yml
version: '3' version: "3"
env: env:
ENV: testing ENV: testing
dotenv: ['.env', '{{.ENV}}/.env.', '{{.HOME}}/.env'] dotenv: [".env", "{{.ENV}}/.env.", "{{.HOME}}/.env"]
tasks: tasks:
greet: greet:
@ -105,7 +105,7 @@ If you want to share tasks between different projects (Taskfiles), you can use
the importing mechanism to include other Taskfiles using the `includes` keyword: the importing mechanism to include other Taskfiles using the `includes` keyword:
```yaml ```yaml
version: '3' version: "3"
includes: includes:
docs: ./documentation # will look for ./documentation/Taskfile.yml docs: ./documentation # will look for ./documentation/Taskfile.yml
@ -126,7 +126,7 @@ was removed on version 3, but you still can have a similar behavior by
explicitly importing these files: explicitly importing these files:
```yaml ```yaml
version: '3' version: "3"
includes: includes:
build: ./Taskfile_{{OS}}.yml build: ./Taskfile_{{OS}}.yml
@ -139,7 +139,7 @@ if the Taskfile is in another directory, but you can force its tasks to run
in another directory by using this alternative syntax: in another directory by using this alternative syntax:
```yaml ```yaml
version: '3' version: "3"
includes: includes:
docs: docs:
@ -150,17 +150,13 @@ includes:
> The included Taskfiles must be using the same schema version the main > The included Taskfiles must be using the same schema version the main
> Taskfile uses. > Taskfile uses.
> Also, for now included Taskfiles can't include other Taskfiles.
> This was a deliberate decision to keep use and implementation simple.
> If you disagree, open an GitHub issue and explain your use case. =)
### Optional includes ### Optional includes
Includes marked as optional will allow Task to continue execution as normal if Includes marked as optional will allow Task to continue execution as normal if
the included file is missing. the included file is missing.
```yaml ```yaml
version: '3' version: "3"
includes: includes:
tests: tests:
@ -180,7 +176,7 @@ located. But you can easily make the task run in another folder informing
`dir`: `dir`:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
serve: serve:
@ -202,7 +198,7 @@ You may have tasks that depend on others. Just pointing them on `deps` will
make them run automatically before running the parent task: make them run automatically before running the parent task:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
build: build:
@ -221,7 +217,7 @@ In the above example, `assets` will always run right before `build` if you run
A task can have only dependencies and no commands to group tasks together: A task can have only dependencies and no commands to group tasks together:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
assets: assets:
@ -246,15 +242,15 @@ If you want to pass information to dependencies, you can do that the same
manner as you would to [call another task](#calling-another-task): manner as you would to [call another task](#calling-another-task):
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
default: default:
deps: deps:
- task: echo_sth - task: echo_sth
vars: {TEXT: "before 1"} vars: { TEXT: "before 1" }
- task: echo_sth - task: echo_sth
vars: {TEXT: "before 2"} vars: { TEXT: "before 2" }
cmds: cmds:
- echo "after" - echo "after"
@ -270,7 +266,7 @@ often result in a faster build pipeline. But in some situations you may need
to call other tasks serially. In this case, just use the following syntax: to call other tasks serially. In this case, just use the following syntax:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
main-task: main-task:
@ -292,7 +288,7 @@ Overriding variables in the called task is as simple as informing `vars`
attribute: attribute:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
greet: greet:
@ -304,7 +300,7 @@ tasks:
greet-pessimistically: greet-pessimistically:
cmds: cmds:
- task: greet - task: greet
vars: {RECIPIENT: "Cruel World"} vars: { RECIPIENT: "Cruel World" }
``` ```
The above syntax is also supported in `deps`. The above syntax is also supported in `deps`.
@ -321,7 +317,7 @@ If a task generates something, you can inform Task the source and generated
files, so Task will prevent to run them if not necessary. files, so Task will prevent to run them if not necessary.
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
build: build:
@ -357,7 +353,7 @@ If you prefer this check to be made by the modification timestamp of the files,
instead of its checksum (content), just set the `method` property to `timestamp`. instead of its checksum (content), just set the `method` property to `timestamp`.
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
build: build:
@ -382,7 +378,7 @@ Alternatively, you can inform a sequence of tests as `status`. If no error
is returned (exit status 0), the task is considered up-to-date: is returned (exit status 0), the task is considered up-to-date:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
generate-files: generate-files:
@ -421,13 +417,13 @@ the tasks are not up-to-date.
### Using programmatic checks to cancel execution of an task and it's dependencies ### Using programmatic checks to cancel execution of an task and it's dependencies
In addition to `status` checks, there are also `preconditions` checks, which are In addition to `status` checks, there are also `preconditions` checks, which are
the logical inverse of `status` checks. That is, if you need a certain set of the logical inverse of `status` checks. That is, if you need a certain set of
conditions to be _true_ you can use the `preconditions` stanza. conditions to be _true_ you can use the `preconditions` stanza.
`preconditions` are similar to `status` lines except they support `sh` `preconditions` are similar to `status` lines except they support `sh`
expansion and they SHOULD all return 0. expansion and they SHOULD all return 0.
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
generate-files: generate-files:
@ -446,7 +442,7 @@ Preconditions can set specific failure messages that can tell
a user what steps to take using the `msg` field. a user what steps to take using the `msg` field.
If a task has a dependency on a sub-task with a precondition, and that If a task has a dependency on a sub-task with a precondition, and that
precondition is not met - the calling task will fail. Note that a task precondition is not met - the calling task will fail. Note that a task
executed with a failing precondition will not run unless `--force` is executed with a failing precondition will not run unless `--force` is
given. given.
@ -455,7 +451,7 @@ executing tasks that depend on it, a `precondition` will fail a task, along
with any other tasks that depend on it. with any other tasks that depend on it.
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
task-will-fail: task-will-fail:
@ -481,24 +477,24 @@ overridden.
Supported values for `run`: Supported values for `run`:
* `always` (default) always attempt to invoke the task regardless of the - `always` (default) always attempt to invoke the task regardless of the
number of previous executions number of previous executions
* `once` only invoke this task once regardless of the number of references - `once` only invoke this task once regardless of the number of references
* `when_changed` only invokes the task once for each unique set of variables - `when_changed` only invokes the task once for each unique set of variables
passed into the task passed into the task
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
default: default:
cmds: cmds:
- task: generate-file - task: generate-file
vars: { CONTENT: '1' } vars: { CONTENT: "1" }
- task: generate-file - task: generate-file
vars: { CONTENT: '2' } vars: { CONTENT: "2" }
- task: generate-file - task: generate-file
vars: { CONTENT: '2' } vars: { CONTENT: "2" }
generate-file: generate-file:
run: when_changed run: when_changed
@ -543,7 +539,7 @@ $ task write-file FILE=file.txt "CONTENT=Hello, World!" print "MESSAGE=All done!
Example of locally declared vars: Example of locally declared vars:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
print-var: print-var:
@ -556,7 +552,7 @@ tasks:
Example of global vars in a `Taskfile.yml`: Example of global vars in a `Taskfile.yml`:
```yaml ```yaml
version: '3' version: "3"
vars: vars:
GREETING: Hello from Taskfile! GREETING: Hello from Taskfile!
@ -574,7 +570,7 @@ The value will be treated as a command and the output assigned. If there is one
or more trailing newlines, the last newline will be trimmed. or more trailing newlines, the last newline will be trimmed.
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
build: build:
@ -600,7 +596,7 @@ $ task yarn -- install
``` ```
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
yarn: yarn:
@ -617,7 +613,7 @@ that this command will run even when the task fails.
In the example below `rm -rf tmpdir/` will run even if the third command fails: In the example below `rm -rf tmpdir/` will run even if the third command fails:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
default: default:
@ -631,7 +627,7 @@ If you want to move the cleanup command into another task, that's possible as
well: well:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
default: default:
@ -644,8 +640,8 @@ tasks:
``` ```
> NOTE: Due to the nature of how the > NOTE: Due to the nature of how the
[Go's own `defer` work](https://go.dev/tour/flowcontrol/13), the deferred > [Go's own `defer` work](https://go.dev/tour/flowcontrol/13), the deferred
commands are executed in the reverse order if you schedule multiple of them. > commands are executed in the reverse order if you schedule multiple of them.
## Go's template engine ## Go's template engine
@ -656,7 +652,7 @@ All functions by the Go's [slim-sprig lib](https://go-task.github.io/slim-sprig/
are available. The following example gets the current date in a given format: are available. The following example gets the current date in a given format:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
print-date: print-date:
@ -685,7 +681,7 @@ Task also adds the following functions:
Example: Example:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
print-os: print-os:
@ -713,7 +709,7 @@ Running `task --list` (or `task -l`) lists all tasks with a description.
The following Taskfile: The following Taskfile:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
build: build:
@ -750,7 +746,7 @@ Running `task --summary task-name` will show a summary of a task.
The following Taskfile: The following Taskfile:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
release: release:
@ -768,7 +764,7 @@ tasks:
- your-build-tool - your-build-tool
``` ```
with running ``task --summary release`` would print the following output: with running `task --summary release` would print the following output:
``` ```
task: release task: release
@ -784,10 +780,11 @@ dependencies:
commands: commands:
- your-release-tool - your-release-tool
``` ```
If a summary is missing, the description will be printed. If a summary is missing, the description will be printed.
If the task does not have a summary or a description, a warning is printed. If the task does not have a summary or a description, a warning is printed.
Please note: *showing the summary will not execute the command*. Please note: _showing the summary will not execute the command_.
## Overriding task name ## Overriding task name
@ -796,7 +793,7 @@ messages to STDOUT, etc. In this case you can just set `label:`, which can also
be interpolated with variables: be interpolated with variables:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
default: default:
@ -808,7 +805,7 @@ tasks:
MESSAGE: world MESSAGE: world
print: print:
label: 'print-{{.MESSAGE}}' label: "print-{{.MESSAGE}}"
cmds: cmds:
- echo "{{.MESSAGE}}" - echo "{{.MESSAGE}}"
``` ```
@ -819,7 +816,7 @@ Silent mode disables echoing of commands before Task runs it.
For the following Taskfile: For the following Taskfile:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
echo: echo:
@ -842,10 +839,10 @@ Print something
There are four ways to enable silent mode: There are four ways to enable silent mode:
* At command level: - At command level:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
echo: echo:
@ -854,10 +851,10 @@ tasks:
silent: true silent: true
``` ```
* At task level: - At task level:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
echo: echo:
@ -866,10 +863,10 @@ tasks:
silent: true silent: true
``` ```
* Globally at Taskfile level: - Globally at Taskfile level:
```yaml ```yaml
version: '3' version: "3"
silent: true silent: true
@ -879,12 +876,12 @@ tasks:
- echo "Print something" - echo "Print something"
``` ```
* Or globally with `--silent` or `-s` flag - Or globally with `--silent` or `-s` flag
If you want to suppress STDOUT instead, just redirect a command to `/dev/null`: If you want to suppress STDOUT instead, just redirect a command to `/dev/null`:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
echo: echo:
@ -903,7 +900,7 @@ You have the option to ignore errors during command execution.
Given the following Taskfile: Given the following Taskfile:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
echo: echo:
@ -916,7 +913,7 @@ Task will abort the execution after running `exit 1` because the status code `1`
However it is possible to continue with execution using `ignore_error`: However it is possible to continue with execution using `ignore_error`:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
echo: echo:
@ -947,24 +944,24 @@ options you can choose:
To choose another one, just set it to root in the Taskfile: To choose another one, just set it to root in the Taskfile:
```yaml ```yaml
version: '3' version: "3"
output: 'group' output: "group"
tasks: tasks:
# ... # ...
``` ```
The `group` output will print the entire output of a command once, after it 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 finishes, so you won't have live feedback for commands that take a long time
to run. to run.
The `prefix` output will prefix every line printed by a command with 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 `[task-name] ` as the prefix, but you can customize the prefix for a command
with the `prefix:` attribute: with the `prefix:` attribute:
```yaml ```yaml
version: '3' version: "3"
output: prefixed output: prefixed
@ -972,11 +969,11 @@ tasks:
default: default:
deps: deps:
- task: print - task: print
vars: {TEXT: foo} vars: { TEXT: foo }
- task: print - task: print
vars: {TEXT: bar} vars: { TEXT: bar }
- task: print - task: print
vars: {TEXT: baz} vars: { TEXT: baz }
print: print:
cmds: cmds:
@ -1005,7 +1002,7 @@ The `interactive: true` tells Task this is an interactive application, and Task
will try to optimize for it: will try to optimize for it:
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
cmds: cmds:
@ -1022,7 +1019,7 @@ Starting on Task v3, you can now write tasks with a shorter syntax if they
have the default settings (e.g. no custom `env:`, `vars:`, `desc:`, `silent:` , etc): have the default settings (e.g. no custom `env:`, `vars:`, `desc:`, `silent:` , etc):
```yaml ```yaml
version: '3' version: "3"
tasks: tasks:
build: go build -v -o ./app{{exeExt}} . build: go build -v -o ./app{{exeExt}} .