go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2025-08-10 22:42:19 +02:00
Code Issues Releases Activity

Revert "Update docs to account for new feature"

Browse Source 
This reverts commit 66748ab5e5.
This commit is contained in:
tylermmorton
2022-02-03 22:09:57 -05:00
parent d3e2fbf1e2
commit 15e831c0b0
1 changed files with 78 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
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.
```yaml
version: "3"
version: '3'
tasks:
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:
```yaml
version: "3"
version: '3'
tasks:
greet:
@@ -54,7 +54,7 @@ Additionally, you can set globally environment variables, that'll be available
to all tasks:
```yaml
version: "3"
version: '3'
env:
GREETING: Hey, there!
@@ -86,12 +86,12 @@ ENDPOINT=testing.com
```yaml
# Taskfile.yml
version: "3"
version: '3'
env:
ENV: testing
dotenv: [".env", "{{.ENV}}/.env.", "{{.HOME}}/.env"]
dotenv: ['.env', '{{.ENV}}/.env.', '{{.HOME}}/.env']
tasks:
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:
```yaml
version: "3"
version: '3'
includes:
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:
```yaml
version: "3"
version: '3'
includes:
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:
```yaml
version: "3"
version: '3'
includes:
docs:
@@ -150,13 +150,17 @@ includes:
> 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. =)
### Optional includes
Includes marked as optional will allow Task to continue execution as normal if
the included file is missing.
```yaml
version: "3"
version: '3'
includes:
tests:
@@ -176,7 +180,7 @@ located. But you can easily make the task run in another folder informing
`dir`:
```yaml
version: "3"
version: '3'
tasks:
serve:
@@ -198,7 +202,7 @@ 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: "3"
version: '3'
tasks:
build:
@@ -217,7 +221,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:
```yaml
version: "3"
version: '3'
tasks:
assets:
@@ -242,7 +246,7 @@ 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: "3"
version: '3'
tasks:
default:
@@ -266,7 +270,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:
```yaml
version: "3"
version: '3'
tasks:
main-task:
@@ -288,7 +292,7 @@ Overriding variables in the called task is as simple as informing `vars`
attribute:
```yaml
version: "3"
version: '3'
tasks:
greet:
@@ -317,7 +321,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.
```yaml
version: "3"
version: '3'
tasks:
build:
@@ -353,7 +357,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`.
```yaml
version: "3"
version: '3'
tasks:
build:
@@ -378,7 +382,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:
```yaml
version: "3"
version: '3'
tasks:
generate-files:
@@ -423,7 +427,7 @@ conditions to be _true_ you can use the `preconditions` stanza.
expansion and they SHOULD all return 0.
```yaml
version: "3"
version: '3'
tasks:
generate-files:
@@ -451,7 +455,7 @@ executing tasks that depend on it, a `precondition` will fail a task, along
with any other tasks that depend on it.
```yaml
version: "3"
version: '3'
tasks:
task-will-fail:
@@ -477,24 +481,24 @@ overridden.
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
- `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
* `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
passed into the task
```yaml
version: "3"
version: '3'
tasks:
default:
cmds:
- task: generate-file
vars: { CONTENT: "1" }
vars: { CONTENT: '1' }
- task: generate-file
vars: { CONTENT: "2" }
vars: { CONTENT: '2' }
- task: generate-file
vars: { CONTENT: "2" }
vars: { CONTENT: '2' }
generate-file:
run: when_changed
@@ -539,7 +543,7 @@ $ task write-file FILE=file.txt "CONTENT=Hello, World!" print "MESSAGE=All done!
Example of locally declared vars:
```yaml
version: "3"
version: '3'
tasks:
print-var:
@@ -552,7 +556,7 @@ tasks:
Example of global vars in a `Taskfile.yml`:
```yaml
version: "3"
version: '3'
vars:
GREETING: Hello from Taskfile!
@@ -570,7 +574,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.
```yaml
version: "3"
version: '3'
tasks:
build:
@@ -596,7 +600,7 @@ $ task yarn -- install
```
```yaml
version: "3"
version: '3'
tasks:
yarn:
@@ -613,7 +617,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:
```yaml
version: "3"
version: '3'
tasks:
default:
@@ -627,7 +631,7 @@ If you want to move the cleanup command into another task, that's possible as
well:
```yaml
version: "3"
version: '3'
tasks:
default:
@@ -640,8 +644,8 @@ tasks:
```
> NOTE: Due to the nature of how the
> [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.
[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.
## Go's template engine
@@ -652,7 +656,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:
```yaml
version: "3"
version: '3'
tasks:
print-date:
@@ -681,7 +685,7 @@ Task also adds the following functions:
Example:
```yaml
version: "3"
version: '3'
tasks:
print-os:
@@ -709,7 +713,7 @@ Running `task --list` (or `task -l`) lists all tasks with a description.
The following Taskfile:
```yaml
version: "3"
version: '3'
tasks:
build:
@@ -746,7 +750,7 @@ Running `task --summary task-name` will show a summary of a task.
The following Taskfile:
```yaml
version: "3"
version: '3'
tasks:
release:
@@ -764,7 +768,7 @@ tasks:
- 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
@@ -780,11 +784,10 @@ dependencies:
commands:
- your-release-tool
```
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.
Please note: _showing the summary will not execute the command_.
Please note: *showing the summary will not execute the command*.
## Overriding task name
@@ -793,7 +796,7 @@ messages to STDOUT, etc. In this case you can just set `label:`, which can also
be interpolated with variables:
```yaml
version: "3"
version: '3'
tasks:
default:
@@ -805,7 +808,7 @@ tasks:
MESSAGE: world
print:
label: "print-{{.MESSAGE}}"
label: 'print-{{.MESSAGE}}'
cmds:
- echo "{{.MESSAGE}}"
```
@@ -816,7 +819,7 @@ Silent mode disables echoing of commands before Task runs it.
For the following Taskfile:
```yaml
version: "3"
version: '3'
tasks:
echo:
@@ -839,10 +842,10 @@ Print something
There are four ways to enable silent mode:
- At command level:
* At command level:
```yaml
version: "3"
version: '3'
tasks:
echo:
@@ -851,10 +854,10 @@ tasks:
silent: true
```
- At task level:
* At task level:
```yaml
version: "3"
version: '3'
tasks:
echo:
@@ -863,10 +866,10 @@ tasks:
silent: true
```
- Globally at Taskfile level:
* Globally at Taskfile level:
```yaml
version: "3"
version: '3'
silent: true
@@ -876,12 +879,12 @@ tasks:
- 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`:
```yaml
version: "3"
version: '3'
tasks:
echo:
@@ -900,7 +903,7 @@ You have the option to ignore errors during command execution.
Given the following Taskfile:
```yaml
version: "3"
version: '3'
tasks:
echo:
@@ -913,7 +916,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`:
```yaml
version: "3"
version: '3'
tasks:
echo:
@@ -944,9 +947,9 @@ options you can choose:
To choose another one, just set it to root in the Taskfile:
```yaml
version: "3"
version: '3'
output: "group"
output: 'group'
tasks:
# ...
@@ -961,7 +964,7 @@ The `prefix` output will prefix every line printed by a command with
with the `prefix:` attribute:
```yaml
version: "3"
version: '3'
output: prefixed
@@ -1002,7 +1005,7 @@ The `interactive: true` tells Task this is an interactive application, and Task
will try to optimize for it:
```yaml
version: "3"
version: '3'
tasks:
cmds:
@@ -1019,7 +1022,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):
```yaml
version: "3"
version: '3'
tasks:
build: go build -v -o ./app{{exeExt}} .