跳到主要内容

API 参考

命令行

该命令的语法如下:

task [--flags] [tasks...] [-- CLI_ARGS...]
提示

If -- is given, all remaining arguments will be assigned to a special CLI_ARGS variable

缩写标志类型默认描述
-c--colorbooltrue彩色输出。 默认开启。 设置为 false 或使用 NO_COLOR=1 禁用。
-C--concurrencyint0限制并发运行的 task 数。 零意味着无限。
-d--dirstring工作目录设置执行目录。
-n--dryboolfalse按运行顺序编译和打印 task,而不执行它们。
-x--exit-codeboolfalse传递 task 命令的退出代码。
-f--forceboolfalse即使 task 是最新的也强制执行。
-g--globalboolfalse$HOME/Taskfile.{yml,yaml} 运行全局 Taskfile。
-h--helpboolfalse显示 Task 使用情况。
-i--initboolfalse在当前目录创建一个新的 Taskfile.yml。
-I--intervalstring5s使用 --watch 设置不同的观察间隔,默认为 5 秒。 这个字符串应该是一个有效的 Go Duration
-l--listboolfalse列出当前文件的全部 task 及对应描述。
-a--list-allboolfalse列出无论有没有描述的所有 task。
--sortstringdefaultChanges the order of the tasks when listed.
default - Alphanumeric with root tasks first
alphanumeric - Alphanumeric
none - No sorting (As they appear in the Taskfile)
--jsonboolfalse查看 JSON 输出
-o--outputstring在 Taskfile 中设置默认值或 intervealed设置输出样式:[interleaved/group/prefixed]。
--output-group-beginstring在任务组输出前打印的消息模板。
--output-group-endstring在任务组输出后打印的消息模板。
--output-group-error-onlyboolfalse在退出码为 0 时忽略命令输出。
-p--parallelboolfalse并行执行命令行上提供的 task。
-s--silentboolfalse禁用回显。
-y--yesboolfalseAssume "yes" as answer to all prompts.
--statusboolfalse如果任何给定 task 不是最新的,则以非 0 退出码退出。
--summaryboolfalse显示有关 task 的摘要。
-t--taskfilestringTaskfile.ymlTaskfile.yaml
-v--verboseboolfalse启用详细模式。
--versionboolfalse显示 Task 版本。
-w--watchboolfalse启用给定 task 的观察器。

退出码

Task 有时会以特定的退出代码退出。 These codes are split into three groups with the following ranges:

  • General errors (0-99)
  • Taskfile errors (100-199)
  • Task errors (200-299)

可以在下面找到退出代码及其描述的完整列表:

代码描述
0成功
1出现未知错误
100找不到 Taskfile
101尝试初始化一个 Taskfile 时已经存在
102Taskfile 无效或无法解析
103A remote Taskfile could not be downloaded
104A remote Taskfile was not trusted by the user
105A remote Taskfile was could not be fetched securely
106No cache was found for a remote Taskfile in offline mode
107No schema version was defined in the Taskfile
200找不到指定的 task
201在 task 中执行命令时出错
202用户试图调用内部 task
203有多个具有相同名称或别名的 task
204一个 task 被调用了太多次
205操作被用户取消
206由于缺少所需变量,任务未执行

这些代码也可以在代码库的 errors/errors.go 文件中找到。

信息

当使用 -x/--exit-code 标志运行 Task 时,任何失败命令的退出代码都将传递给用户。

JSON 输出

--json 标志与 --list--list-all 标志结合使用时,将输出具有以下结构的 JSON 对象:

{
"tasks": [
{
"name": "",
"desc": "",
"summary": "",
"up_to_date": false,
"location": {
"line": 54,
"column": 3,
"taskfile": "/path/to/Taskfile.yml"
}
}
// ...
],
"location": "/path/to/Taskfile.yml"
}

特殊变量

模板系统上有一些可用的特殊变量:

变量描述
CLI_ARGS当通过 CLI 调用 Task 时,传递包含在 -- 之后的所有额外参数。
CLI_FORCEA boolean containing whether the --force or --force-all flags were set.
TASK当前 task 的名称。
ROOT_DIR根 Taskfile 的绝对路径。
TASKFILE_DIR包含 Taskfile 的绝对路径
USER_WORKING_DIR调用 task 的目录的绝对路径。
CHECKSUMsources 中列出的文件的 checksum。 仅在 status 参数中可用,并且如果 method 设置为 checksum
TIMESTAMPThe date object of the greatest timestamp of the files listed in sources. 仅在 status 参数中可用,并且如果 method 设置为 timestamp
TASK_VERSIONTask 的当前版本。
ITEMThe value of the current iteration when using the for property. Can be changed to a different variable name using as:.

环境变量

Some environment variables can be overridden to adjust Task behavior.

ENV默认描述
TASK_TEMP_DIR.task临时目录的位置。 可以相对于项目比如 tmp/task 或绝对如 /tmp/.task~/.task
TASK_COLOR_RESET0用于白色的颜色。
TASK_COLOR_BLUE34用于蓝色的颜色。
TASK_COLOR_GREEN32用于绿色的颜色。
TASK_COLOR_CYAN36用于青色的颜色。
TASK_COLOR_YELLOW33用于黄色的颜色。
TASK_COLOR_MAGENTA35用于洋红色的颜色。
TASK_COLOR_RED31用于红色的颜色。
FORCE_COLOR强制使用颜色输出。

Taskfile Schema

属性类型默认描述
versionstringTaskfile 的版本。 当前版本是 3
outputstringinterleaved输出模式。 可用选项: interleavedgroupprefixed
methodstringchecksumTaskfile 中的默认方法。 Can be overridden in a task by task basis. 可用选项:checksumtimestampnone
includesmap[string]Include要包含的其他 Taskfile。
varsmap[string]Variable一组全局变量。
envmap[string]Variable一组全局环境变量。
tasksmap[string]Task一组 task 定义。
silentboolfalse此 Taskfile 的默认“silent”选项。 If false, can be overridden with true in a task by task basis.
dotenv[]string要解析的 .env 文件路径列表。
runstringalwaysTaskfile 中默认的 'run' 选项。 可用选项: alwaysoncewhen_changed
intervalstring5s设置 --watch 模式下的观察时间,默认 5 秒。 这个字符串应该是一个有效的 Go Duration
set[]string内置 set 指定选项。
shopt[]string内置 shopt 指定选项。

Include

属性类型默认描述
taskfilestring要包含的 Taskfile 或目录的路径。 如果是目录,Task 将在该目录中查找名为 Taskfile.ymlTaskfile.yaml 的文件。 如果是相对路径,则相对于包含 Taskfile 的目录进行解析。
dirstringTaskfile 文件父目录运行时包含的 task 的工作目录。
optionalboolfalse设置为 true 时, 文件不存在也不会报错
internalboolfalse停止在命令行上调用包含的 Taskfile 中的任何 task。 当与 --list 一起使用时,这些命令也将从输出中省略。
aliases[]string包含的 Taskfile 的命名空间的替代名称。
varsmap[string]Variable一组应用于包含的 Taskfile 的变量。
信息

像下面这样只赋值一个字符串,和把这个值设置到 taskfile 属性是一样的。

includes:
foo: ./path

Variable

属性类型默认描述
itselfstring将设置为变量的静态值。
shstring一个 shell 命令。 输出 (STDOUT) 将分配给变量。
信息

静态和动态变量有不同的语法,如下所示:

vars:
STATIC: static
DYNAMIC:
sh: echo "dynamic"

Task

属性类型默认描述
cmds[]Command要执行的 shell 命令列表。
deps[]Dependency此 task 的依赖项列表。 此处定义的 task 将在此 task 之前并行运行。
labelstring运行 task 时覆盖输出中的 task 名称。 支持变量。
descstringtask 的简短描述。 这在调用 task --list 时显示。
promptstringA prompt that will be presented before a task is run. Declining will cancel running the current and any subsequent tasks.
summarystringtask 的较长描述。 这在调用 task --summary [task] 时显示。
aliases[]string可以调用 task 的别名列表。
sources[]string运行此 task 之前要检查的源列表。 与 checksumtimestamp 方法相关。 可以是文件路径或星号。
generates[]string此 task 要生成的文件列表。 与 timestamp 方法相关。 可以是文件路径或星号。
status[]string用于检查此 task 是否应运行的命令列表。 否则跳过该 task。 这个方法会覆盖 methodsourcesgenerates
requires[]stringA list of variables which should be set if this task is to run, if any of these variables are unset the task will error and not run.
preconditions[]Precondition用于检查此 task 是否应运行的命令列表。 如果不满足条件,task 将出错。
requiresRequiresA list of required variables which should be set if this task is to run, if any variables listed are unset the task will error and not run.
dirstring此 task 应运行的目录。 默认为当前工作目录。
varsmap[string]Variable可在 task 中使用的一组变量。
envmap[string]Variable一组可用于 shell 命令的环境变量。
dotenv[]string要解析的 .env 文件路径列表。
silentboolfalse从输出中隐藏 task 名称和命令。 命令的输出仍将重定向到 STDOUTSTDERR。 当与 --list 标志结合使用时,task 描述将被隐藏。
interactiveboolfalse告诉 task 该命令是交互式的。
internalboolfalse停止在命令行上调用 task。 当与 --list 一起使用时,它也会从输出中省略。
methodstringchecksum定义用于检查 task 是最新的方法。 timestamp 将比较 sources 的时间戳并生成文件。 checksum 将检查 checksum(您可能想忽略 .gitignore 文件中的 .task 文件夹)。 none 跳过任何验证并始终运行 task。
prefixstring定义一个字符串作为并行运行 task 输出的前缀。 仅在输出模式是 prefixed 时使用。
ignore_errorboolfalse如果执行命令时发生错误,则继续执行。
runstringTaskfile 中全局声明的值或 always指定如果多次调用该 task 是否应再次运行。 可用选项:alwaysoncewhen_changed
platforms[]string所有平台指定应在哪些平台上运行 task。 允许使用 有效的 GOOS 和 GOARCH 值。 否则将跳过 task。
set[]string内置 set 指定选项。
shopt[]string内置 shopt 指定选项。
信息

这些替代语法可用。 他们会将给定值设置为 cmds,其他所有内容都将设置为其默认值:

tasks:
foo: echo "foo"

foobar:
- echo "foo"
- echo "bar"

baz:
cmd: echo "baz"

Command

属性类型默认描述
cmdstring要执行的 shell 命令
taskstring执行另一个 task,而不执行命令。 不能与 cmd 同时设置。
forForRuns the command once for each given value.
silentboolfalse跳过此命令的一些输出。 请注意,命令的 STDOUT 和 STDERR 仍将被重定向。
varsmap[string]Variable要传递给引用 task 的可选附加变量。 仅在设置 task 而不是 cmd 时相关。
ignore_errorboolfalse执行命令的时候忽略错误,继续执行
deferstringcmd 的替代方法,但安排命令在此 task 结束时执行,而不是立即执行。 不能与 cmd 一同使用。
platforms[]string所有平台指定应在哪些平台上运行该命令。 允许使用 有效的 GOOS 和 GOARCH 值。 否则将跳过命令。
set[]string内置 set 指定选项。
shopt[]string内置 shopt 指定选项。
信息

如果以字符串形式给出,该值将分配给 cmd

tasks:
foo:
cmds:
- echo "foo"
- echo "bar"

Dependency

属性类型默认描述
taskstring要作为依赖项执行的 task。
varsmap[string]Variable要传递给此 task 的可选附加变量。
silentboolfalse从输出中隐藏 task 名称和命令。 命令的输出仍将重定向到 STDOUTSTDERR
提示

如果你不想设置额外的变量,将依赖关系声明为一个字符串列表就足够了(它们将被分配给 task)。

tasks:
foo:
deps: [foo, bar]

For

The for parameter can be defined as a string, a list of strings or a map. If it is defined as a string, you can give it any of the following values:

  • source - Will run the command for each source file defined on the task. (Glob patterns will be resolved, so *.go will run for every Go file that matches).

If it is defined as a list of strings, the command will be run for each value.

Finally, the for parameter can be defined as a map when you want to use a variable to define the values to loop over:

属性类型默认描述
varstringThe name of the variable to use as an input.
splitstring(any whitespace)What string the variable should be split on.
asstringITEMThe name of the iterator variable.

Precondition

AttributeTypeDefaultDescription
shstring要执行的命令。 如果返回非零退出码, task 将在不执行其命令的情况下出错。
msgstring如果不满足先决条件,则打印可选消息。
提示

如果你不想设置不同的消息,你可以像这样声明一个前提条件,值将被分配给 sh

tasks:
foo:
precondition: test -f Taskfile.yml

Requires

AttributeTypeDefaultDescription
vars[]stringList of variable or environment variable names that must be set if this task is to execute and run