Task (go-task)

Table of Contents

1. How It Works
2. Supported File Patterns
   1. Global Taskfile
   2. Custom Taskfile Patterns
3. Task Execution
4. Example Taskfile
5. Configuration
   1. Enabling / Disabling
   2. Application Path
   3. Aliases In The Tree
6. Watch Mode
7. Troubleshooting
   1. No tasks appear in the tree view
   2. Tasks from included Taskfiles are missing
8. Related

---

Task is a fast, cross-platform task runner and build tool written in Go. It is designed as a simpler, more portable alternative to Make. Tasks are defined in a Taskfile.yml file using a clean YAML syntax with support for variables, dependencies, namespacing, includes, and remote Taskfiles.

How It Works

Task discovery uses the CLI’s built-in JSON output mode rather than static YAML parsing. This correctly resolves included Taskfiles, namespaced tasks, and template variables that a static parser cannot evaluate. For each directory in the workspace that contains a Taskfile, the extension runs:

task --list-all --no-status --json

The JSON response contains the resolved task name, description, and source location (file path and line number) for every available task. Each task is surfaced as a runnable entry in the tree view.

The task executable must be installed and accessible on your system PATH (or configured via workspaceTasks.applicationPath.task) for task discovery to work. If the executable is not found, no tasks are discovered from Taskfiles.

---

Supported File Patterns

The extension scans for any of the following Taskfile filenames anywhere in the workspace:

Pattern	Description
**/Taskfile.yml	Standard Taskfile (recommended name)
**/taskfile.yml	Lowercase variant
**/Taskfile.yaml	YAML extension variant
**/taskfile.yaml	Lowercase YAML variant
**/Taskfile.dist.yml	Distribution Taskfile (intended for version control)
**/taskfile.dist.yml	Lowercase distribution variant
**/Taskfile.dist.yaml	Distribution YAML variant
**/taskfile.dist.yaml	Lowercase distribution YAML variant

When multiple Taskfile variants exist in the same directory (e.g. both Taskfile.yml and Taskfile.dist.yml), the directory is scanned only once by the CLI, which automatically applies its own resolution precedence.

Global Taskfiles ($HOME/Taskfile.yml) are outside the workspace and are not discovered by default.

Global Taskfile

Task can discover tasks from a global Taskfile in your home directory when enabled:

{
  "workspaceTasks.taskfile.discoverGlobalTaskfile": true
}

When enabled, Workspace Tasks checks standard Taskfile variants in $HOME and uses the first one found by Task precedence. These files are watched for create/change/delete events, and global tasks are refreshed automatically when they change.

Custom Taskfile Patterns

If your project uses non-standard Taskfile names, add custom glob patterns to discover them:

{
  "workspaceTasks.taskfile.additionalFilePatterns": [
    "**/Taskfile.ci.yml",
    "**/backend/MyTasks.yml"
  ]
}

Executions automatically include --taskfile <absolute path> to ensure the selected Taskfile is used consistently regardless of current working directory.

---

Task Execution

When you run a Task task, the extension invokes:

task <taskName> [args]

The working directory is set to the directory containing the Taskfile. This ensures task resolves the correct Taskfile, local includes, and relative paths.

Run with arguments example:

task deploy --force

---

Example Taskfile

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

version: '3'

vars:
  APP_NAME: my-app

tasks:
  default:
    desc: Print a greeting message
    cmds:
      - echo "Hello from Task!"
    silent: true

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

  test:
    desc: Run the test suite
    cmds:
      - echo "Running tests for ..."

  ci:
    desc: Run the full CI pipeline
    deps: [build, test]

---

Configuration

Enabling / Disabling

Task support is enabled by default. To disable it, add the following to your VS Code settings:

{
  "workspaceTasks.enabledTaskTypes": {
    "taskfile": false
  }
}

Application Path

If task is not on your system PATH, or you want to use a specific version, configure the executable path:

{
  "workspaceTasks.applicationPath.taskfile": "/usr/local/bin/task"
}

On Windows, if the path ends with task (without .exe), the .exe extension is appended automatically. The ~/ prefix is expanded to your home directory on all platforms.

See Application Paths for the full reference.

Aliases In The Tree

Task supports aliases (alternative names for the same task). When workspaceTasks.taskfile.showAliases is enabled (default: true), tasks with aliases appear as expandable tree items and each alias is shown as a child item.

Running an alias child executes:

task <alias>

Disable alias child items in the tree with:

{
  "workspaceTasks.taskfile.showAliases": false
}

---

Watch Mode

Task supports a watch mode (task --watch) that re-runs a task whenever its source files change. To start a task in watch mode, click the Watch ($(eye)) button that appears next to a task item in the tree view, or right-click and select Watch Task.

Watch mode opens a new integrated terminal named task watch: <taskName>. Close the terminal to stop watching.

To disable the Watch button on task items:

{
  "workspaceTasks.taskfile.enableWatchMode": false
}

---

Troubleshooting

No tasks appear in the tree view

1. Check that task is installed. Run task --version in a terminal to verify.
2. Check the application path setting. If task is not on your PATH, set workspaceTasks.applicationPath.task to the full path of the executable.
3. Check that task is enabled. Verify workspaceTasks.enabledTaskTypes.task is true (it is true by default).
4. Reload the workspace. Use the Workspace Tasks: Refresh command (Ctrl+Shift+P → Workspace Tasks: Refresh).

Tasks from included Taskfiles are missing

Task automatically resolves includes when --list-all --json is invoked. If included Taskfiles reference paths that do not exist, task may print an error to stderr instead of returning JSON. Check the extension output channel (Workspace Tasks in the Output panel) for warning messages from the task discovery process.

---

Related

• Task Runners overview — all supported task runners
• Application Paths — configure executable paths
• Enabling / Disabling Task Types — control which task types are active
• Task website — official documentation
• Task on GitHub — source code and issue tracker