taskfiles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Taskfiles

Repository Structure

仓库结构

Taskfile.yaml                    # Root: includes namespaced taskfiles
.taskfiles/
├── inventory/taskfile.yaml      # inv: IPMI host management
├── terragrunt/taskfile.yaml     # tg: Infrastructure operations
├── worktree/taskfile.yaml       # wt: Git worktree management
└── renovate/taskfile.yaml       # renovate: Config validation

Taskfile.yaml                    # 根目录：引用带命名空间的taskfile
.taskfiles/
├── inventory/taskfile.yaml      # inv: IPMI主机管理
├── terragrunt/taskfile.yaml     # tg: 基础设施操作
├── worktree/taskfile.yaml       # wt: Git工作区管理
└── renovate/taskfile.yaml       # renovate: 配置验证

File Template

文件模板

Always include schema and version:

yaml

---

始终包含schema和版本：

yaml

---

yaml-language-server: $schema=https://taskfile.dev/schema.json

version: "3"

vars: MY_DIR: "{{.ROOT_DIR}}/path"

tasks: my-task: desc: Short description for --list output. cmds: - echo "hello"

undefined

version: "3"

vars: MY_DIR: "{{.ROOT_DIR}}/path"

tasks: my-task: desc: 用于--list输出的简短描述。 cmds: - echo "hello"

undefined

Required Patterns

必需模式

Include New Taskfiles

引用新的Taskfile

Add to root

Taskfile.yaml

yaml

includes:
  namespace: .taskfiles/namespace

添加到根目录

Taskfile.yaml

：

yaml

includes:
  namespace: .taskfiles/namespace

Wildcard Tasks

通配符任务

Use for parameterized operations:

yaml

plan-*:
  desc: Plans a specific terragrunt stack.
  vars:
    STACK: "{{index .MATCH 0}}"
  label: plan-{{.STACK}}          # Dynamic label for output
  cmds:
    - terragrunt plan --working-dir {{.INFRASTRUCTURE_DIR}}/stacks/{{.STACK}}
  preconditions:
    - which terragrunt
    - test -d "{{.INFRASTRUCTURE_DIR}}/stacks/{{.STACK}}"

用于参数化操作：

yaml

plan-*:
  desc: 规划特定的terragrunt栈。
  vars:
    STACK: "{{index .MATCH 0}}"
  label: plan-{{.STACK}}          # 用于输出的动态标签
  cmds:
    - terragrunt plan --working-dir {{.INFRASTRUCTURE_DIR}}/stacks/{{.STACK}}
  preconditions:
    - which terragrunt
    - test -d "{{.INFRASTRUCTURE_DIR}}/stacks/{{.STACK}}"

Dependencies and Formatting

依赖关系与格式

Run dependencies before main task:

yaml

apply-*:
  deps: [use, fmt]                # Run in parallel before cmds
  cmds:
    - terragrunt apply ...

在主任务前运行依赖项：

yaml

apply-*:
  deps: [use, fmt]                # 在执行cmds前并行运行
  cmds:
    - terragrunt apply ...

Internal Helper Tasks

内部辅助任务

Hide implementation details:

yaml

ipmi-command:
  internal: true                  # Hidden from --list
  silent: true                    # Suppress command output
  requires:
    vars: [HOST, COMMAND]         # Validate required vars
  cmds:
    - ipmitool ... {{.COMMAND}}

隐藏实现细节：

yaml

ipmi-command:
  internal: true                  # 在--list中隐藏
  silent: true                    # 抑制命令输出
  requires:
    vars: [HOST, COMMAND]         # 验证必需的变量
  cmds:
    - ipmitool ... {{.COMMAND}}

Preconditions

前置条件

Validate before execution:

yaml

preconditions:
  - which required-tool           # Tool must exist
  - test -d "{{.PATH}}"           # Directory must exist
  - sh: test "{{.VALUE}}" != ""
    msg: "VALUE cannot be empty"  # Custom error message

执行前验证：

yaml

preconditions:
  - which required-tool           # 工具必须存在
  - test -d "{{.PATH}}"           # 目录必须存在
  - sh: test "{{.VALUE}}" != ""
    msg: "VALUE不能为空"  # 自定义错误消息

Source Tracking

源文件跟踪

Skip unchanged tasks:

yaml

fmt:
  sources:
    - "{{.DIR}}/**/*.tf"
  generates:
    - "{{.DIR}}/**/*.tf"          # Same files = format in place
  cmds:
    - tofu fmt -recursive

跳过未更改的任务：

yaml

fmt:
  sources:
    - "{{.DIR}}/**/*.tf"
  generates:
    - "{{.DIR}}/**/*.tf"          # 相同文件 = 原地格式化
  cmds:
    - tofu fmt -recursive

Dynamic Variables from Files

从文件加载动态变量

Load from external sources:

yaml

vars:
  VALID_HOSTS:
    sh: "cat {{.INVENTORY_FILE}} | yq -r '.hosts | keys[]'"

从外部源加载：

yaml

vars:
  VALID_HOSTS:
    sh: "cat {{.INVENTORY_FILE}} | yq -r '.hosts | keys[]'"

For Loops

循环

Iterate over lists:

yaml

power-status:
  cmds:
    - for: { var: VALID_HOSTS }
      cmd: task inv:status-{{.ITEM}}

遍历列表：

yaml

power-status:
  cmds:
    - for: { var: VALID_HOSTS }
      cmd: task inv:status-{{.ITEM}}

CLI Arguments

CLI参数

Accept user input:

yaml

new:
  requires:
    vars: [CLI_ARGS]              # Must provide argument
  vars:
    NAME: "{{.CLI_ARGS}}"
  cmds:
    - git worktree add ... -b "{{.NAME}}"

Usage:

task wt:new -- feature-branch

接受用户输入：

yaml

new:
  requires:
    vars: [CLI_ARGS]              # 必须提供参数
  vars:
    NAME: "{{.CLI_ARGS}}"
  cmds:
    - git worktree add ... -b "{{.NAME}}"

用法：

task wt:new -- feature-branch

Style Rules

样式规则

Element	Convention	Example
Variables	UPPERCASE	`STACK` , `ROOT_DIR`
Task names	kebab-case	`power-on-*` , `tofu-fmt`
Templates	No spaces	`{{.VAR}}` not `{{ .VAR }}`
Indentation	2 spaces	Standard YAML

元素	约定	示例
变量	大写	`STACK` , `ROOT_DIR`
任务名称	kebab-case	`power-on-*` , `tofu-fmt`
模板	无空格	`{{.VAR}}` 而非 `{{ .VAR }}`
缩进	2个空格	标准YAML格式

Common Operations

常见操作

bash

task --list              # Show available tasks
task tg:list             # List terragrunt stacks
task tg:plan-live        # Plan specific stack
task inv:power-on-node41 # IPMI power control
task wt:new -- branch    # Create worktree

bash

task --list              # 显示可用任务
task tg:list             # 列出terragrunt栈
task tg:plan-live        # 规划特定栈
task inv:power-on-node41 # IPMI电源控制
task wt:new -- branch    # 创建工作区

References

参考资料

references/styleguide.md - Naming and formatting conventions
references/schema.md - Complete property reference
references/cli.md - CLI flags and options

references/styleguide.md - 命名与格式约定
references/schema.md - 完整属性参考
references/cli.md - CLI标志与选项