2018-09-22 23:44:24 +02:00
|
|
|
# Usage
|
|
|
|
|
|
|
|
## Getting started
|
|
|
|
|
|
|
|
Create a file called `Taskfile.yml` in the root of your project.
|
|
|
|
The `cmds` attribute should contain the commands of a task.
|
|
|
|
The example below allows compiling a Go app and uses [Minify][minify] to concat
|
|
|
|
and minify multiple CSS files into a single one.
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
build:
|
|
|
|
cmds:
|
|
|
|
- go build -v -i main.go
|
|
|
|
|
|
|
|
assets:
|
|
|
|
cmds:
|
|
|
|
- minify -o public/style.css src/css
|
|
|
|
```
|
|
|
|
|
|
|
|
Running the tasks is as simple as running:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
task assets build
|
|
|
|
```
|
|
|
|
|
|
|
|
Task uses [github.com/mvdan/sh](https://github.com/mvdan/sh), a native Go sh
|
|
|
|
interpreter. So you can write sh/bash commands and it will work even on
|
|
|
|
Windows, where `sh` or `bash` are usually not available. Just remember any
|
|
|
|
executable called must be available by the OS or in PATH.
|
|
|
|
|
2019-01-02 17:21:21 +02:00
|
|
|
If you omit a task name, "default" will be assumed.
|
2018-09-22 23:44:24 +02:00
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
## Environment
|
2018-09-22 23:44:24 +02:00
|
|
|
|
2019-01-02 17:21:21 +02:00
|
|
|
You can use `env` to set custom environment variables for a specific task:
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
2019-01-02 17:21:21 +02:00
|
|
|
greet:
|
2018-09-22 23:44:24 +02:00
|
|
|
cmds:
|
2019-01-02 17:21:21 +02:00
|
|
|
- echo $GREETING
|
2018-09-22 23:44:24 +02:00
|
|
|
env:
|
2019-01-02 17:21:21 +02:00
|
|
|
GREETING: Hey, there!
|
2018-09-22 23:44:24 +02:00
|
|
|
```
|
|
|
|
|
2019-01-02 17:21:21 +02:00
|
|
|
Additionally, you can set globally environment variables, that'll be available
|
|
|
|
to all tasks:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
env:
|
|
|
|
GREETING: Hey, there!
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
greet:
|
|
|
|
cmds:
|
|
|
|
- echo $GREETING
|
|
|
|
```
|
|
|
|
|
2019-11-08 12:01:57 +02:00
|
|
|
> NOTE: `env` supports expansion and retrieving output from a shell command
|
2019-01-02 17:21:21 +02:00
|
|
|
> just like variables, as you can see on the [Variables](#variables) section.
|
|
|
|
|
2018-10-13 23:14:42 +02:00
|
|
|
## Operating System specific tasks
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
If you add a `Taskfile_{{GOOS}}.yml` you can override or amend your Taskfile
|
|
|
|
based on the operating system.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
Taskfile.yml:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
build:
|
|
|
|
cmds:
|
|
|
|
- echo "default"
|
|
|
|
```
|
|
|
|
|
|
|
|
Taskfile_linux.yml:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
build:
|
|
|
|
cmds:
|
|
|
|
- echo "linux"
|
|
|
|
```
|
|
|
|
|
|
|
|
Will print out `linux` and not `default`.
|
|
|
|
|
|
|
|
Keep in mind that the version of the files should match. Also, when redefining
|
|
|
|
a task the whole task is replaced, properties of the task are not merged.
|
|
|
|
|
|
|
|
It's also possible to have an OS specific `Taskvars.yml` file, like
|
2018-12-27 02:11:36 +02:00
|
|
|
`Taskvars_windows.yml`, `Taskvars_linux.yml`, or `Taskvars_darwin.yml`. See the
|
2018-09-22 23:44:24 +02:00
|
|
|
[variables section](#variables) below.
|
|
|
|
|
2018-10-13 23:14:42 +02:00
|
|
|
## Including other Taskfiles
|
|
|
|
|
2018-12-09 19:57:13 +02:00
|
|
|
> This feature is still experimental and may have bugs.
|
|
|
|
|
2018-10-13 23:14:42 +02:00
|
|
|
If you want to share tasks between different projects (Taskfiles), you can use
|
|
|
|
the importing mechanism to include other Taskfiles using the `includes` keyword:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
includes:
|
|
|
|
docs: ./documentation # will look for ./documentation/Taskfile.yml
|
|
|
|
docker: ./DockerTasks.yml
|
|
|
|
```
|
|
|
|
|
|
|
|
The tasks described in the given Taskfiles will be available with the informed
|
|
|
|
namespace. So, you'd call `task docs:serve` to run the `serve` task from
|
|
|
|
`documentation/Taskfile.yml` or `task docker:build` to run the `build` task
|
|
|
|
from the `DockerTasks.yml` file.
|
|
|
|
|
|
|
|
> The included Taskfiles must be using the same schema version the main
|
|
|
|
> 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. =)
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
## Task directory
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
By default, tasks will be executed in the directory where the Taskfile is
|
|
|
|
located. But you can easily make the task run in another folder informing
|
|
|
|
`dir`:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
serve:
|
|
|
|
dir: public/www
|
|
|
|
cmds:
|
|
|
|
# run http server
|
|
|
|
- caddy
|
|
|
|
```
|
|
|
|
|
2019-06-16 11:33:00 +02:00
|
|
|
If the directory doesn't exist, `task` creates it.
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
## Task dependencies
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
You may have tasks that depend on others. Just pointing them on `deps` will
|
|
|
|
make them run automatically before running the parent task:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
build:
|
|
|
|
deps: [assets]
|
|
|
|
cmds:
|
|
|
|
- go build -v -i main.go
|
|
|
|
|
|
|
|
assets:
|
|
|
|
cmds:
|
|
|
|
- minify -o public/style.css src/css
|
|
|
|
```
|
|
|
|
|
|
|
|
In the above example, `assets` will always run right before `build` if you run
|
|
|
|
`task build`.
|
|
|
|
|
|
|
|
A task can have only dependencies and no commands to group tasks together:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
assets:
|
|
|
|
deps: [js, css]
|
|
|
|
|
|
|
|
js:
|
|
|
|
cmds:
|
|
|
|
- minify -o public/script.js src/js
|
|
|
|
|
|
|
|
css:
|
|
|
|
cmds:
|
|
|
|
- minify -o public/style.css src/css
|
|
|
|
```
|
|
|
|
|
|
|
|
If there is more than one dependency, they always run in parallel for better
|
|
|
|
performance.
|
|
|
|
|
2019-11-16 04:31:01 +02:00
|
|
|
> You can also make the tasks given by the command line run in parallel by
|
|
|
|
> using the `--parallel` flag (alias `-p`). Example: `task --parallel js css`.
|
|
|
|
|
2018-09-22 23:44:24 +02:00
|
|
|
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):
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
default:
|
|
|
|
deps:
|
|
|
|
- task: echo_sth
|
|
|
|
vars: {TEXT: "before 1"}
|
|
|
|
- task: echo_sth
|
|
|
|
vars: {TEXT: "before 2"}
|
|
|
|
cmds:
|
|
|
|
- echo "after"
|
|
|
|
|
|
|
|
echo_sth:
|
|
|
|
cmds:
|
|
|
|
- echo {{.TEXT}}
|
|
|
|
```
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
## Calling another task
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
When a task has many dependencies, they are executed concurrently. This will
|
|
|
|
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:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
main-task:
|
|
|
|
cmds:
|
|
|
|
- task: task-to-be-called
|
|
|
|
- task: another-task
|
|
|
|
- echo "Both done"
|
|
|
|
|
|
|
|
task-to-be-called:
|
|
|
|
cmds:
|
|
|
|
- echo "Task to be called"
|
|
|
|
|
|
|
|
another-task:
|
|
|
|
cmds:
|
|
|
|
- echo "Another task"
|
|
|
|
```
|
|
|
|
|
|
|
|
Overriding variables in the called task is as simple as informing `vars`
|
|
|
|
attribute:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
main-task:
|
|
|
|
cmds:
|
|
|
|
- task: write-file
|
|
|
|
vars: {FILE: "hello.txt", CONTENT: "Hello!"}
|
|
|
|
- task: write-file
|
|
|
|
vars: {FILE: "world.txt", CONTENT: "World!"}
|
|
|
|
|
|
|
|
write-file:
|
|
|
|
cmds:
|
|
|
|
- echo "{{.CONTENT}}" > {{.FILE}}
|
|
|
|
```
|
|
|
|
|
|
|
|
The above syntax is also supported in `deps`.
|
|
|
|
|
2019-02-03 01:12:57 +02:00
|
|
|
> NOTE: If you want to call a task declared in the root Taskfile from within an
|
|
|
|
> [included Taskfile](#including-other-taskfiles), add a leading `:` like this:
|
|
|
|
> `task: :task-name`.
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
## Prevent unnecessary work
|
2018-09-22 23:44:24 +02:00
|
|
|
|
2019-08-25 19:30:00 +02:00
|
|
|
### By fingerprinting locally generated files and their sources
|
|
|
|
|
2018-09-22 23:44:24 +02:00
|
|
|
If a task generates something, you can inform Task the source and generated
|
|
|
|
files, so Task will prevent to run them if not necessary.
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
build:
|
|
|
|
deps: [js, css]
|
|
|
|
cmds:
|
|
|
|
- go build -v -i main.go
|
|
|
|
|
|
|
|
js:
|
|
|
|
cmds:
|
|
|
|
- minify -o public/script.js src/js
|
|
|
|
sources:
|
|
|
|
- src/js/**/*.js
|
|
|
|
generates:
|
|
|
|
- public/script.js
|
|
|
|
|
|
|
|
css:
|
|
|
|
cmds:
|
|
|
|
- minify -o public/style.css src/css
|
|
|
|
sources:
|
|
|
|
- src/css/**/*.css
|
|
|
|
generates:
|
|
|
|
- public/style.css
|
|
|
|
```
|
|
|
|
|
|
|
|
`sources` and `generates` can be files or file patterns. When both are given,
|
|
|
|
Task will compare the modification date/time of the files to determine if it's
|
|
|
|
necessary to run the task. If not, it will just print a message like
|
|
|
|
`Task "js" is up to date`.
|
|
|
|
|
|
|
|
If you prefer this check to be made by the content of the files, instead of
|
|
|
|
its timestamp, just set the `method` property to `checksum`.
|
|
|
|
You will probably want to ignore the `.task` folder in your `.gitignore` file
|
|
|
|
(It's there that Task stores the last checksum).
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
build:
|
|
|
|
cmds:
|
|
|
|
- go build .
|
|
|
|
sources:
|
|
|
|
- ./*.go
|
|
|
|
generates:
|
|
|
|
- app{{exeExt}}
|
|
|
|
method: checksum
|
|
|
|
```
|
|
|
|
|
|
|
|
> TIP: method `none` skips any validation and always run the task.
|
|
|
|
|
2019-08-25 19:30:00 +02:00
|
|
|
### Using programmatic checks to indicate a task is up to date.
|
|
|
|
|
2018-09-22 23:44:24 +02:00
|
|
|
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:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
generate-files:
|
|
|
|
cmds:
|
|
|
|
- mkdir directory
|
|
|
|
- touch directory/file1.txt
|
|
|
|
- touch directory/file2.txt
|
|
|
|
# test existence of files
|
|
|
|
status:
|
|
|
|
- test -d directory
|
|
|
|
- test -f directory/file1.txt
|
|
|
|
- test -f directory/file2.txt
|
|
|
|
```
|
|
|
|
|
2019-08-25 19:30:00 +02:00
|
|
|
Normally, you would use `sources` in combination with
|
2019-06-18 03:57:25 +02:00
|
|
|
`generates` - but for tasks that generate remote artifacts (Docker images,
|
2019-06-11 20:49:37 +02:00
|
|
|
deploys, CD releases) the checksum source and timestamps require either
|
|
|
|
access to the artifact or for an out-of-band refresh of the `.checksum`
|
|
|
|
fingerprint file.
|
|
|
|
|
|
|
|
Two special variables `{{.CHECKSUM}}` and `{{.TIMESTAMP}}` are available
|
|
|
|
for interpolation within `status` commands, depending on the method assigned
|
2019-09-14 22:54:41 +02:00
|
|
|
to fingerprint the sources. Only `source` globs are fingerprinted.
|
2019-06-11 20:49:37 +02:00
|
|
|
|
2019-09-14 22:54:41 +02:00
|
|
|
Note that the `{{.TIMESTAMP}}` variable is a "live" Go `time.Time` struct, and
|
|
|
|
can be formatted using any of the methods that `time.Time` responds to.
|
2019-08-25 22:16:59 +02:00
|
|
|
|
|
|
|
See [the Go Time documentation](https://golang.org/pkg/time/) for more information.
|
|
|
|
|
2018-09-22 23:44:24 +02:00
|
|
|
You can use `--force` or `-f` if you want to force a task to run even when
|
|
|
|
up-to-date.
|
|
|
|
|
|
|
|
Also, `task --status [tasks]...` will exit with a non-zero exit code if any of
|
|
|
|
the tasks are not up-to-date.
|
|
|
|
|
2019-08-25 19:30:00 +02:00
|
|
|
### 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
|
|
|
|
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.
|
|
|
|
`preconditions` are similar to `status` lines except they support `sh`
|
|
|
|
expansion and they SHOULD all return 0.
|
2019-05-17 22:13:47 +02:00
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
generate-files:
|
|
|
|
cmds:
|
|
|
|
- mkdir directory
|
|
|
|
- touch directory/file1.txt
|
|
|
|
- touch directory/file2.txt
|
|
|
|
# test existence of files
|
|
|
|
preconditions:
|
|
|
|
- test -f .env
|
|
|
|
- sh: "[ 1 = 0 ]"
|
|
|
|
msg: "One doesn't equal Zero, Halting"
|
|
|
|
```
|
|
|
|
|
|
|
|
Preconditions can set specific failure messages that can tell
|
2019-05-28 22:16:37 +02:00
|
|
|
a user what steps to take using the `msg` field.
|
2019-05-17 22:13:47 +02:00
|
|
|
|
|
|
|
If a task has a dependency on a sub-task with a precondition, and that
|
2019-05-28 22:16:37 +02:00
|
|
|
precondition is not met - the calling task will fail. Note that a task
|
|
|
|
executed with a failing precondition will not run unless `--force` is
|
|
|
|
given.
|
|
|
|
|
|
|
|
Unlike `status` which will skip a task if it is up to date, and continue
|
2019-06-11 20:46:22 +02:00
|
|
|
executing tasks that depend on it, a `precondition` will fail a task, along
|
2019-05-28 22:16:37 +02:00
|
|
|
with any other tasks that depend on it.
|
2019-05-17 22:13:47 +02:00
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
tasks:
|
|
|
|
task_will_fail:
|
|
|
|
preconditions:
|
|
|
|
- sh: "exit 1"
|
|
|
|
|
2019-05-28 22:16:37 +02:00
|
|
|
task_will_also_fail:
|
2019-06-11 20:46:22 +02:00
|
|
|
deps:
|
|
|
|
- task_will_fail
|
2019-05-17 22:13:47 +02:00
|
|
|
|
2019-05-28 22:16:37 +02:00
|
|
|
task_will_still_fail:
|
2019-06-11 20:46:22 +02:00
|
|
|
cmds:
|
|
|
|
- task: task_will_fail
|
|
|
|
- echo "I will not run"
|
2019-05-17 22:13:47 +02:00
|
|
|
```
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
## Variables
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
When doing interpolation of variables, Task will look for the below.
|
|
|
|
They are listed below in order of importance (e.g. most important first):
|
|
|
|
|
2019-08-11 00:50:47 +02:00
|
|
|
- Variables declared in the task definition
|
2018-09-22 23:44:24 +02:00
|
|
|
- Variables given while calling a task from another.
|
|
|
|
(See [Calling another task](#calling-another-task) above)
|
|
|
|
- Variables declared in the `vars:` option in the `Taskfile`
|
|
|
|
- Variables available in the `Taskvars.yml` file
|
|
|
|
- Environment variables
|
|
|
|
|
|
|
|
Example of sending parameters with environment variables:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ TASK_VARIABLE=a-value task do-something
|
|
|
|
```
|
|
|
|
|
|
|
|
Since some shells don't support above syntax to set environment variables
|
|
|
|
(Windows) tasks also accepts a similar style when not in the beginning of
|
|
|
|
the command. Variables given in this form are only visible to the task called
|
|
|
|
right before.
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ task write-file FILE=file.txt "CONTENT=Hello, World!" print "MESSAGE=All done!"
|
|
|
|
```
|
|
|
|
|
2019-05-11 16:06:47 +02:00
|
|
|
If you want to set global variables using this syntax, give it before any task:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ task OUTPUT=file.txt generate-file
|
|
|
|
```
|
|
|
|
|
2018-09-22 23:44:24 +02:00
|
|
|
Example of locally declared vars:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
print-var:
|
|
|
|
cmds:
|
2019-06-11 10:35:10 +02:00
|
|
|
- echo "{{.VAR}}"
|
2018-09-22 23:44:24 +02:00
|
|
|
vars:
|
|
|
|
VAR: Hello!
|
|
|
|
```
|
|
|
|
|
|
|
|
Example of global vars in a `Taskfile.yml`:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
vars:
|
|
|
|
GREETING: Hello from Taskfile!
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
greet:
|
|
|
|
cmds:
|
|
|
|
- echo "{{.GREETING}}"
|
|
|
|
```
|
|
|
|
|
|
|
|
Example of `Taskvars.yml` file:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
PROJECT_NAME: My Project
|
|
|
|
DEV_MODE: production
|
|
|
|
GIT_COMMIT: {sh: git log -n 1 --format=%h}
|
|
|
|
```
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
### Variables expansion
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
Variables are expanded 2 times by default. You can change that by setting the
|
|
|
|
`expansions:` option. Change that will be necessary if you compose many
|
|
|
|
variables together:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
expansions: 3
|
|
|
|
|
|
|
|
vars:
|
|
|
|
FOO: foo
|
|
|
|
BAR: bar
|
|
|
|
BAZ: baz
|
|
|
|
FOOBAR: "{{.FOO}}{{.BAR}}"
|
|
|
|
FOOBARBAZ: "{{.FOOBAR}}{{.BAZ}}"
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
default:
|
|
|
|
cmds:
|
|
|
|
- echo "{{.FOOBARBAZ}}"
|
|
|
|
```
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
### Dynamic variables
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
The below syntax (`sh:` prop in a variable) is considered a dynamic variable.
|
|
|
|
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.
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
build:
|
|
|
|
cmds:
|
|
|
|
- go build -ldflags="-X main.Version={{.GIT_COMMIT}}" main.go
|
|
|
|
vars:
|
|
|
|
GIT_COMMIT:
|
|
|
|
sh: git log -n 1 --format=%h
|
|
|
|
```
|
|
|
|
|
|
|
|
This works for all types of variables.
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
## Go's template engine
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
Task parse commands as [Go's template engine][gotemplate] before executing
|
|
|
|
them. Variables are accessible through dot syntax (`.VARNAME`).
|
|
|
|
|
2019-06-23 03:48:53 +02:00
|
|
|
All functions by the Go's [slim-sprig lib](https://go-task.github.io/slim-sprig/)
|
2018-09-22 23:44:24 +02:00
|
|
|
are available. The following example gets the current date in a given format:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
print-date:
|
|
|
|
cmds:
|
|
|
|
- echo {{now | date "2006-01-02"}}
|
|
|
|
```
|
|
|
|
|
|
|
|
Task also adds the following functions:
|
|
|
|
|
|
|
|
- `OS`: Returns operating system. Possible values are "windows", "linux",
|
|
|
|
"darwin" (macOS) and "freebsd".
|
|
|
|
- `ARCH`: return the architecture Task was compiled to: "386", "amd64", "arm"
|
|
|
|
or "s390x".
|
|
|
|
- `splitLines`: Splits Unix (\n) and Windows (\r\n) styled newlines.
|
|
|
|
- `catLines`: Replaces Unix (\n) and Windows (\r\n) styled newlines with a space.
|
|
|
|
- `toSlash`: Does nothing on Unix, but on Windows converts a string from `\`
|
|
|
|
path format to `/`.
|
2019-01-02 17:25:58 +02:00
|
|
|
- `fromSlash`: Opposite of `toSlash`. Does nothing on Unix, but on Windows
|
2018-09-22 23:44:24 +02:00
|
|
|
converts a string from `\` path format to `/`.
|
|
|
|
- `exeExt`: Returns the right executable extension for the current OS
|
|
|
|
(`".exe"` for Windows, `""` for others).
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
print-os:
|
|
|
|
cmds:
|
|
|
|
- echo '{{OS}} {{ARCH}}'
|
|
|
|
- echo '{{if eq OS "windows"}}windows-command{{else}}unix-command{{end}}'
|
|
|
|
# This will be path/to/file on Unix but path\to\file on Windows
|
|
|
|
- echo '{{fromSlash "path/to/file"}}'
|
|
|
|
enumerated-file:
|
|
|
|
vars:
|
|
|
|
CONTENT: |
|
|
|
|
foo
|
|
|
|
bar
|
|
|
|
cmds:
|
|
|
|
- |
|
|
|
|
cat << EOF > output.txt
|
|
|
|
{{range $i, $line := .CONTENT | splitLines -}}
|
|
|
|
{{printf "%3d" $i}}: {{$line}}
|
|
|
|
{{end}}EOF
|
|
|
|
```
|
|
|
|
|
2018-09-23 20:06:43 +02:00
|
|
|
## Help
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
Running `task --list` (or `task -l`) lists all tasks with a description.
|
2019-01-02 17:25:58 +02:00
|
|
|
The following Taskfile:
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
build:
|
|
|
|
desc: Build the go binary.
|
|
|
|
cmds:
|
|
|
|
- go build -v -i main.go
|
|
|
|
|
|
|
|
test:
|
|
|
|
desc: Run all the go tests.
|
|
|
|
cmds:
|
|
|
|
- go test -race ./...
|
|
|
|
|
|
|
|
js:
|
|
|
|
cmds:
|
|
|
|
- minify -o public/script.js src/js
|
|
|
|
|
|
|
|
css:
|
|
|
|
cmds:
|
|
|
|
- minify -o public/style.css src/css
|
|
|
|
```
|
|
|
|
|
|
|
|
would print the following output:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
* build: Build the go binary.
|
|
|
|
* test: Run all the go tests.
|
|
|
|
```
|
|
|
|
|
2019-02-24 20:10:44 +02:00
|
|
|
## Display summary of task
|
2019-02-24 12:52:31 +02:00
|
|
|
|
2019-02-24 20:02:44 +02:00
|
|
|
Running `task --summary task-name` will show a summary of a task
|
2019-02-24 12:52:31 +02:00
|
|
|
The following Taskfile:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
release:
|
2019-02-24 20:02:44 +02:00
|
|
|
deps: [build]
|
|
|
|
summary: |
|
2019-02-24 12:52:31 +02:00
|
|
|
Release your project to github
|
|
|
|
|
2019-02-24 20:02:44 +02:00
|
|
|
It will build your project before starting the release it.
|
2019-02-24 12:52:31 +02:00
|
|
|
Please make sure that you have set GITHUB_TOKEN before starting.
|
|
|
|
cmds:
|
|
|
|
- your-release-tool
|
2019-03-03 19:56:42 +02:00
|
|
|
|
2019-02-24 20:02:44 +02:00
|
|
|
build:
|
|
|
|
cmds:
|
|
|
|
- your-build-tool
|
2019-02-24 12:52:31 +02:00
|
|
|
```
|
|
|
|
|
2019-02-24 20:02:44 +02:00
|
|
|
with running ``task --summary release`` would print the following output:
|
2019-02-24 12:52:31 +02:00
|
|
|
|
|
|
|
```
|
2019-02-24 20:02:44 +02:00
|
|
|
task: release
|
|
|
|
|
2019-02-24 12:52:31 +02:00
|
|
|
Release your project to github
|
|
|
|
|
2019-02-24 20:02:44 +02:00
|
|
|
It will build your project before starting the release it.
|
2019-02-24 13:00:45 +02:00
|
|
|
Please make sure that you have set GITHUB_TOKEN before starting.
|
2019-02-24 20:02:44 +02:00
|
|
|
|
|
|
|
dependencies:
|
|
|
|
- build
|
|
|
|
|
|
|
|
commands:
|
|
|
|
- your-release-tool
|
2019-02-24 12:52:31 +02:00
|
|
|
```
|
2019-05-11 16:06:47 +02:00
|
|
|
If a summary is missing, the description will be printed.
|
2019-02-24 20:02:44 +02:00
|
|
|
If the task does not have a summary or a description, a warning is printed.
|
2019-02-24 12:52:31 +02:00
|
|
|
|
2019-03-03 20:43:23 +02:00
|
|
|
Please note: *showing the summary will not execute the command*.
|
2019-02-24 12:52:31 +02:00
|
|
|
|
2018-09-22 23:44:24 +02:00
|
|
|
## Silent mode
|
|
|
|
|
|
|
|
Silent mode disables echoing of commands before Task runs it.
|
|
|
|
For the following Taskfile:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
echo:
|
|
|
|
cmds:
|
|
|
|
- echo "Print something"
|
|
|
|
```
|
|
|
|
|
|
|
|
Normally this will be print:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
echo "Print something"
|
|
|
|
Print something
|
|
|
|
```
|
|
|
|
|
|
|
|
With silent mode on, the below will be print instead:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
Print something
|
|
|
|
```
|
|
|
|
|
|
|
|
There's three ways to enable silent mode:
|
|
|
|
|
|
|
|
* At command level:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
echo:
|
|
|
|
cmds:
|
|
|
|
- cmd: echo "Print something"
|
|
|
|
silent: true
|
|
|
|
```
|
|
|
|
|
|
|
|
* At task level:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
echo:
|
|
|
|
cmds:
|
|
|
|
- echo "Print something"
|
|
|
|
silent: true
|
|
|
|
```
|
|
|
|
|
|
|
|
* Or globally with `--silent` or `-s` flag
|
|
|
|
|
2019-01-02 17:25:58 +02:00
|
|
|
If you want to suppress STDOUT instead, just redirect a command to `/dev/null`:
|
2018-09-22 23:44:24 +02:00
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
echo:
|
|
|
|
cmds:
|
|
|
|
- echo "This will print nothing" > /dev/null
|
|
|
|
```
|
|
|
|
|
|
|
|
## Dry run mode
|
|
|
|
|
|
|
|
Dry run mode (`--dry`) compiles and steps through each task, printing the commands
|
|
|
|
that would be run without executing them. This is useful for debugging your Taskfiles.
|
|
|
|
|
|
|
|
## Ignore errors
|
|
|
|
|
|
|
|
You have the option to ignore errors during command execution.
|
|
|
|
Given the following Taskfile:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
echo:
|
|
|
|
cmds:
|
|
|
|
- exit 1
|
|
|
|
- echo "Hello World"
|
|
|
|
```
|
|
|
|
|
|
|
|
Task will abort the execution after running `exit 1` because the status code `1` stands for `EXIT_FAILURE`.
|
|
|
|
However it is possible to continue with execution using `ignore_error`:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
echo:
|
|
|
|
cmds:
|
|
|
|
- cmd: exit 1
|
|
|
|
ignore_error: true
|
|
|
|
- echo "Hello World"
|
|
|
|
```
|
|
|
|
|
2019-01-21 14:36:04 +02:00
|
|
|
`ignore_error` can also be set for a task, which mean errors will be suppressed
|
2018-09-22 23:44:24 +02:00
|
|
|
for all commands. But keep in mind this option won't propagate to other tasks
|
|
|
|
called either by `deps` or `cmds`!
|
|
|
|
|
|
|
|
## Output syntax
|
|
|
|
|
|
|
|
By default, Task just redirect the STDOUT and STDERR of the running commands
|
|
|
|
to the shell in real time. This is good for having live feedback for log
|
|
|
|
printed by commands, but the output can become messy if you have multiple
|
|
|
|
commands running at the same time and printing lots of stuff.
|
|
|
|
|
|
|
|
To make this more customizable, there are currently three different output
|
|
|
|
options you can choose:
|
|
|
|
|
|
|
|
- `interleaved` (default)
|
|
|
|
- `group`
|
|
|
|
- `prefixed`
|
|
|
|
|
|
|
|
To choose another one, just set it to root in the Taskfile:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
output: 'group'
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
# ...
|
|
|
|
```
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
version: '2'
|
|
|
|
|
|
|
|
output: prefixed
|
|
|
|
|
|
|
|
tasks:
|
|
|
|
default:
|
|
|
|
deps:
|
|
|
|
- task: print
|
|
|
|
vars: {TEXT: foo}
|
|
|
|
- task: print
|
|
|
|
vars: {TEXT: bar}
|
|
|
|
- task: print
|
|
|
|
vars: {TEXT: baz}
|
|
|
|
|
|
|
|
print:
|
|
|
|
cmds:
|
|
|
|
- echo "{{.TEXT}}"
|
|
|
|
prefix: "print-{{.TEXT}}"
|
|
|
|
silent: true
|
|
|
|
```
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ task default
|
|
|
|
[print-foo] foo
|
|
|
|
[print-bar] bar
|
|
|
|
[print-baz] baz
|
|
|
|
```
|
|
|
|
|
2019-02-09 14:01:07 +02:00
|
|
|
> The `output` option can also be specified by the `--output` or `-o` flags.
|
|
|
|
|
2018-09-22 23:44:24 +02:00
|
|
|
## Watch tasks
|
|
|
|
|
|
|
|
If you give a `--watch` or `-w` argument, task will watch for file changes
|
|
|
|
and run the task again. This requires the `sources` attribute to be given,
|
|
|
|
so task know which files to watch.
|
|
|
|
|
|
|
|
[gotemplate]: https://golang.org/pkg/text/template/
|
|
|
|
[minify]: https://github.com/tdewolff/minify/tree/master/cmd/minify
|