API 参考

命令行

该命令的语法如下：

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

提示

如果 -- 给出，所有剩余参数将被分配给一个特殊的 CLI_ARGS 变量

缩写	标志	类型	默认	描述
`-c`	`--color`	`bool`	`true`	彩色输出。默认开启。设置为 `false` 或使用 `NO_COLOR=1` 禁用。
`-C`	`--concurrency`	`int`	`0`	限制并发运行的任务数。零意味着无限。
`-d`	`--dir`	`string`	工作目录	设置执行目录。
`-n`	`--dry`	`bool`	`false`	按运行顺序编译和打印任务，而不执行它们。
`-x`	`--exit-code`	`bool`	`false`	传递任务命令的退出代码。
`-f`	`--force`	`bool`	`false`	即使任务是最新的也强制执行。
`-g`	`--global`	`bool`	`false`	从 `$HOME/Taskfile.{yml,yaml}` 运行全局任务文件。
`-h`	`--help`	`bool`	`false`	显示任务使用情况。
`-i`	`--init`	`bool`	`false`	在当前目录创建一个新的 Taskfile.yml。
`-I`	`--interval`	`string`	`5s`	使用 `--watch` 设置不同的观察间隔，默认为 5 秒。这个字符串应该是一个有效的 Go Duration。
`-l`	`--list`	`bool`	`false`	列出当前文件的全部任务及对应描述。
`-a`	`--list-all`	`bool`	`false`	列出无论有没有描述的所有任务。
	`--sort`	`string`	`default`	在列出时更改 task 的顺序。
	`--json`	`bool`	`false`	查看 JSON 输出
`-o`	`--output`	`string`	在 Taskfile 中设置默认值或 `intervealed`	设置输出样式：[`interleaved`/`group`/`prefixed`]。
	`--output-group-begin`	`string`		在任务组输出前打印的消息模板。
	`--output-group-end`	`string`		在任务组输出后打印的消息模板。
	`--output-group-error-only`	`bool`	`false`	在退出码为 0 时忽略命令输出。
`-p`	`--parallel`	`bool`	`false`	并行执行命令行上提供的任务。
`-s`	`--silent`	`bool`	`false`	禁用回显。
	`--status`	`bool`	`false`	如果任何给定任务不是最新的，则以非 0 退出码退出。
	`--summary`	`bool`	`false`	显示有关任务的摘要。
`-t`	`--taskfile`	`string`	`Taskfile.yml` 或 `Taskfile.yaml`
`-v`	`--verbose`	`bool`	`false`	启用详细模式。
	`--version`	`bool`	`false`	显示 Task 版本。
`-w`	`--watch`	`bool`	`false`	启用给定任务的观察器。

退出码

Task 有时会以特定的退出代码退出。这些代码分为三组，范围如下：

一般错误 (0-99)
Taskfile 错误 (100-199)
Task 错误 (200-299)

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

代码	描述
0	成功
1	出现未知错误
100	找不到 Taskfile
101	尝试初始化一个 Taskfile 时已经存在
102	Taskfile 无效或无法解析
200	找不到指定的 task
201	在 task 中执行命令时出错
202	用户试图调用内部 task
203	有多个具有相同名称或别名的 task
204	一个 task 被调用了太多次

这些代码也可以在存储库的 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 时，传递包含在 `--` 之后的所有额外参数。
`TASK`	当前任务的名称。
`ROOT_DIR`	根 Taskfile 的绝对路径。
`TASKFILE_DIR`	包含 Taskfile 的绝对路径
`USER_WORKING_DIR`	调用 `task` 的目录的绝对路径。
`CHECKSUM`	在 `sources` 中列出的文件的 checksum。仅在 `status` 参数中可用，并且如果方法设置为 `checksum`。
`TIMESTAMP`	`sources` 中列出的文件的最大时间戳的日期对象。仅在 `status` 参数中可用，并且如果方法设置为 `timestamp`。
`TASK_VERSION`	Task 的当前版本。

环境变量

可以覆盖某些环境变量以调整 Task 行为。

环境变量	默认	描述
`TASK_TEMP_DIR`	`.task`	临时目录的位置。可以相对于项目比如 `tmp/task` 或绝对如 `/tmp/.task` 或 `~/.task`。
`TASK_COLOR_RESET`	`0`	用于白色的颜色。
`TASK_COLOR_BLUE`	`34`	用于蓝色的颜色。
`TASK_COLOR_GREEN`	`32`	用于绿色的颜色。
`TASK_COLOR_CYAN`	`36`	用于青色的颜色。
`TASK_COLOR_YELLOW`	`33`	用于黄色的颜色。
`TASK_COLOR_MAGENTA`	`35`	用于洋红色的颜色。
`TASK_COLOR_RED`	`31`	用于红色的颜色。
`FORCE_COLOR`		强制使用颜色输出。

Taskfile Schema

属性	类型	默认	描述
`version`	`string`		Taskfile 的版本。当前版本是 `3`。
`output`	`string`	`interleaved`	输出模式。可用选项: `interleaved`、`group` 和 `prefixed`
`method`	`string`	`checksum`	Taskfile 中的默认方法。可以在任务基础上覆盖。可用选项：`checksum`、`timestamp` 和 `none`。
`includes`	`map[string]Include`		要包含的其他 Taskfile。
`vars`	`map[string]Variable`		一组全局变量。
`env`	`map[string]Variable`		一组全局环境变量。
`tasks`	`map[string]Task`		一组任务定义。
`silent`	`bool`	`false`	此任务文件的默认“silent”选项。如果为 `false`，则可以在任务的基础上用 `true` 覆盖。
`dotenv`	`[]string`		要解析的 `.env` 文件路径列表。
`run`	`string`	`always`	Taskfile 中默认的 'run' 选项。可用选项: `always`、`once` 和 `when_changed`。
`interval`	`string`	`5s`	设置 `--watch` 模式下的观察时间，默认 5 秒。这个字符串应该是一个有效的 Go Duration。
`set`	`[]string`		为内置 `set` 指定选项。
`shopt`	`[]string`		为内置 `shopt` 指定选项。

Include

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

信息

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

includes:
  foo: ./path

Variable

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

信息

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

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

Task

属性	类型	默认	描述
`cmds`	`[]Command`		要执行的 shell 命令列表。
`deps`	`[]Dependency`		此任务的依赖项列表。此处定义的任务将在此任务之前并行运行。
`label`	`string`		运行任务时覆盖输出中的任务名称。支持变量。
`desc`	`string`		Task 的简短描述。这在调用 `task --list` 时显示。
`summary`	`string`		任务的较长描述。这在调用 `task --summary [task]` 时显示。
`aliases`	`[]string`		可以调用任务的别名列表。
`sources`	`[]string`		运行此任务之前要检查的源列表。与 `checksum` 和 `timestamp` 相关。可以是文件路径或星号。
`generates`	`[]string`		此任务要生成的文件列表。与 `timestamp` 方法相关。可以是文件路径或星号。
`status`	`[]string`		用于检查此 task 是否应运行的命令列表。否则跳过该任务。这个方法会覆盖 `method`、`sources` 和 `generates`。
`preconditions`	`[]Precondition`		用于检查此任务是否应运行的命令列表。如果不满足条件，任务将出错。
`dir`	`string`		此 task 应运行的目录。默认为当前工作目录。
`vars`	`map[string]Variable`		可在 task 中使用的一组变量。
`env`	`map[string]Variable`		一组可用于 shell 命令的环境变量。
`dotenv`	`[]string`		要解析的 `.env` 文件路径列表。
`silent`	`bool`	`false`	从输出中隐藏任务名称和命令。命令的输出仍将重定向到 `STDOUT` 和 `STDERR`。当与 `--list` 标志结合使用时，任务描述将被隐藏。
`interactive`	`bool`	`false`	告诉任务该命令是交互式的。
`internal`	`bool`	`false`	停止在命令行上调用任务。当与 `--list` 一起使用时，它也会从输出中省略。
`method`	`string`	`checksum`	定义用于检查任务是最新的方法。 `timestamp` 将比较源的时间戳并生成文件。 `checksum` 将检查 checksum（您可能想忽略 .gitignore 文件中的 .task 文件夹）。 `none` 跳过任何验证并始终运行任务。
`prefix`	`string`		定义一个字符串作为并行运行 task 输出的前缀。仅在输出模式是 `prefixed` 时使用。
`ignore_error`	`bool`	`false`	如果执行命令时发生错误，则继续执行。
`run`	`string`	Taskfile 中全局声明的值或 `always`	指定如果多次调用该任务是否应再次运行。可用选项：`always`、`once` 和 `when_changed`。
`platforms`	`[]string`	所有平台	指定应在哪些平台上运行任务。允许使用有效的 GOOS 和 GOARCH 值。否则将跳过任务。
`set`	`[]string`		为内置 `set` 指定选项。
`shopt`	`[]string`		为内置 `shopt` 指定选项。

信息

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

tasks:
  foo: echo "foo"

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

  baz:
    cmd: echo "baz"

Command

属性	类型	默认	描述
`cmd`	`string`		要执行的 shell 命令
`silent`	`bool`	`false`	跳过此命令的一些输出。请注意，命令的 STDOUT 和 STDERR 仍将被重定向。
`task`	`string`		执行另一个 task，而不执行命令。不能与 `cmd` 同时设置。
`vars`	`map[string]Variable`		要传递给引用任务的可选附加变量。仅在设置 `task` 而不是 `cmd` 时相关。
`ignore_error`	`bool`	`false`	执行命令的时候忽略错误，继续执行
`defer`	`string`		`cmd` 的替代方法，但安排命令在此任务结束时执行，而不是立即执行。不能与 `cmd` 一同使用。
`platforms`	`[]string`	所有平台	指定应在哪些平台上运行该命令。允许使用有效的 GOOS 和 GOARCH 值。否则将跳过命令。
`set`	`[]string`		为内置 `set` 指定选项。
`shopt`	`[]string`		为内置 `shopt` 指定选项。

信息

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

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

Dependency

属性	类型	默认	描述
`task`	`string`		要作为依赖项执行的任务。
`vars`	`map[string]Variable`		要传递给此任务的可选附加变量。

提示

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

tasks:
  foo:
    deps: [foo, bar]

Precondition

属性	类型	默认	描述
`sh`	`string`		要执行的命令。如果返回非零退出码，任务将在不执行其命令的情况下出错。
`msg`	`string`		如果不满足先决条件，则打印可选消息。

提示

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

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

API 参考

命令行​

退出码​

JSON 输出​

特殊变量​

环境变量​

Taskfile Schema​

Include​

Variable​

Task​

Command​

Dependency​

Precondition​

命令行

退出码