Skip to content

schema.md

Latest commit

 

History

History
940 lines (742 loc) · 16.2 KB

schema.md

File metadata and controls

940 lines (742 loc) · 16.2 KB
title Taskfile Schema Reference
description A reference for the Taskfile schema
outline deep

Taskfile Schema Reference

This page documents all available properties and types for the Taskfile schema version 3, based on the official JSON schema.

Root Schema

The root Taskfile schema defines the structure of your main Taskfile.yml.

version

  • Type: string or number
  • Required: Yes
  • Valid values: "3", 3, or any valid semver string
  • Description: Version of the Taskfile schema
version: '3'

output

  • Type: string or object
  • Default: interleaved
  • Options: interleaved, group, prefixed
  • Description: Controls how task output is displayed
# Simple string format
output: group

# Advanced object format
output:
  group:
    begin: "::group::{{.TASK}}"
    end: "::endgroup::"
    error_only: false

method

  • Type: string
  • Default: checksum
  • Options: checksum, timestamp, none
  • Description: Default method for checking if tasks are up-to-date
method: timestamp

includes

  • Type: map[string]Include
  • Description: Include other Taskfiles
includes:
  # Simple string format
  docs: ./Taskfile.yml

  # Full object format
  backend:
    taskfile: ./backend
    dir: ./backend
    optional: false
    flatten: false
    internal: false
    aliases: [api]
    excludes: [internal-task]
    vars:
      SERVICE_NAME: backend
    checksum: abc123...

vars

  • Type: map[string]Variable
  • Description: Global variables available to all tasks
vars:
  # Simple values
  APP_NAME: myapp
  VERSION: 1.0.0
  DEBUG: true
  PORT: 8080
  FEATURES: [auth, logging]

  # Dynamic variables
  COMMIT_HASH:
    sh: git rev-parse HEAD

  # Variable references
  BUILD_VERSION:
    ref: .VERSION

  # Map variables
  CONFIG:
    map:
      database: postgres
      cache: redis

env

  • Type: map[string]Variable
  • Description: Global environment variables
env:
  NODE_ENV: production
  DATABASE_URL:
    sh: echo $DATABASE_URL

tasks

  • Type: map[string]Task
  • Description: Task definitions
tasks:
  # Simple string format
  hello: echo "Hello World"

  # Array format
  build:
    - go mod tidy
    - go build ./...

  # Full object format
  deploy:
    desc: Deploy the application
    cmds:
      - ./scripts/deploy.sh

silent

  • Type: bool
  • Default: false
  • Description: Suppress task name and command output by default
silent: true

dotenv

  • Type: []string
  • Description: Load environment variables from .env files. When the same variable is defined in multiple files, the first file in the list takes precedence.
dotenv:
  - .env.local # Highest priority
  - .env # Lowest priority

run

  • Type: string
  • Default: always
  • Options: always, once, when_changed
  • Description: Default execution behavior for tasks
run: once

interval

  • Type: string
  • Default: 100ms
  • Pattern: ^[0-9]+(?:m|s|ms)$
  • Description: Watch interval for file changes
interval: 1s

set

  • Type: []string
  • Options: allexport, a, errexit, e, noexec, n, noglob, f, nounset, u, xtrace, x, pipefail
  • Description: POSIX shell options for all commands
set: [errexit, nounset, pipefail]

shopt

  • Type: []string
  • Options: expand_aliases, globstar, nullglob
  • Description: Bash shell options for all commands
shopt: [globstar]

Include

Configuration for including external Taskfiles.

taskfile

  • Type: string
  • Required: Yes
  • Description: Path to the Taskfile or directory to include
includes:
  backend: ./backend/Taskfile.yml
  # Shorthand for above
  frontend: ./frontend

dir

  • Type: string
  • Description: Working directory for included tasks
includes:
  api:
    taskfile: ./api
    dir: ./api

optional

  • Type: bool
  • Default: false
  • Description: Don't error if the included file doesn't exist
includes:
  optional-tasks:
    taskfile: ./optional.yml
    optional: true

flatten

  • Type: bool
  • Default: false
  • Description: Include tasks without namespace prefix
includes:
  common:
    taskfile: ./common.yml
    flatten: true

internal

  • Type: bool
  • Default: false
  • Description: Hide included tasks from command line and --list
includes:
  internal:
    taskfile: ./internal.yml
    internal: true

aliases

  • Type: []string
  • Description: Alternative names for the namespace
includes:
  database:
    taskfile: ./db.yml
    aliases: [db, data]

excludes

  • Type: []string
  • Description: Tasks to exclude from inclusion
includes:
  shared:
    taskfile: ./shared.yml
    excludes: [internal-setup, debug-only]

vars

  • Type: map[string]Variable
  • Description: Variables to pass to the included Taskfile
includes:
  deploy:
    taskfile: ./deploy.yml
    vars:
      ENVIRONMENT: production

checksum

  • Type: string
  • Description: Expected checksum of the included file
includes:
  remote:
    taskfile: https://example.com/tasks.yml
    checksum: c153e97e0b3a998a7ed2e61064c6ddaddd0de0c525feefd6bba8569827d8efe9

Variable

Variables support multiple types and can be static values, dynamic commands, references, or maps.

Static Variables

vars:
  # String
  APP_NAME: myapp
  # Number
  PORT: 8080
  # Boolean
  DEBUG: true
  # Array
  FEATURES: [auth, logging, metrics]
  # Null
  OPTIONAL_VAR: null

Dynamic Variables (sh)

vars:
  COMMIT_HASH:
    sh: git rev-parse HEAD
  BUILD_TIME:
    sh: date -u +"%Y-%m-%dT%H:%M:%SZ"

Variable References (ref)

vars:
  BASE_VERSION: 1.0.0
  FULL_VERSION:
    ref: .BASE_VERSION

Map Variables (map)

vars:
  CONFIG:
    map:
      database:
        host: localhost
        port: 5432
      cache:
        type: redis
        ttl: 3600

Variable Ordering

Variables can reference previously defined variables:

vars:
  GREETING: Hello
  TARGET: World
  MESSAGE: '{{.GREETING}} {{.TARGET}}!'

Task

Individual task configuration with multiple syntax options.

Simple Task Formats

tasks:
  # String command
  hello: echo "Hello World"

  # Array of commands
  build:
    - go mod tidy
    - go build ./...

  # Object with cmd shorthand
  test:
    cmd: go test ./...

Task Properties

cmds

  • Type: []Command
  • Description: Commands to execute
tasks:
  build:
    cmds:
      - go build ./...
      - echo "Build complete"

cmd

  • Type: string
  • Description: Single command (alternative to cmds)
tasks:
  test:
    cmd: go test ./...

deps

  • Type: []Dependency
  • Description: Tasks to run before this task
tasks:
  # Simple dependencies
  deploy:
    deps: [build, test]
    cmds:
      - ./deploy.sh

  # Dependencies with variables
  advanced-deploy:
    deps:
      - task: build
        vars:
          ENVIRONMENT: production
      - task: test
        vars:
          COVERAGE: true
    cmds:
      - ./deploy.sh

  # Silent dependencies
  main:
    deps:
      - task: setup
        silent: true
    cmds:
      - echo "Main task"

  # Loop dependencies
  test-all:
    deps:
      - for: [unit, integration, e2e]
        task: test
        vars:
          TEST_TYPE: '{{.ITEM}}'
    cmds:
      - echo "All tests completed"

desc

  • Type: string
  • Description: Short description shown in --list
tasks:
  test:
    desc: Run unit tests
    cmds:
      - go test ./...

summary

  • Type: string
  • Description: Detailed description shown in --summary
tasks:
  deploy:
    desc: Deploy to production
    summary: |
      Deploy the application to production environment.
      This includes building, testing, and uploading artifacts.

prompt

  • Type: string or []string
  • Description: Prompts shown before task execution
tasks:
  # Single prompt
  deploy:
    prompt: "Deploy to production?"
    cmds:
      - ./deploy.sh

  # Multiple prompts
  deploy-multi:
    prompt:
      - "Are you sure?"
      - "This will affect live users!"
    cmds:
      - ./deploy.sh

aliases

  • Type: []string
  • Description: Alternative names for the task
tasks:
  build:
    aliases: [compile, make]
    cmds:
      - go build ./...

sources

  • Type: []string or []Glob
  • Description: Source files to monitor for changes
tasks:
  build:
    sources:
      - '**/*.go'
      - go.mod
      # With exclusions
      - exclude: '**/*_test.go'
    cmds:
      - go build ./...

generates

  • Type: []string or []Glob
  • Description: Files generated by this task
tasks:
  build:
    sources: ['**/*.go']
    generates:
      - './app'
      - exclude: '*.debug'
    cmds:
      - go build -o app ./cmd

status

  • Type: []string
  • Description: Commands to check if task should run
tasks:
  install-deps:
    status:
      - test -f node_modules/.installed
    cmds:
      - npm install
      - touch node_modules/.installed

preconditions

  • Type: []Precondition
  • Description: Conditions that must be met before running
tasks:
  # Simple precondition (shorthand)
  build:
    preconditions:
      - test -d ./src
    cmds:
      - go build ./...

  # Preconditions with custom messages
  deploy:
    preconditions:
      - sh: test -n "$API_KEY"
        msg: 'API_KEY environment variable is required'
      - sh: test -f ./app
        msg: "Application binary not found. Run 'task build' first."
    cmds:
      - ./deploy.sh

if

  • Type: string
  • Description: Shell command to conditionally execute the task. If the command exits with a non-zero code, the task is skipped (not failed).
tasks:
  # Task only runs in CI environment
  deploy:
    if: '[ "$CI" = "true" ]'
    cmds:
      - ./deploy.sh

  # Using Go template expressions
  build-prod:
    if: '{{eq .ENV "production"}}'
    cmds:
      - go build -ldflags="-s -w" ./...

dir

  • Type: string
  • Description: The directory in which this task should run
  • Default: If the task is in the root Taskfile, the default dir is ROOT_DIR. For included Taskfiles, the default dir is the value specified in their respective includes.*.dir field (if any).
tasks:
  current-dir:
    dir: '{{.USER_WORKING_DIR}}'
    cmd: pwd

requires

  • Type: Requires
  • Description: Required variables with optional enum validation
tasks:
  # Simple requirements
  deploy:
    requires:
      vars: [API_KEY, ENVIRONMENT]
    cmds:
      - ./deploy.sh

  # Requirements with enum validation
  advanced-deploy:
    requires:
      vars:
        - API_KEY
        - name: ENVIRONMENT
          enum: [development, staging, production]
        - name: LOG_LEVEL
          enum: [debug, info, warn, error]
    cmds:
      - echo "Deploying to {{.ENVIRONMENT}} with log level {{.LOG_LEVEL}}"
      - ./deploy.sh

See Prompting for missing variables interactively for information on enabling interactive prompts for missing required variables.

watch

  • Type: bool
  • Default: false
  • Description: Automatically run task in watch mode
tasks:
  dev:
    watch: true
    cmds:
      - npm run dev

platforms

  • Type: []string
  • Description: Platforms where this task should run
tasks:
  windows-build:
    platforms: [windows]
    cmds:
      - go build -o app.exe ./cmd

  unix-build:
    platforms: [linux, darwin]
    cmds:
      - go build -o app ./cmd

Command

Individual command configuration within a task.

Basic Commands

tasks:
  example:
    cmds:
      - echo "Simple command"
      - ls -la

Command Object

tasks:
  example:
    cmds:
      - cmd: echo "Hello World"
        silent: true
        ignore_error: false
        platforms: [linux, darwin]
        set: [errexit]
        shopt: [globstar]
        if: '[ "$CI" = "true" ]'
        ask: "Run this command?"

Task References

tasks:
  example:
    cmds:
      - task: other-task
        vars:
          PARAM: value
        silent: false

Deferred Commands

tasks:
  with-cleanup:
    cmds:
      - echo "Starting work"
      # Deferred command string
      - defer: echo "Cleaning up"
      # Deferred task reference
      - defer:
          task: cleanup-task
          vars:
            CLEANUP_MODE: full

For Loops

Loop Over List

tasks:
  greet-all:
    cmds:
      - for: [alice, bob, charlie]
        cmd: echo "Hello {{.ITEM}}"

Loop Over Sources/Generates

tasks:
  process-files:
    sources: ['*.txt']
    cmds:
      - for: sources
        cmd: wc -l {{.ITEM}}
      - for: generates
        cmd: gzip {{.ITEM}}

Loop Over Variable

tasks:
  process-items:
    vars:
      ITEMS: 'item1,item2,item3'
    cmds:
      - for:
          var: ITEMS
          split: ','
          as: CURRENT
        cmd: echo "Processing {{.CURRENT}}"

Loop Over Matrix

tasks:
  test-matrix:
    cmds:
      - for:
          matrix:
            OS: [linux, windows, darwin]
            ARCH: [amd64, arm64]
        cmd: echo "Testing {{.ITEM.OS}}/{{.ITEM.ARCH}}"

Loop in Dependencies

tasks:
  build-all:
    deps:
      - for: [frontend, backend, worker]
        task: build
        vars:
          SERVICE: '{{.ITEM}}'

Conditional Commands

Use if to conditionally execute a command. If the shell command exits with a non-zero code, the command is skipped.

tasks:
  build:
    cmds:
      # Only run in production
      - cmd: echo "Optimizing for production"
        if: '[ "$ENV" = "production" ]'
      # Using Go templates
      - cmd: echo "Feature enabled"
        if: '{{eq .ENABLE_FEATURE "true"}}'
      # Inside for loops (evaluated per iteration)
      - for: [a, b, c]
        cmd: echo "processing {{.ITEM}}"
        if: '[ "{{.ITEM}}" != "b" ]'

Command Confirmations

Use ask to request user confirmation before executing a command. If the user declines (answers "n" or "no"), the command is skipped but the task continues.

tasks:
  deploy:
    cmds:
      - cmd: echo "Deploying to production..."
        ask: "Deploy to production?"
      - cmd: echo "Updating database..."
        ask: "Run database migrations?"
      - echo "Done!"  # No ask, always runs
Flag Behavior
(none) Asks user for y/n confirmation
--yes Auto-confirms all asks
--dry Shows commands without asking

:::note

This is different from the task-level prompt: which cancels the entire task if declined. Command-level ask: only skips the individual command.

:::

Shell Options

Set Options

Available set options for POSIX shell features:

  • allexport / a - Export all variables
  • errexit / e - Exit on error
  • noexec / n - Read commands but don't execute
  • noglob / f - Disable pathname expansion
  • nounset / u - Error on undefined variables
  • xtrace / x - Print commands before execution
  • pipefail - Pipe failures propagate
# Global level
set: [errexit, nounset, pipefail]

tasks:
  debug:
    # Task level
    set: [xtrace]
    cmds:
      - cmd: echo "This will be traced"
        # Command level
        set: [noexec]

Shopt Options

Available shopt options for Bash features:

  • expand_aliases - Enable alias expansion
  • globstar - Enable ** recursive globbing
  • nullglob - Null glob expansion
# Global level
shopt: [globstar]

tasks:
  find-files:
    # Task level
    shopt: [nullglob]
    cmds:
      - cmd: ls **/*.go
        # Command level
        shopt: [globstar]