这是indexloc提供的服务，不要输入任何密码
Skip to content

docs: document HCL Taskfile support #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 5, 2025
Merged

docs: document HCL Taskfile support #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@
Task is a task runner / build tool that aims to be simpler and easier to use than, for example, <a href="https://www.gnu.org/software/make/">GNU Make<a>.
</p>

<p>
Taskfiles can be written in YAML or HCL. By default Task looks for <code>Taskfile.yml</code>, <code>Taskfile.yaml</code>, <code>Taskfile.hcl</code>, or a plain <code>Taskfile</code> in your project.
</p>

<p>
<a href="https://taskfile.dev/installation/">Installation</a> | <a href="https://taskfile.dev/usage/">Documentation</a> | <a href="https://twitter.com/taskfiledev">Twitter</a> | <a href="https://bsky.app/profile/taskfile.dev">Bluesky</a> | <a href="https://fosstodon.org/@task">Mastodon</a> | <a href="https://discord.gg/6TY36E39UK">Discord</a>
</p>
Expand Down
3 changes: 3 additions & 0 deletions internal/flags/flags.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ was specified, or lists all tasks if an unknown task name was specified.
Example: 'task hello' with the following 'Taskfile.yml' file will generate an
'output.txt' file with the content "hello".

Taskfiles can be written in YAML or HCL. By default Task looks for
'Taskfile.yml', 'Taskfile.yaml', 'Taskfile.hcl', or a bare 'Taskfile'.

'''
version: '3'
tasks:
Expand Down
29 changes: 21 additions & 8 deletions website/docs/getting_started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,24 @@ tasks:
silent: true
```

As you can see, all Taskfiles are written in [YAML format][yaml]. The `version`
attribute specifies the minimum version of Task that can be used to run this
file. The `vars` attribute is used to define variables that can be used in
tasks. In this case, we are creating a string variable called `GREETING` with a
value of `Hello, World!`.
The example above is written in [YAML format][yaml], but Taskfiles can also be
written in HCL:

```hcl
version = "3"

vars = { GREETING = "Hello, World!" }

task "default" {
cmds = ["echo ${GREETING}"]
silent = true
}
```

Both formats are fully supported. The `version` attribute specifies the minimum
version of Task that can be used to run this file. The `vars` attribute is used
to define variables that can be used in tasks. In this case, we are creating a
string variable called `GREETING` with a value of `Hello, World!`.

Finally, the `tasks` attribute is used to define the tasks that can be run. In
this case, we have a task called `default` that echoes the value of the
Expand All @@ -71,9 +84,9 @@ task default

Note that we don't have to specify the name of the Taskfile. Task will
automatically look for a file called `Taskfile.yml` (or any of Task's [supported
file names][supported-file-names]) in the current directory. Additionally, tasks
with the name `default` are special. They can also be run without specifying the
task name.
file names][supported-file-names], such as `Taskfile.hcl` or a plain
`Taskfile`) in the current directory. Additionally, tasks with the name
`default` are special. They can also be run without specifying the task name.

If you created a Taskfile in a different directory, you can run it by passing
the absolute or relative path to the directory as an argument using the `--dir`
Expand Down
8 changes: 5 additions & 3 deletions website/docs/reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,11 @@ If `--` is given, all remaining arguments will be assigned to a special
| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/{T,t}askfile.{yml,yaml,hcl}` or `$HOME/{T,t}askfile`.
|
| `-h` | `--help` | `bool` | `false` | Shows Task usage.
| `-i` | `--init` | `bool` | `false` | Creates a new `Taskfile.yml` in the current folder.
|
| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
Expand Down
2 changes: 1 addition & 1 deletion website/docs/reference/package.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ strings (via stdin).

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.
Taskfile configuration (YAML or HCL) into an AST and store them in memory.

- [`ast.TaskfileGraph`] - Represents a set of Taskfiles and their dependencies
between one another.
Expand Down
6 changes: 4 additions & 2 deletions website/docs/styleguide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,10 @@ sidebar_position: 11

# Style Guide

This is the official style guide for `Taskfile.yml` files. It provides basic
instructions for keeping your Taskfiles clean and familiar to other users.
This is the official style guide for `Taskfile.yml` files. Task also supports
Taskfiles written in HCL, but this guide focuses on the YAML format. It
provides basic instructions for keeping your Taskfiles clean and familiar to
other users.

This guide contains general guidelines, but they do not necessarily need to be
followed strictly. Feel free to disagree and do things differently if you need
Expand Down
20 changes: 16 additions & 4 deletions website/docs/usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,16 @@ Task looks for files with the following names, in order of priority:
- `taskfile.dist.yml`
- `Taskfile.dist.yaml`
- `taskfile.dist.yaml`
- `Taskfile.hcl`
- `taskfile.hcl`
- `Taskfile`
- `taskfile`

The `.dist` variants allow projects to have one committed file (`.dist`) while
still allowing individual users to override the Taskfile by adding an additional
`Taskfile.yml` (which would be in your `.gitignore`).
`Taskfile.yml` (which would be in your `.gitignore`). YAML files are checked
before HCL or extensionless files. If both YAML and HCL Taskfiles are present,
the YAML file will be used.

### Running a Taskfile from a subdirectory

Expand Down Expand Up @@ -65,7 +71,8 @@ will be brought up.

If you call Task with the `--global` (alias `-g`) flag, it will look for your
home directory instead of your working directory. In short, Task will look for a
Taskfile that matches `$HOME/{T,t}askfile.{yml,yaml}` .
Taskfile that matches `$HOME/{T,t}askfile.{yml,yaml,hcl}` or
`$HOME/{T,t}askfile`.

This is useful to have automation that you can run from anywhere in your system!

Expand Down Expand Up @@ -97,14 +104,19 @@ tasks:
### Reading a Taskfile from stdin

Taskfile also supports reading from stdin. This is useful if you are generating
Taskfiles dynamically and don't want write them to disk. To tell task to read
Taskfiles dynamically and don't want write them to disk. To tell Task to read
from stdin, you must specify the `-t/--taskfile` flag with the special `-`
value. You may then pipe into Task as you would any other program:
value. You may then pipe into Task as you would any other program. Both YAML and
HCL content are supported and Task will attempt to detect the format
automatically:

```shell
task -t - <(cat ./Taskfile.yml)
# OR
cat ./Taskfile.yml | task -t -

# HCL content works too
cat ./Taskfile.hcl | task -t -
```

## Environment variables
Expand Down
29 changes: 21 additions & 8 deletions website/versioned_docs/version-latest/getting_started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,24 @@ tasks:
silent: true
```

As you can see, all Taskfiles are written in [YAML format][yaml]. The `version`
attribute specifies the minimum version of Task that can be used to run this
file. The `vars` attribute is used to define variables that can be used in
tasks. In this case, we are creating a string variable called `GREETING` with a
value of `Hello, World!`.
The example above is written in [YAML format][yaml], but Taskfiles can also be
written in HCL:

```hcl
version = "3"

vars = { GREETING = "Hello, World!" }

task "default" {
cmds = ["echo ${GREETING}"]
silent = true
}
```

Both formats are fully supported. The `version` attribute specifies the minimum
version of Task that can be used to run this file. The `vars` attribute is used
to define variables that can be used in tasks. In this case, we are creating a
string variable called `GREETING` with a value of `Hello, World!`.

Finally, the `tasks` attribute is used to define the tasks that can be run. In
this case, we have a task called `default` that echoes the value of the
Expand All @@ -71,9 +84,9 @@ task default

Note that we don't have to specify the name of the Taskfile. Task will
automatically look for a file called `Taskfile.yml` (or any of Task's [supported
file names][supported-file-names]) in the current directory. Additionally, tasks
with the name `default` are special. They can also be run without specifying the
task name.
file names][supported-file-names], such as `Taskfile.hcl` or a plain
`Taskfile`) in the current directory. Additionally, tasks with the name
`default` are special. They can also be run without specifying the task name.

If you created a Taskfile in a different directory, you can run it by passing
the absolute or relative path to the directory as an argument using the `--dir`
Expand Down
7 changes: 4 additions & 3 deletions website/versioned_docs/version-latest/reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,10 @@ If `--` is given, all remaining arguments will be assigned to a special
| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/{T,t}askfile.{yml,yaml,hcl}` or `$HOME/{T,t}askfile`.
|
| `-i` | `--init` | `bool` | `false` | Creates a new `Taskfile.yml` in the current folder.
|
| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
Expand Down
2 changes: 1 addition & 1 deletion website/versioned_docs/version-latest/reference/package.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ strings (via stdin).

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.
Taskfile configuration (YAML or HCL) into an AST and store them in memory.

- [`ast.TaskfileGraph`] - Represents a set of Taskfiles and their dependencies
between one another.
Expand Down
6 changes: 4 additions & 2 deletions website/versioned_docs/version-latest/styleguide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,10 @@ sidebar_position: 11

# Style Guide

This is the official style guide for `Taskfile.yml` files. It provides basic
instructions for keeping your Taskfiles clean and familiar to other users.
This is the official style guide for `Taskfile.yml` files. Task also supports
Taskfiles written in HCL, but this guide focuses on the YAML format. It
provides basic instructions for keeping your Taskfiles clean and familiar to
other users.

This guide contains general guidelines, but they do not necessarily need to be
followed strictly. Feel free to disagree and do things differently if you need
Expand Down
20 changes: 16 additions & 4 deletions website/versioned_docs/version-latest/usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,16 @@ Task looks for files with the following names, in order of priority:
- `taskfile.dist.yml`
- `Taskfile.dist.yaml`
- `taskfile.dist.yaml`
- `Taskfile.hcl`
- `taskfile.hcl`
- `Taskfile`
- `taskfile`

The `.dist` variants allow projects to have one committed file (`.dist`) while
still allowing individual users to override the Taskfile by adding an additional
`Taskfile.yml` (which would be in your `.gitignore`).
`Taskfile.yml` (which would be in your `.gitignore`). YAML files are checked
before HCL or extensionless files. If both YAML and HCL Taskfiles are present,
the YAML file will be used.

### Running a Taskfile from a subdirectory

Expand Down Expand Up @@ -65,7 +71,8 @@ will be brought up.

If you call Task with the `--global` (alias `-g`) flag, it will look for your
home directory instead of your working directory. In short, Task will look for a
Taskfile that matches `$HOME/{T,t}askfile.{yml,yaml}` .
Taskfile that matches `$HOME/{T,t}askfile.{yml,yaml,hcl}` or
`$HOME/{T,t}askfile`.

This is useful to have automation that you can run from anywhere in your system!

Expand Down Expand Up @@ -97,14 +104,19 @@ tasks:
### Reading a Taskfile from stdin

Taskfile also supports reading from stdin. This is useful if you are generating
Taskfiles dynamically and don't want write them to disk. To tell task to read
Taskfiles dynamically and don't want write them to disk. To tell Task to read
from stdin, you must specify the `-t/--taskfile` flag with the special `-`
value. You may then pipe into Task as you would any other program:
value. You may then pipe into Task as you would any other program. Both YAML and
HCL content are supported and Task will attempt to detect the format
automatically:

```shell
task -t - <(cat ./Taskfile.yml)
# OR
cat ./Taskfile.yml | task -t -

# HCL content works too
cat ./Taskfile.hcl | task -t -
```

## Environment variables
Expand Down