+ Taskfiles can be written in YAML or HCL. By default Task looks for Taskfile.yml, Taskfile.yaml, Taskfile.hcl, or a plain Taskfile in your project.
+
Installation | Documentation | Twitter | Bluesky | Mastodon | Discord
diff --git a/internal/flags/flags.go b/internal/flags/flags.go index 7dd9e43d15..cb55ef02cf 100644 --- a/internal/flags/flags.go +++ b/internal/flags/flags.go @@ -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: diff --git a/website/docs/getting_started.mdx b/website/docs/getting_started.mdx index e79108d26d..605efc8614 100644 --- a/website/docs/getting_started.mdx +++ b/website/docs/getting_started.mdx @@ -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 @@ -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` diff --git a/website/docs/reference/cli.mdx b/website/docs/reference/cli.mdx index 55ab128f6e..0c1e368261 100644 --- a/website/docs/reference/cli.mdx +++ b/website/docs/reference/cli.mdx @@ -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. | diff --git a/website/docs/reference/package.mdx b/website/docs/reference/package.mdx index 4777f5df68..fd193bc5bb 100644 --- a/website/docs/reference/package.mdx +++ b/website/docs/reference/package.mdx @@ -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. diff --git a/website/docs/styleguide.mdx b/website/docs/styleguide.mdx index 1213e4a09f..aef2babf65 100644 --- a/website/docs/styleguide.mdx +++ b/website/docs/styleguide.mdx @@ -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 diff --git a/website/docs/usage.mdx b/website/docs/usage.mdx index 9590cf4f25..b0aa326b6b 100644 --- a/website/docs/usage.mdx +++ b/website/docs/usage.mdx @@ -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 @@ -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! @@ -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 diff --git a/website/versioned_docs/version-latest/getting_started.mdx b/website/versioned_docs/version-latest/getting_started.mdx index e79108d26d..605efc8614 100644 --- a/website/versioned_docs/version-latest/getting_started.mdx +++ b/website/versioned_docs/version-latest/getting_started.mdx @@ -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 @@ -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` diff --git a/website/versioned_docs/version-latest/reference/cli.mdx b/website/versioned_docs/version-latest/reference/cli.mdx index 55ab128f6e..b0b3dacbd6 100644 --- a/website/versioned_docs/version-latest/reference/cli.mdx +++ b/website/versioned_docs/version-latest/reference/cli.mdx @@ -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. | diff --git a/website/versioned_docs/version-latest/reference/package.mdx b/website/versioned_docs/version-latest/reference/package.mdx index 4777f5df68..fd193bc5bb 100644 --- a/website/versioned_docs/version-latest/reference/package.mdx +++ b/website/versioned_docs/version-latest/reference/package.mdx @@ -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. diff --git a/website/versioned_docs/version-latest/styleguide.mdx b/website/versioned_docs/version-latest/styleguide.mdx index 1213e4a09f..aef2babf65 100644 --- a/website/versioned_docs/version-latest/styleguide.mdx +++ b/website/versioned_docs/version-latest/styleguide.mdx @@ -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 diff --git a/website/versioned_docs/version-latest/usage.mdx b/website/versioned_docs/version-latest/usage.mdx index 9590cf4f25..b0aa326b6b 100644 --- a/website/versioned_docs/version-latest/usage.mdx +++ b/website/versioned_docs/version-latest/usage.mdx @@ -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 @@ -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! @@ -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