go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2025-07-15 01:35:00 +02:00
Code Issues Releases Activity

Merge pull request #759 from Cornul11/patch-1

Browse Source 
fixed grammatical errors
This commit is contained in:
Andrey Nering
2022-06-10 10:11:34 -03:00
committed by GitHub
parent b222c34f12 8a74141e4b
commit 374ec27ab5
1 changed files with 47 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
docs/docs/usage.md
View File

@ -32,7 +32,7 @@ task assets build
``` ```
Task uses [mvdan.cc/sh](https://mvdan.cc/sh/), a native Go sh Task uses [mvdan.cc/sh](https://mvdan.cc/sh/), a native Go sh
interpreter. So you can write sh/bash commands and it will work even on 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 Windows, where `sh` or `bash` are usually not available. Just remember any
executable called must be available by the OS or in PATH. executable called must be available by the OS or in PATH.
@ -69,7 +69,7 @@ tasks:
GREETING: Hey, there! GREETING: Hey, there!
``` ```
Additionally, you can set globally environment variables, that'll be available Additionally, you can set global environment variables that will be available
to all tasks: to all tasks:
```yaml ```yaml
@ -87,7 +87,7 @@ tasks:
:::info :::info
`env` supports expansion and retrieving output from a shell command `env` supports expansion and retrieving output from a shell command
just like variables, as you can see on the [Variables](#variables) section. just like variables, as you can see in the [Variables](#variables) section.
::: :::
@ -153,7 +153,7 @@ includes:
### Directory of included Taskfile ### Directory of included Taskfile
By default, included Taskfile's tasks are ran in the current directory, even By default, included Taskfile's tasks are run in the current directory, even
if the Taskfile is in another directory, but you can force its tasks to run 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:
@ -168,7 +168,7 @@ includes:
:::info :::info
The included Taskfiles must be using the same schema version the main The included Taskfiles must be using the same schema version as the main
Taskfile uses. Taskfile uses.
::: :::
@ -215,7 +215,7 @@ includes:
:::info :::info
Vars declared in the included Taskfile have preference over the Vars declared in the included Taskfile have preference over the
included ones! If you want a variable in an included Taskfile to be overridable included ones! If you want a variable in an included Taskfile to be overridable,
use the [default function](https://go-task.github.io/slim-sprig/defaults.html): use the [default function](https://go-task.github.io/slim-sprig/defaults.html):
`MY_VAR: '{{.MY_VAR | default "my-default-value"}}'`. `MY_VAR: '{{.MY_VAR | default "my-default-value"}}'`.
@ -224,7 +224,7 @@ use the [default function](https://go-task.github.io/slim-sprig/defaults.html):
## Task directory ## Task directory
By default, tasks will be executed in the directory where the Taskfile is 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 located. But you can easily make the task run in another folder, informing
`dir`: `dir`:
```yaml ```yaml
@ -238,12 +238,12 @@ tasks:
- caddy - caddy
``` ```
If the directory doesn't exist, `task` creates it. If the directory does not exist, `task` creates it.
## Task dependencies ## Task dependencies
> Dependencies run in parallel, so dependencies of a task shouldn't depend one > Dependencies run in parallel, so dependencies of a task should not depend one
> another. If you want to force tasks to run serially take a look at the > another. If you want to force tasks to run serially, take a look at the
> [Calling Another Task](#calling-another-task) section below. > [Calling Another Task](#calling-another-task) section below.
You may have tasks that depend on others. Just pointing them on `deps` will You may have tasks that depend on others. Just pointing them on `deps` will
@ -318,8 +318,8 @@ tasks:
## Calling another task ## Calling another task
When a task has many dependencies, they are executed concurrently. This will 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 often result in a faster build pipeline. However, 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, use the following syntax:
```yaml ```yaml
version: '3' version: '3'
@ -374,7 +374,7 @@ NOTE: If you want to call a task declared in the root Taskfile from within an
### By fingerprinting locally generated files and their sources ### By fingerprinting locally generated files and their sources
If a task generates something, you can inform Task the source and generated 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 running them if not necessary.
```yaml ```yaml
version: '3' version: '3'
@ -407,7 +407,7 @@ Task will compare the checksum of the source files to determine if it's
necessary to run the task. If not, it will just print a message like necessary to run the task. If not, it will just print a message like
`Task "js" is up to date`. `Task "js" is up to date`.
You will probably want to ignore the `.task` folder in your `.gitignore` file You will probably want to ignore the `.task` folder in your `.gitignore` file
(It's there that Task stores the last checksum). (It is there that Task stores the last checksum).
If you prefer this check to be made by the modification timestamp of the files, 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`.
@ -430,13 +430,13 @@ tasks:
Each task has only one checksum stored for its `sources`. If you want Each task has only one checksum stored for its `sources`. If you want
to distinguish a task by any of its input variables, you can add those to distinguish a task by any of its input variables, you can add those
variables as part of the task's label and it will be considered a different variables as part of the task's label, and it will be considered a different
task. task.
This is useful if you want to run a task once for each distinct set of This is useful if you want to run a task once for each distinct set of
inputs until the sources actually change. For example if the sources depend inputs until the sources actually change. For example, if the sources depend
on the value of a variable, or you want the task to rerun if some arguments on the value of a variable, or you if you want the task to rerun if some arguments
change even if the source hasn't. change even if the source has not.
::: :::
@ -448,7 +448,7 @@ The method `none` skips any validation and always run the task.
:::info :::info
For the `checksum` (default) method to work, it's only necessary to For the `checksum` (default) method to work, it is only necessary to
inform the source files, but if you want to use the `timestamp` method, you inform the source files, but if you want to use the `timestamp` method, you
also need to inform the generated files with `generates`. also need to inform the generated files with `generates`.
@ -496,13 +496,13 @@ up-to-date.
Also, `task --status [tasks]...` will exit with a non-zero exit code if any of Also, `task --status [tasks]...` will exit with a non-zero exit code if any of
the tasks are not up-to-date. 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 the execution of a task and its dependencies
In addition to `status` checks, there are also `preconditions` checks, which are In addition to `status` checks, `preconditions` checks 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'
@ -528,7 +528,7 @@ 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.
Unlike `status` which will skip a task if it is up to date, and continue Unlike `status`, which will skip a task if it is up to date and continue
executing tasks that depend on it, a `precondition` will fail a task, along 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.
@ -616,8 +616,8 @@ A special variable `.TASK` is always available containing the task name.
::: :::
Since some shells don't support above syntax to set environment variables Since some shells do not support the above syntax to set environment variables
(Windows) tasks also accepts a similar style when not in the beginning of (Windows) tasks also accept a similar style when not at the beginning of
the command. the command.
```bash ```bash
@ -654,7 +654,7 @@ tasks:
### Dynamic variables ### Dynamic variables
The below syntax (`sh:` prop in a variable) is considered a dynamic variable. 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 The value will be treated as a command and the output assigned. If there are one
or more trailing newlines, the last newline will be trimmed. or more trailing newlines, the last newline will be trimmed.
```yaml ```yaml
@ -698,7 +698,7 @@ With the `defer` keyword, it's possible to schedule cleanup to be run once
the task finishes. The difference with just putting it as the last command is the task finishes. The difference with just putting it as the last command is
that this command will run even when the task fails. 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'
@ -711,7 +711,7 @@ tasks:
- echo 'Do work on tmpdir/' - echo 'Do work on tmpdir/'
``` ```
If you want to move the cleanup command into another task, that's possible as If you want to move the cleanup command into another task, that is possible as
well: well:
```yaml ```yaml
@ -754,7 +754,7 @@ tasks:
Task also adds the following functions: Task also adds the following functions:
- `OS`: Returns operating system. Possible values are "windows", "linux", - `OS`: Returns the operating system. Possible values are "windows", "linux",
"darwin" (macOS) and "freebsd". "darwin" (macOS) and "freebsd".
- `ARCH`: return the architecture Task was compiled to: "386", "amd64", "arm" - `ARCH`: return the architecture Task was compiled to: "386", "amd64", "arm"
or "s390x". or "s390x".
@ -879,8 +879,8 @@ Please note: *showing the summary will not execute the command*.
## Overriding task name ## Overriding task name
Sometimes you may want to override the task name print on summary, up-to-date Sometimes you may want to override the task name printed on the summary, up-to-date
messages to STDOUT, etc. In this case you can just set `label:`, which can also 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
@ -903,7 +903,7 @@ tasks:
## Silent mode ## Silent mode
Silent mode disables echoing of commands before Task runs it. Silent mode disables the echoing of commands before Task runs it.
For the following Taskfile: For the following Taskfile:
```yaml ```yaml
@ -915,14 +915,14 @@ tasks:
- echo "Print something" - echo "Print something"
``` ```
Normally this will be print: Normally this will be printed:
```sh ```sh
echo "Print something" echo "Print something"
Print something Print something
``` ```
With silent mode on, the below will be print instead: With silent mode on, the below will be printed instead:
```sh ```sh
Print something Print something
@ -1001,7 +1001,7 @@ tasks:
``` ```
Task will abort the execution after running `exit 1` because the status code `1` stands for `EXIT_FAILURE`. 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`: However, it is possible to continue with execution using `ignore_error`:
```yaml ```yaml
version: '3' version: '3'
@ -1014,16 +1014,16 @@ tasks:
- echo "Hello World" - echo "Hello World"
``` ```
`ignore_error` can also be set for a task, which mean errors will be suppressed `ignore_error` can also be set for a task, which means errors will be suppressed
for all commands. But keep in mind this option won't propagate to other tasks for all commands. Nevertheless, keep in mind that this option will not propagate to other tasks
called either by `deps` or `cmds`! called either by `deps` or `cmds`!
## Output syntax ## Output syntax
By default, Task just redirect the STDOUT and STDERR of the running commands By default, Task just redirects the STDOUT and STDERR of the running commands
to the shell in real time. This is good for having live feedback for log to the shell in real-time. This is good for having live feedback for logging
printed by commands, but the output can become messy if you have multiple printed by commands, but the output can become messy if you have multiple
commands running at the same time and printing lots of stuff. commands running simultaneously and printing lots of stuff.
To make this more customizable, there are currently three different output To make this more customizable, there are currently three different output
options you can choose: options you can choose:
@ -1043,8 +1043,8 @@ 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 will not have live feedback for commands that take a long time
to run. to run.
When using the `group` output, you can optionally provide a templated message When using the `group` output, you can optionally provide a templated message
@ -1117,11 +1117,11 @@ The `output` option can also be specified by the `--output` or `-o` flags.
## Interactive CLI application ## Interactive CLI application
When running interactive CLI applications inside Task they can sometimes behave When running interactive CLI applications inside Task they can sometimes behave
weirdly, specially when the [output mode](#output-syntax) is set to something weirdly, especially when the [output mode](#output-syntax) is set to something
other than `interleaved` (the default), or when interactive apps are ran in other than `interleaved` (the default), or when interactive apps are run in
parallel with other tasks. parallel with other tasks.
The `interactive: true` tells Task this is an interactive application, and Task 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
@ -1134,7 +1134,7 @@ tasks:
interactive: true interactive: true
``` ```
If you still have problem running an interactive app through Task, please open If you still have problems running an interactive app through Task, please open
an issue about it. an issue about it.
## Short task syntax ## Short task syntax