rayan/go-task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2026-06-29 15:44:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: migrate website to vitepress (#2359)

Browse Source 
Co-authored-by: Pete Davison <pd93.uk@outlook.com>
Co-authored-by: Andrey Nering <andreynering@users.noreply.github.com>
This commit is contained in:
Valentin Maerten
2025-08-12 18:09:19 +02:00
committed by GitHub
parent 64fc538a16
commit 79c93fb42b
137 changed files with 13639 additions and 19421 deletions
Download Patch File Download Diff File Expand all files Collapse all files

343
website/src/docs/reference/cli.md Normal file
View File

@@ -0,0 +1,343 @@
---
title: CLI Reference
description: Complete reference for Task CLI commands, flags, and exit codes
permalink: /reference/cli/
outline: deep
---
# Command Line Interface
Task CLI commands have the following syntax:
```bash
task [options] [tasks...] [-- CLI_ARGS...]
```
::: tip
If `--` is given, all remaining arguments will be assigned to a special
`CLI_ARGS` variable
:::
## Commands
### `task [tasks...]`
Run one or more tasks defined in your Taskfile.
```bash
task build
task test lint
task deploy --force
```
### `task --list`
List all available tasks with their descriptions.
```bash
task --list
task -l
```
### `task --list-all`
List all tasks, including those without descriptions.
```bash
task --list-all
task -a
```
### `task --init`
Create a new Taskfile.yml in the current directory.
```bash
task --init
task -i
```
## Options
### General
#### `-h, --help`
Show help information.
```bash
task --help
```
#### `--version`
Show Task version.
```bash
task --version
```
#### `-v, --verbose`
Enable verbose mode for detailed output.
```bash
task build --verbose
```
#### `-s, --silent`
Disable command echoing.
```bash
task deploy --silent
```
### Execution Control
#### `-f, --force`
Force execution even when the task is up-to-date.
```bash
task build --force
```
#### `-n, --dry`
Compile and print tasks without executing them.
```bash
task deploy --dry
```
#### `-p, --parallel`
Execute multiple tasks in parallel.
```bash
task test lint --parallel
```
#### `-C, --concurrency <number>`
Limit the number of concurrent tasks. Zero means unlimited.
```bash
task test --concurrency 4
```
#### `-x, --exit-code`
Pass through the exit code of failed commands.
```bash
task test --exit-code
```
### File and Directory
#### `-d, --dir <path>`
Set the directory where Task will run and look for Taskfiles.
```bash
task build --dir ./backend
```
#### `-t, --taskfile <file>`
Specify a custom Taskfile path.
```bash
task build --taskfile ./custom/Taskfile.yml
```
#### `-g, --global`
Run the global Taskfile from `$HOME/Taskfile.{yml,yaml}`.
```bash
task backup --global
```
### Output Control
#### `-o, --output <mode>`
Set output style. Available modes: `interleaved`, `group`, `prefixed`.
```bash
task test --output group
```
#### `--output-group-begin <template>`
Message template to print before grouped output.
```bash
task test --output group --output-group-begin "::group::{{.TASK}}"
```
#### `--output-group-end <template>`
Message template to print after grouped output.
```bash
task test --output group --output-group-end "::endgroup::"
```
#### `--output-group-error-only`
Only show command output on non-zero exit codes.
```bash
task test --output group --output-group-error-only
```
#### `-c, --color`
Control colored output. Enabled by default.
```bash
task build --color=false
# or use environment variable
NO_COLOR=1 task build
```
### Task Information
#### `--status`
Check if tasks are up-to-date without running them.
```bash
task build --status
```
#### `--summary`
Show detailed information about a task.
```bash
task build --summary
```
#### `--json`
Output task information in JSON format (use with `--list` or `--list-all`).
```bash
task --list --json
```
#### `--sort <mode>`
Change task listing order. Available modes: `default`, `alphanumeric`, `none`.
```bash
task --list --sort alphanumeric
```
### Watch Mode
#### `-w, --watch`
Watch for file changes and re-run tasks automatically.
```bash
task build --watch
```
#### `-I, --interval <duration>`
Set watch interval (default: `5s`). Must be a valid
[Go duration](https://pkg.go.dev/time#ParseDuration).
```bash
task build --watch --interval 1s
```
### Interactive
#### `-y, --yes`
Automatically answer "yes" to all prompts.
```bash
task deploy --yes
```
## Exit Codes
Task uses specific exit codes to indicate different types of errors:
### Success
- **0** - Success
### General Errors (1-99)
- **1** - Unknown error occurred
### Taskfile Errors (100-199)
- **100** - No Taskfile found
- **101** - Taskfile already exists (when using `--init`)
- **102** - Invalid or unparseable Taskfile
- **103** - Remote Taskfile download failed
- **104** - Remote Taskfile not trusted
- **105** - Remote Taskfile fetch not secure
- **106** - No cache for remote Taskfile in offline mode
- **107** - No schema version defined in Taskfile
### Task Errors (200-255)
- **200** - Task not found
- **201** - Command execution error
- **202** - Attempted to run internal task
- **203** - Multiple tasks with same name/alias
- **204** - Task called too many times (recursion limit)
- **205** - Task cancelled by user
- **206** - Missing required variables
- **207** - Variable has incorrect value
::: info
When using `-x/--exit-code`, failed command exit codes are passed through
instead of the above codes.
:::
::: tip
The complete list of exit codes is available in the repository at
[`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).
:::
## JSON Output Format
When using `--json` with `--list` or `--list-all`:
```json
{
"tasks": [
{
"name": "build",
"task": "build",
"desc": "Build the application",
"summary": "Compiles the source code and generates binaries",
"up_to_date": false,
"location": {
"line": 12,
"column": 3,
"taskfile": "/path/to/Taskfile.yml"
}
}
],
"location": "/path/to/Taskfile.yml"
}
```

181
website/src/docs/reference/package.md Normal file
View File

@@ -0,0 +1,181 @@
---
title: CLI Reference
description: Complete reference for Task CLI commands, flags, and exit codes
---
# Package API
::: warning
**_Task's package API is still experimental and subject to breaking changes._**
This means that unlike our CLI, we may make breaking changes to the package API
in minor (or even patch) releases. We try to avoid this when possible, but it
may be necessary in order to improve the overall design of the package API.
In the future we may stabilize the package API. However, this is not currently
planned. For now, if you need to use Task as a Go package, we recommend pinning
the version in your `go.mod` file. Where possible we will try to include a
changelog entry for breaking changes to the package API.
:::
Task is primarily a CLI tool that is agnostic of any programming language.
However, it is written in Go and therefore can also be used as a Go package too.
This can be useful if you are already using Go in your project and you need to
extend Task's functionality in some way. In this document, we describe the
public API surface of Task and how to use it. This may also be useful if you
want to contribute to Task or understand how it works in more detail.
## Key packages
The following packages make up the most important parts of Task's package API.
Below we have listed what they are for and some of the key types available:
### [`github.com/go-task/task/v3`]
The core task package provides most of the main functionality for Task including
fetching and executing tasks from a Taskfile. At this time, the vast majority of
the this package's functionality is exposed via the [`task.Executor`] which
allows the user to fetch and execute tasks from a Taskfile.
::: info
This is the package which is most likely to be the subject of breaking changes
as we refine the API.
:::
### [`github.com/go-task/task/v3/taskfile`]
The `taskfile` package provides utilities for _reading_ Taskfiles from various
sources. These sources can be local files, remote files, or even in-memory
strings (via stdin).
- [`taskfile.Node`] - A reference to the location of a Taskfile. A `Node` is an
interface that has several implementations:
- [`taskfile.FileNode`] - Local files
- [`taskfile.HTTPNode`] - Remote files via HTTP/HTTPS
- [`taskfile.GitNode`] - Remote files via Git
- [`taskfile.StdinNode`] - In-memory strings (via stdin)
- [`taskfile.Reader`] - Accepts a `Node` and reads the Taskfile from it.
- [`taskfile.Snippet`] - Mostly used for rendering Taskfile errors. A snippet
stores a small part of a taskfile around a given line number and column. The
output can be syntax highlighted for CLIs and include line/column indicators.
### [`github.com/go-task/task/v3/taskfile/ast`]
AST stands for ["Abstract Syntax Tree"][ast]. An AST allows us to easily
represent the Taskfile syntax in Go. This package provides a way to parse
Taskfile YAML into an AST and store them in memory.
- [`ast.TaskfileGraph`] - Represents a set of Taskfiles and their dependencies
between one another.
- [`ast.Taskfile`] - Represents a single Taskfile or a set of merged Taskfiles.
The `Taskfile` type contains all of the subtypes for the Taskfile syntax, such
as `tasks`, `includes`, `vars`, etc. These are not listed here for brevity.
### [`github.com/go-task/task/v3/errors`]
Contains all of the error types used in Task. All of these types implement the
[`errors.TaskError`] interface which wraps Go's standard [`error`] interface.
This allows you to call the `Code` method on the error to obtain the unique exit
code for any error.
## Reading Taskfiles
Start by importing the `github.com/go-task/task/v3/taskfile` package. This
provides all of the functions you need to read a Taskfile into memory:
```go
import (
"github.com/go-task/task/v3/taskfile"
)
```
Reading Taskfiles is done by using a [`taskfile.Reader`] and an implementation
of [`taskfile.Node`]. In this example we will read a local file by using the
[`taskfile.FileNode`] type. You can create this by calling the
[`taskfile.NewFileNode`] function:
```go
node := taskfile.NewFileNode("Taskfile.yml", "./path/to/dir")
```
and then create a your reader by calling the [`taskfile.NewReader`] function and
passing any functional options you want to use. For example, you could pass a
debug function to the reader which will be called with debug messages:
```go
reader := taskfile.NewReader(
taskfile.WithDebugFunc(func(s string) {
slog.Debug(s)
}),
)
```
Now that everything is set up, you can read the Taskfile (and any included
Taskfiles) by calling the `Read` method on the reader and pass the `Node` as an
argument:
```go
ctx := context.Background()
tfg, err := reader.Read(ctx, node)
// handle error
```
This returns an instance of [`ast.TaskfileGraph`] which is a "Directed Acyclic
Graph" (DAG) of all the parsed Taskfiles. We use this graph to store and resolve
the `includes` directives in Taskfiles. However most of the time, you will want
a merged Taskfile. To do this, simply call the `Merge` method on the Taskfile
graph:
```go
tf, err := tfg.Merge()
// handle error
```
This compiles the DAG into a single [`ast.Taskfile`] containing all the
namespaces and tasks from all the Taskfiles we read.
::: info
We plan to remove AST merging in the future as it is unnecessarily complex and
causes lots of issues with scoping.
:::
[`github.com/go-task/task/v3`]: https://pkg.go.dev/github.com/go-task/task/v3
[`github.com/go-task/task/v3/taskfile`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile
[`github.com/go-task/task/v3/taskfile/ast`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile/ast
[`github.com/go-task/task/v3/errors`]:
https://pkg.go.dev/github.com/go-task/task/v3/errors
[`ast.TaskfileGraph`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile/ast#TaskfileGraph
[`ast.Taskfile`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile/ast#Taskfile
[`taskfile.Node`]: https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Node
[`taskfile.FileNode`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile#FileNode
[`taskfile.HTTPNode`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile#HTTPNode
[`taskfile.GitNode`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile#GitNode
[`taskfile.StdinNode`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile#StdinNode
[`taskfile.NewFileNode`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile#NewFileNode
[`taskfile.Reader`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader
[`taskfile.NewReader`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile#NewReader
[`taskfile.Snippet`]:
https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Snippet
[`task.Executor`]: https://pkg.go.dev/github.com/go-task/task/v3#Executor
[`task.Formatter`]: https://pkg.go.dev/github.com/go-task/task/v3#Formatter
[`errors.TaskError`]:
https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskError
[`error`]: https://pkg.go.dev/builtin#error
[ast]: https://en.wikipedia.org/wiki/Abstract_syntax_tree

840
website/src/docs/reference/schema.md Normal file
View File

@@ -0,0 +1,840 @@
---
title: Schema Reference
description:
Complete reference for the Taskfile schema based on the official JSON schema
outline: deep
---
# Schema Reference
This page documents all available properties and types for the Taskfile schema
version 3, based on the
[official JSON schema](https://taskfile.dev/schema.json).
## 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
```yaml
version: '3'
```
### `output`
- **Type**: `string` or `object`
- **Default**: `interleaved`
- **Options**: `interleaved`, `group`, `prefixed`
- **Description**: Controls how task output is displayed
```yaml
# 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
```yaml
method: timestamp
```
### [`includes`](#include)
- **Type**: `map[string]Include`
- **Description**: Include other Taskfiles
```yaml
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`](#variable)
- **Type**: `map[string]Variable`
- **Description**: Global variables available to all tasks
```yaml
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
```yaml
env:
NODE_ENV: production
DATABASE_URL:
sh: echo $DATABASE_URL
```
### [`tasks`](#task)
- **Type**: `map[string]Task`
- **Description**: Task definitions
```yaml
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
```yaml
silent: true
```
### `dotenv`
- **Type**: `[]string`
- **Description**: Load environment variables from .env files
```yaml
dotenv:
- .env
- .env.local
```
### `run`
- **Type**: `string`
- **Default**: `always`
- **Options**: `always`, `once`, `when_changed`
- **Description**: Default execution behavior for tasks
```yaml
run: once
```
### `interval`
- **Type**: `string`
- **Default**: `100ms`
- **Pattern**: `^[0-9]+(?:m|s|ms)$`
- **Description**: Watch interval for file changes
```yaml
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
```yaml
set: [errexit, nounset, pipefail]
```
### `shopt`
- **Type**: `[]string`
- **Options**: `expand_aliases`, `globstar`, `nullglob`
- **Description**: Bash shell options for all commands
```yaml
shopt: [globstar]
```
## Include
Configuration for including external Taskfiles.
### `taskfile`
- **Type**: `string`
- **Required**: Yes
- **Description**: Path to the Taskfile or directory to include
```yaml
includes:
backend: ./backend/Taskfile.yml
# Shorthand for above
frontend: ./frontend
```
### `dir`
- **Type**: `string`
- **Description**: Working directory for included tasks
```yaml
includes:
api:
taskfile: ./api
dir: ./api
```
### `optional`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Don't error if the included file doesn't exist
```yaml
includes:
optional-tasks:
taskfile: ./optional.yml
optional: true
```
### `flatten`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Include tasks without namespace prefix
```yaml
includes:
common:
taskfile: ./common.yml
flatten: true
```
### `internal`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Hide included tasks from command line and `--list`
```yaml
includes:
internal:
taskfile: ./internal.yml
internal: true
```
### `aliases`
- **Type**: `[]string`
- **Description**: Alternative names for the namespace
```yaml
includes:
database:
taskfile: ./db.yml
aliases: [db, data]
```
### `excludes`
- **Type**: `[]string`
- **Description**: Tasks to exclude from inclusion
```yaml
includes:
shared:
taskfile: ./shared.yml
excludes: [internal-setup, debug-only]
```
### `vars`
- **Type**: `map[string]Variable`
- **Description**: Variables to pass to the included Taskfile
```yaml
includes:
deploy:
taskfile: ./deploy.yml
vars:
ENVIRONMENT: production
```
### `checksum`
- **Type**: `string`
- **Description**: Expected checksum of the included file
```yaml
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
```yaml
vars:
# String
APP_NAME: myapp
# Number
PORT: 8080
# Boolean
DEBUG: true
# Array
FEATURES: [auth, logging, metrics]
# Null
OPTIONAL_VAR: null
```
### Dynamic Variables (`sh`)
```yaml
vars:
COMMIT_HASH:
sh: git rev-parse HEAD
BUILD_TIME:
sh: date -u +"%Y-%m-%dT%H:%M:%SZ"
```
### Variable References (`ref`)
```yaml
vars:
BASE_VERSION: 1.0.0
FULL_VERSION:
ref: BASE_VERSION
```
### Map Variables (`map`)
```yaml
vars:
CONFIG:
map:
database:
host: localhost
port: 5432
cache:
type: redis
ttl: 3600
```
### Variable Ordering
Variables can reference previously defined variables:
```yaml
vars:
GREETING: Hello
TARGET: World
MESSAGE: '{{.GREETING}} {{.TARGET}}!'
```
## Task
Individual task configuration with multiple syntax options.
### Simple Task Formats
```yaml
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
```yaml
tasks:
build:
cmds:
- go build ./...
- echo "Build complete"
```
#### `cmd`
- **Type**: `string`
- **Description**: Single command (alternative to `cmds`)
```yaml
tasks:
test:
cmd: go test ./...
```
#### `deps`
- **Type**: `[]Dependency`
- **Description**: Tasks to run before this task
```yaml
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`
```yaml
tasks:
test:
desc: Run unit tests
cmds:
- go test ./...
```
#### `summary`
- **Type**: `string`
- **Description**: Detailed description shown in `--summary`
```yaml
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
```yaml
tasks:
deploy:
prompt: "Deploy to production?"
# or multiple prompts
prompt:
- "Are you sure?"
- "This will affect live users!"
```
#### `aliases`
- **Type**: `[]string`
- **Description**: Alternative names for the task
```yaml
tasks:
build:
aliases: [compile, make]
cmds:
- go build ./...
```
#### `sources`
- **Type**: `[]string` or `[]Glob`
- **Description**: Source files to monitor for changes
```yaml
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
```yaml
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
```yaml
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
```yaml
tasks:
# Simple precondition (shorthand)
build:
preconditions:
- test -f ./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
```
#### `requires`
- **Type**: `Requires`
- **Description**: Required variables with optional enums
```yaml
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
```
#### `watch`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Automatically run task in watch mode
```yaml
tasks:
dev:
watch: true
cmds:
- npm run dev
```
#### `platforms`
- **Type**: `[]string`
- **Description**: Platforms where this task should run
```yaml
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
```yaml
tasks:
example:
cmds:
- echo "Simple command"
- ls -la
```
### Command Object
```yaml
tasks:
example:
cmds:
- cmd: echo "Hello World"
silent: true
ignore_error: false
platforms: [linux, darwin]
set: [errexit]
shopt: [globstar]
```
### Task References
```yaml
tasks:
example:
cmds:
- task: other-task
vars:
PARAM: value
silent: false
```
### Deferred Commands
```yaml
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
```yaml
tasks:
greet-all:
cmds:
- for: [alice, bob, charlie]
cmd: echo "Hello {{.ITEM}}"
```
#### Loop Over Sources/Generates
```yaml
tasks:
process-files:
sources: ['*.txt']
cmds:
- for: sources
cmd: wc -l {{.ITEM}}
- for: generates
cmd: gzip {{.ITEM}}
```
#### Loop Over Variable
```yaml
tasks:
process-items:
vars:
ITEMS: 'item1,item2,item3'
cmds:
- for:
var: ITEMS
split: ','
as: CURRENT
cmd: echo "Processing {{.CURRENT}}"
```
#### Loop Over Matrix
```yaml
tasks:
test-matrix:
cmds:
- for:
matrix:
OS: [linux, windows, darwin]
ARCH: [amd64, arm64]
cmd: echo "Testing {{.OS}}/{{.ARCH}}"
```
#### Loop in Dependencies
```yaml
tasks:
build-all:
deps:
- for: [frontend, backend, worker]
task: build
vars:
SERVICE: '{{.ITEM}}'
```
## 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
```yaml
# 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
```yaml
# Global level
shopt: [globstar]
tasks:
find-files:
# Task level
shopt: [nullglob]
cmds:
- cmd: ls **/*.go
# Command level
shopt: [globstar]
```

781
website/src/docs/reference/templating.md Normal file
View File

@@ -0,0 +1,781 @@
---
title: Templating Reference
description:
Comprehensive guide to Task's templating system with Go text/template, special
variables, and available functions
outline: deep
---
# Templating Reference
Task's templating engine uses Go's
[text/template](https://pkg.go.dev/text/template) package to interpolate values.
This reference covers the main features and all available functions for creating
dynamic Taskfiles.
## Basic Usage
Most string values in Task can be templated using double curly braces
<span v-pre>`{{` and `}}`</span>. Anything inside the braces is executed as a Go
template.
### Simple Variable Interpolation
```yaml
version: '3'
tasks:
hello:
vars:
MESSAGE: 'Hello, World!'
cmds:
- 'echo {{.MESSAGE}}'
```
**Output:**
```
Hello, World!
```
### Conditional Logic
```yaml
version: '3'
tasks:
maybe-happy:
vars:
SMILE: ':\)'
FROWN: ':\('
HAPPY: true
cmds:
- 'echo {{if .HAPPY}}{{.SMILE}}{{else}}{{.FROWN}}{{end}}'
```
**Output:**
```
:)
```
### Function Calls and Pipes
```yaml
version: '3'
tasks:
uniq:
vars:
NUMBERS: '0,1,1,1,2,2,3'
cmds:
- 'echo {{splitList "," .NUMBERS | uniq | join ", "}}'
```
**Output:**
```
0, 1, 2, 3
```
### Control Flow with Loops
```yaml
version: '3'
tasks:
loop:
vars:
NUMBERS: [0, 1, 1, 1, 2, 2, 3]
cmds:
- |
{{range $index, $num := .NUMBERS}}
{{if gt $num 1}}{{break}}{{end}}
echo {{$index}}: {{$num}}
{{end}}
```
**Output:**
```
0: 0
1: 1
2: 1
3: 1
```
## Special Variables
Task provides special variables that are always available in templates. These
override any user-defined variables with the same name.
### CLI
#### `CLI_ARGS`
- **Type**: `string`
- **Description**: All extra arguments passed after `--` as a string
```yaml
tasks:
test:
cmds:
- go test {{.CLI_ARGS}}
```
```bash
task test -- -v -race
# Runs: go test -v -race
```
#### `CLI_ARGS_LIST`
- **Type**: `[]string`
- **Description**: All extra arguments passed after `--` as a shell parsed list
```yaml
tasks:
docker-run:
cmds:
- docker run {{range .CLI_ARGS_LIST}}{{.}} {{end}}myapp
```
#### `CLI_FORCE`
- **Type**: `bool`
- **Description**: Whether `--force` or `--force-all` flags were set
```yaml
tasks:
deploy:
cmds:
- |
{{if .CLI_FORCE}}
echo "Force deployment enabled"
{{end}}
./deploy.sh
```
#### `CLI_SILENT`
- **Type**: `bool`
- **Description**: Whether `--silent` flag was set
#### `CLI_VERBOSE`
- **Type**: `bool`
- **Description**: Whether `--verbose` flag was set
#### `CLI_OFFLINE`
- **Type**: `bool`
- **Description**: Whether `--offline` flag was set
### Task
#### `TASK`
- **Type**: `string`
- **Description**: Name of the current task
```yaml
tasks:
build:
cmds:
- echo "Running task {{.TASK}}"
```
#### `ALIAS`
- **Type**: `string`
- **Description**: Alias used for the current task, otherwise matches `TASK`
#### `TASK_EXE`
- **Type**: `string`
- **Description**: Task executable name or path
```yaml
tasks:
self-update:
cmds:
- echo "Updating {{.TASK_EXE}}"
```
### File Paths
#### `ROOT_TASKFILE`
- **Type**: `string`
- **Description**: Absolute path of the root Taskfile
#### `ROOT_DIR`
- **Type**: `string`
- **Description**: Absolute path of the root Taskfile directory
#### `TASKFILE`
- **Type**: `string`
- **Description**: Absolute path of the current (included) Taskfile
#### `TASKFILE_DIR`
- **Type**: `string`
- **Description**: Absolute path of the current Taskfile directory
#### `TASK_DIR`
- **Type**: `string`
- **Description**: Absolute path where the task is executed
#### `USER_WORKING_DIR`
- **Type**: `string`
- **Description**: Absolute path where `task` was called from
```yaml
tasks:
info:
cmds:
- echo "Root {{.ROOT_DIR}}"
- echo "Current {{.TASKFILE_DIR}}"
- echo "Working {{.USER_WORKING_DIR}}"
```
### Status
#### `CHECKSUM`
- **Type**: `string`
- **Description**: Checksum of files in `sources` (only in `status` with
`checksum` method)
#### `TIMESTAMP`
- **Type**: `time.Time`
- **Description**: Greatest timestamp of files in `sources` (only in `status`
with `timestamp` method)
```yaml
tasks:
build:
method: checksum
sources: ['**/*.go']
status:
- test "{{.CHECKSUM}}" = "$(cat .last-checksum)"
cmds:
- go build ./...
- echo "{{.CHECKSUM}}" > .last-checksum
```
### Loop
#### `ITEM`
- **Type**: `any`
- **Description**: Current iteration value when using `for` property
```yaml
tasks:
greet:
cmds:
- for: [alice, bob, charlie]
cmd: echo "Hello {{.ITEM}}"
```
Can be renamed using `as`:
```yaml
tasks:
greet:
cmds:
- for:
var: NAMES
as: NAME
cmd: echo "Hello {{.NAME}}"
```
### Defer
#### `EXIT_CODE`
- **Type**: `int`
- **Description**: Failed command exit code (only in `defer`, only when
non-zero)
```yaml
tasks:
deploy:
cmds:
- ./deploy.sh
- defer: |
{{if .EXIT_CODE}}
echo "Deployment failed with code {{.EXIT_CODE}}"
./rollback.sh
{{end}}
```
### System
#### `TASK_VERSION`
- **Type**: `string`
- **Description**: Current version of Task
```yaml
tasks:
version:
cmds:
- echo "Using Task {{.TASK_VERSION}}"
```
## Available Functions
Task provides a comprehensive set of functions for templating. Functions can be chained using pipes (`|`) and combined for powerful templating capabilities.
### Logic and Control Flow
#### `and`, `or`, `not`
Boolean operations for conditional logic
```yaml
tasks:
conditional:
vars:
DEBUG: true
VERBOSE: false
PRODUCTION: false
cmds:
- echo "{{if and .DEBUG .VERBOSE}}Debug mode with verbose{{end}}"
- echo "{{if or .DEBUG .VERBOSE}}Some kind of debug{{end}}"
- echo "{{if not .PRODUCTION}}Development build{{end}}"
```
#### `eq`, `ne`, `lt`, `le`, `gt`, `ge`
Comparison operations
```yaml
tasks:
compare:
vars:
VERSION: 3
cmds:
- echo "{{if gt .VERSION 2}}Version 3 or higher{{end}}"
- echo "{{if eq .VERSION 3}}Exactly version 3{{end}}"
```
### Data Access and Manipulation
#### `index`
Access array/map elements by index or key
```yaml
tasks:
access:
vars:
SERVICES: [api, web, worker]
CONFIG:
map:
database: postgres
port: 5432
cmds:
- echo "First service {{index .SERVICES 0}}"
- echo "Database {{index .CONFIG "database"}}"
```
#### `len`
Get length of arrays, maps, or strings
```yaml
tasks:
length:
vars:
ITEMS: [a, b, c, d]
TEXT: "Hello World"
cmds:
- echo "Found {{len .ITEMS}} items"
- echo "Text has {{len .TEXT}} characters"
```
#### `slice`
Extract a portion of an array or string
```yaml
tasks:
slice-demo:
vars:
ITEMS: [a, b, c, d, e]
cmds:
- echo "{{slice .ITEMS 1 3}}" # [b c]
```
### String Functions
#### Basic String Operations
```yaml
tasks:
string-basic:
vars:
MESSAGE: ' Hello World '
NAME: 'john doe'
TEXT: "Hello World"
cmds:
- echo "{{.MESSAGE | trim}}" # "Hello World"
- echo "{{.NAME | title}}" # "John Doe"
- echo "{{.NAME | upper}}" # "JOHN DOE"
- echo "{{.MESSAGE | lower}}" # "hello world"
- echo "{{.NAME | trunc 4}}" # "john"
- echo "{{"test" | repeat 3}}" # "testtesttest"
- echo "{{substr .TEXT 0 5}}" # "Hello"
```
#### String Testing and Searching
```yaml
tasks:
string-test:
vars:
FILENAME: 'app.tar.gz'
EMAIL: 'user@example.com'
cmds:
- echo "{{.FILENAME | hasPrefix "app"}}" # true
- echo "{{.FILENAME | hasSuffix ".gz"}}" # true
- echo "{{.EMAIL | contains "@"}}" # true
```
#### String Replacement and Formatting
```yaml
tasks:
string-format:
vars:
TEXT: 'Hello, World!'
UNSAFE: 'file with spaces.txt'
cmds:
- echo "{{.TEXT | replace "," ""}}" # "Hello World!"
- echo "{{.TEXT | quote}}" # "\"Hello, World!\""
- echo "{{.UNSAFE | shellQuote}}" # Shell-safe quoting
- echo "{{.UNSAFE | q}}" # Short alias for shellQuote
```
#### Regular Expressions
```yaml
tasks:
regex:
vars:
EMAIL: 'user@example.com'
TEXT: 'abc123def456'
cmds:
- echo "{{regexMatch "@" .EMAIL}}" # true
- echo "{{regexFind "[0-9]+" .TEXT}}" # "123"
- echo "{{regexFindAll "[0-9]+" .TEXT -1}}" # ["123", "456"]
- echo "{{regexReplaceAll "[0-9]+" .TEXT "X"}}" # "abcXdefX"
```
### List Functions
#### List Access and Basic Operations
```yaml
tasks:
list-basic:
vars:
ITEMS: ["apple", "banana", "cherry", "date"]
cmds:
- echo "First {{.ITEMS | first}}" # "apple"
- echo "Last {{.ITEMS | last}}" # "date"
- echo "Rest {{.ITEMS | rest}}" # ["banana", "cherry", "date"]
- echo "Initial {{.ITEMS | initial}}" # ["apple", "banana", "cherry"]
- echo "Length {{.ITEMS | len}}" # 4
```
#### List Manipulation
```yaml
tasks:
list-manipulate:
vars:
NUMBERS: [3, 1, 4, 1, 5, 9, 1]
FRUITS: ["apple", "banana"]
cmds:
- echo "{{.NUMBERS | uniq}}" # [3, 1, 4, 5, 9]
- echo "{{.NUMBERS | sortAlpha}}" # [1, 1, 1, 3, 4, 5, 9]
- echo"'{{append .FRUITS "cherry"}}"" # ["apple", "banana", "cherry"]
- echo "{{ without .NUMBERS 1}}" # [3, 4, 5, 9]
- echo "{{.NUMBERS | has 5}}" # true
```
#### String Lists
```yaml
tasks:
string-lists:
vars:
CSV: 'apple,banana,cherry'
WORDS: ['hello', 'world', 'from', 'task']
MULTILINE: |
line1
line2
line3
cmds:
- echo "{{.CSV | splitList ","}}" # ["apple", "banana", "cherry"]
- echo "{{.WORDS | join " "}}" # "hello world from task"
- echo "{{.WORDS | sortAlpha}}" # ["from", "hello", "task", "world"]
- echo "{{.MULTILINE | splitLines}}" # Split on newlines (Unix/Windows)
- echo "{{.MULTILINE | catLines}}" # Replace newlines with spaces
```
#### Shell Argument Parsing
```yaml
tasks:
shell-args:
vars:
ARGS: 'file1.txt -v --output="result file.txt"'
cmds:
- |
{{range .ARGS | splitArgs}}
echo "Arg: {{.}}"
{{end}}
```
### Math Functions
```yaml
tasks:
math:
vars:
A: 10
B: 3
NUMBERS: [1, 5, 3, 9, 2]
cmds:
- echo "Addition {{add .A .B}}" # 13
- echo "Subtraction {{sub .A .B}}" # 7
- echo "Multiplication {{mul .A .B}}" # 30
- echo "Division {{div .A .B}}" # 3
- echo "Modulo {{mod .A .B}}" # 1
- echo "Maximum {{.NUMBERS | max}}" # 9
- echo "Minimum {{.NUMBERS | min}}" # 1
- echo "Random 1-99 {{randInt 1 100}}" # Random number
- echo "Random 0-999 {{randIntN 1000}}" # Random number 0-999
```
### Date and Time Functions
```yaml
tasks:
date-time:
vars:
BUILD_DATE: "2023-12-25"
cmds:
- echo "Now {{now | date "2006-01-02 15:04:05"}}"
- echo {{ toDate "2006-01-02" .BUILD_DATE }}
- echo "Build {{.BUILD_DATE | toDate "2006-01-02" | date "Jan 2, 2006"}}"
- echo "Unix timestamp {{now | unixEpoch}}"
- echo "Duration ago {{now | ago}}"
```
### System Functions
#### Platform Information
```yaml
tasks:
platform:
cmds:
- echo "OS {{OS}}" # linux, darwin, windows, etc.
- echo "Architecture {{ARCH}}" # amd64, arm64, etc.
- echo "CPU cores {{numCPU}}" # Number of CPU cores
- echo "Building for {{OS}}/{{ARCH}}"
```
#### Path Functions
```yaml
tasks:
paths:
vars:
WIN_PATH: 'C:\Users\name\file.txt'
OUTPUT_DIR: 'dist'
BINARY_NAME: 'myapp'
cmds:
- echo "{{.WIN_PATH | toSlash}}" # Convert to forward slashes
- echo "{{.WIN_PATH | fromSlash}}" # Convert to OS-specific slashes
- echo "{{joinPath .OUTPUT_DIR .BINARY_NAME}}" # Join path elements
- echo "Relative {{relPath .ROOT_DIR .TASKFILE_DIR}}" # Get relative path
```
### Data Structure Functions
#### Dictionary Operations
```yaml
tasks:
dict:
vars:
CONFIG:
map:
database: postgres
port: 5432
ssl: true
cmds:
- echo "Database {{.CONFIG | get "database"}}"
- echo "Keys {{.CONFIG | keys}}"
- echo "Has SSL {{.CONFIG | hasKey "ssl"}}"
- echo "{{dict "env" "prod" "debug" false}}"
```
#### Merging and Combining
```yaml
tasks:
merge:
vars:
BASE_CONFIG:
map:
timeout: 30
retries: 3
USER_CONFIG:
map:
timeout: 60
debug: true
cmds:
- echo "{{merge .BASE_CONFIG .USER_CONFIG | toJson}}"
```
### Default Values and Coalescing
```yaml
tasks:
defaults:
vars:
API_URL: ""
DEBUG: false
ITEMS: []
cmds:
- echo "{{.API_URL | default "http://localhost:8080"}}"
- echo "{{.DEBUG | default true}}"
- echo "{{.MISSING_VAR | default "fallback"}}"
- echo "{{coalesce .API_URL .FALLBACK_URL "default"}}"
- echo "Is empty {{empty .ITEMS}}" # true
```
### Encoding and Serialization
#### JSON
```yaml
tasks:
json:
vars:
DATA:
map:
name: 'Task'
version: '3.0'
JSON_STRING: '{"key": "value", "number": 42}'
cmds:
- echo "{{.DATA | toJson}}"
- echo "{{.DATA | toPrettyJson}}"
- echo "{{.JSON_STRING | fromJson }}"
```
#### YAML
```yaml
tasks:
yaml:
vars:
CONFIG:
map:
database:
host: localhost
port: 5432
YAML_STRING: |
key: value
items:
- one
- two
cmds:
- echo "{{.CONFIG | toYaml}}"
- echo "{{.YAML_STRING | fromYaml}}"
```
#### Base64
```yaml
tasks:
base64:
vars:
SECRET: 'my-secret-key'
cmds:
- echo "{{.SECRET | b64enc}}" # Encode to base64
- echo "{{"bXktc2VjcmV0LWtleQ==" | b64dec}}" # Decode from base64
```
### Type Conversion
```yaml
tasks:
convert:
vars:
NUM_STR: '42'
FLOAT_STR: '3.14'
BOOL_STR: 'true'
ITEMS: [1, 2, 3]
cmds:
- echo "{{.NUM_STR | atoi | add 8}}" # String to int: 50
- echo "{{.FLOAT_STR | float64}}" # String to float: 3.14
- echo "{{.ITEMS | toStrings}}" # Convert to strings: ["1", "2", "3"]
```
### Utility Functions
#### UUID Generation
```yaml
tasks:
generate:
vars:
DEPLOYMENT_ID: "{{uuid}}"
cmds:
- echo "Deployment ID {{.DEPLOYMENT_ID}}"
```
#### Debugging
```yaml
tasks:
debug:
vars:
COMPLEX_VAR:
map:
items: [1, 2, 3]
nested:
key: value
cmds:
- echo "{{spew .COMPLEX_VAR}}" # Pretty-print for debugging
```
### Output Functions
#### Formatted Output
```yaml
tasks:
output:
vars:
VERSION: "1.2.3"
BUILD: 42
cmds:
- echo '{{print "Simple output"}}'
- echo '{{printf "Version %s.%d" .VERSION .BUILD}}'
- echo '{{println "With newline"}}'
```