taskfile

name

taskfile

description

Configure and use Taskfile (task automation tool) for project build workflows. Use when users want to: (1) Create or configure a Taskfile.yml, (2) Add/modify tasks for building, testing, deploying, or other automation, (3) Set up task dependencies and variables, (4) Configure watch mode, parallel execution, or advanced features, (5) Troubleshoot Taskfile issues, (6) Organize tasks across multiple files with includes.

Taskfile Configuration and Usage

Taskfile is a cross-platform task automation tool that uses YAML to define build workflows. It provides Make-like functionality with modern features including parallel execution, dependency management, file watching, and cross-platform support.

Quick Start

Create a New Taskfile

Use the template in assets/Taskfile.template.yml as a starting point:

cp assets/Taskfile.template.yml Taskfile.yml

Customize tasks for the project type:

• Python projects: See assets/examples/python.yml
• Node.js projects: See assets/examples/nodejs.yml
• Docker projects: See assets/examples/docker.yml

Basic Structure

version: '3'

vars:
  VAR_NAME: value

tasks:
  build:
    desc: "Build the application"
    cmds:
      - echo "Building..."

Common Task Patterns

Simple Task

tasks:
  hello:
    desc: "Print hello message"
    cmds:
      - echo "Hello, World!"

Task with Dependencies

Dependencies run in parallel by default:

tasks:
  build:
    desc: "Build the application"
    deps: [lint, test]  # Run lint and test first (parallel)
    cmds:
      - go build -o app

Task with Variables

vars:
  APP_NAME: myapp

tasks:
  build:
    desc: "Build {{.APP_NAME}}"
    vars:
      VERSION:
        sh: git describe --tags
    cmds:
      - go build -o {{.APP_NAME}} -ldflags "-X main.version={{.VERSION}}"

Smart Rebuilds (Source/Generates)

Only run when sources are newer than generated files:

tasks:
  build:
    sources:
      - src/**/*.go
    generates:
      - bin/app
    cmds:
      - go build -o bin/app

Watch Mode for Development

Auto-rebuild on file changes:

tasks:
  dev:
    desc: "Development mode with auto-reload"
    watch: true
    sources:
      - 'src/**/*.go'
    cmds:
      - task: build
      - ./bin/app

Multi-Platform Builds

tasks:
  build-all:
    desc: "Build for all platforms"
    for:
      var: BUILD_TARGET
      matrix:
        GOOS: [linux, darwin, windows]
        GOARCH: [amd64, arm64]
    cmd: GOOS={{.GOOS}} GOARCH={{.GOARCH}} go build -o bin/app-{{.GOOS}}-{{.GOARCH}}

Cleanup with Defer

Guaranteed cleanup even on failure:

tasks:
  test:
    desc: "Run tests with cleanup"
    cmds:
      - docker-compose up -d
      - defer: docker-compose down
      - go test ./...

Conditional Execution

tasks:
  deploy:
    desc: "Deploy application"
    preconditions:
      - test -f bin/app
      - sh: git diff --quiet
        msg: "Git working directory must be clean"
    requires:
      vars: [DEPLOY_ENV]
    cmds:
      - ./scripts/deploy.sh {{.DEPLOY_ENV}}

CLI Usage

Running Tasks

task build              # Run build task
task build test         # Run multiple tasks
task -p build test      # Run tasks in parallel

Passing Variables

task build VERSION=1.2.3 ENV=prod

Common Flags

task --list             # List available tasks
task --list-all         # List all tasks (including internal)
task --summary build    # Show task details
task --watch dev        # Enable watch mode
task --force build      # Ignore cache/status
task --dry build        # Show commands without running
task --silent build     # Suppress output

Organizing Large Projects

Split Tasks Across Multiple Files

Main Taskfile.yml:

version: '3'

includes:
  docker:
    taskfile: ./docker/Taskfile.yml
  backend:
    taskfile: ./backend/Taskfile.yml
    dir: ./backend
  frontend:
    taskfile: ./frontend/Taskfile.yml
    dir: ./frontend

tasks:
  build:
    desc: "Build all components"
    deps:
      - docker:build
      - backend:build
      - frontend:build

Run namespaced tasks:

task backend:test       # Run test task from backend/Taskfile.yml
task frontend:build     # Run build task from frontend/Taskfile.yml

Advanced Features

For complete syntax reference and advanced features, see references/taskfile-syntax.md:

• Environment variables and .env file loading
• Status checking with checksums and timestamps
• Wildcard tasks for dynamic task names
• Internal tasks (hidden from --list)
• Platform-specific tasks (OS/architecture filtering)
• Custom output formatting
• Go template syntax for complex logic

Tips

• Use desc for user-facing tasks, omit for internal helper tasks
• Set silent: true to suppress command echo
• Use {{.USER_WORKING_DIR}} to reference the directory where task was invoked
• Add interactive: true for tasks running interactive CLIs
• Use method: checksum for better caching on large projects
• Store sensitive values in .env files and load with dotenv: [.env]