rayan/go-task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2026-06-30 08:04:28 +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

923
website/src/docs/changelog.md Normal file
View File

@@ -0,0 +1,923 @@
---
title: Changelog
outline: deep
---
# Changelog
## v3.44.1 - 2025-07-23
- Internal tasks will no longer be shown as suggestions since they cannot be
called (#2309, #2323 by @maxmzkrcensys)
- Fixed install script for some ARM platforms (#1516, #2291 by @trulede).
- Fixed a regression where fingerprinting was not working correctly if the path
to you Taskfile contained a space (#2321, #2322 by @pd93).
- Reverted a breaking change to `randInt` (#2312, #2316 by @pd93).
- Made new variables `TEST_NAME` and `TEST_DIR` available in fixture tests
(#2265 by @pd93).
## v3.44.0 - 2025-06-08
- Added `uuid`, `randInt` and `randIntN` template functions (#1346, #2225 by
@pd93).
- Added new `CLI_ARGS_LIST` array variable which contains the arguments passed
to Task after the `--` (the same as `CLI_ARGS`, but an array instead of a
string). (#2138, #2139, #2140 by @pd93).
- Added `toYaml` and `fromYaml` templating functions (#2217, #2219 by @pd93).
- Added `task` field the `--list --json` output (#2256 by @aleksandersh).
- Added the ability to
[pin included taskfiles](https://taskfile.dev/next/experiments/remote-taskfiles/#manual-checksum-pinning)
by specifying a checksum. This works with both local and remote Taskfiles
(#2222, #2223 by @pd93).
- When using the
[Remote Taskfiles experiment](https://github.com/go-task/task/issues/1317),
any credentials used in the URL will now be redacted in Task's output (#2100,
#2220 by @pd93).
- Fixed fuzzy suggestions not working when misspelling a task name (#2192, #2200
by @vmaerten).
- Fixed a bug where taskfiles in directories containing spaces created
directories in the wrong location (#2208, #2216 by @pd93).
- Added support for dual JSON schema files, allowing changes without affecting
the current schema. The current schemas will only be updated during releases.
(#2211 by @vmaerten).
- Improved fingerprint documentation by specifying that the method can be set at
the root level to apply to all tasks (#2233 by @vmaerten).
- Fixed some watcher regressions after #2048 (#2199, #2202, #2241, #2196 by
@wazazaby, #2271 by @andreynering).
## v3.43.3 - 2025-04-27
Reverted the changes made in #2113 and #2186 that affected the
`USER_WORKING_DIR` and built-in variables. This fixes #2206, #2195, #2207 and
#2208.
## v3.43.2 - 2025-04-21
- Fixed regresion of `CLI_ARGS` being exposed as the wrong type (#2190, #2191 by
@vmaerten).
## v3.43.1 - 2025-04-21
- Significant improvements were made to the watcher. We migrated from
[watcher](https://github.com/radovskyb/watcher) to
[fsnotify](https://github.com/fsnotify/fsnotify). The former library used
polling, which means Task had a high CPU usage when watching too many files.
`fsnotify` uses proper the APIs from each operating system to watch files,
which means a much better performance. The default interval changed from 5
seconds to 100 milliseconds, because now it configures the wait time for
duplicated events, instead of the polling time (#2048 by @andreynering, #1508,
#985, #1179).
- The [Map Variables experiment](https://github.com/go-task/task/issues/1585)
was made generally available so you can now
[define map variables in your Taskfiles!](https://taskfile.dev/usage/#variables)
(#1585, #1547, #2081 by @pd93).
- Wildcards can now
[match multiple tasks](https://taskfile.dev/usage/#wildcard-arguments) (#2072,
#2121 by @pd93).
- Added the ability to
[loop over the files specified by the `generates` keyword](https://taskfile.dev/usage/#looping-over-your-tasks-sources-or-generated-files).
This works the same way as looping over sources (#2151 by @sedyh).
- Added the ability to resolve variables when defining an include variable
(#2108, #2113 by @pd93).
- A few changes have been made to the
[Remote Taskfiles experiment](https://github.com/go-task/task/issues/1317)
(#1402, #2176 by @pd93):
- Cached files are now prioritized over remote ones.
- Added an `--expiry` flag which sets the TTL for a remote file cache. By
default the value will be 0 (caching disabled). If Task is running in
offline mode or fails to make a connection, it will fallback on the cache.
- `.taskrc` files can now be used from subdirectories and will be searched for
recursively up the file tree in the same way that Taskfiles are (#2159, #2166
by @pd93).
- The default taskfile (output when using the `--init` flag) is now an embedded
file in the binary instead of being stored in the code (#2112 by @pd93).
- Improved the way we report the Task version when using the `--version` flag or
<span v-pre>`{{.TASK_VERSION}}`</span> variable. This should now be more
consistent and easier for package maintainers to use (#2131 by @pd93).
- Fixed a bug where globstar (`**`) matching in `sources` only resolved the
first result (#2073, #2075 by @pd93).
- Fixed a bug where sorting tasks by "none" would use the default sorting
instead of leaving tasks in the order they were defined (#2124, #2125 by
@trulede).
- Fixed Fish completion on newer Fish versions (#2130 by @atusy).
- Fixed a bug where undefined/null variables resolved to an empty string instead
of `nil` (#1911, #2144 by @pd93).
- The `USER_WORKING_DIR` special now will now properly account for the `--dir`
(`-d`) flag, if given (#2102, #2103 by @jaynis, #2186 by @andreynering).
- Fix Fish completions when `--global` (`-g`) is given (#2134 by @atusy).
- Fixed variables not available when using `defer:` (#1909, #2173 by @vmaerten).
### Package API
- The [`Executor`](https://pkg.go.dev/github.com/go-task/task/v3#Executor) now
uses the functional options pattern (#2085, #2147, #2148 by @pd93).
- The functional options for the
[`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader)
and
[`taskfile.Snippet`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Snippet)
types no longer have the `Reader`/`Snippet` respective prefixes (#2148 by
@pd93).
- [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader)
no longer accepts a
[`taskfile.Node`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Node).
Instead nodes are passed directly into the
[`Reader.Read`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader.Read)
method (#2169 by @pd93).
- [`Reader.Read`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader.Read)
also now accepts a [`context.Context`](https://pkg.go.dev/context#Context)
(#2176 by @pd93).
## v3.42.1 - 2025-03-10
- Fixed a bug where some special variables caused a type error when used global
variables (#2106, #2107 by @pd93).
## v3.42.0 - 2025-03-08
- Made `--init` less verbose by default and respect `--silent` and `--verbose`
flags (#2009, #2011 by @HeCorr).
- `--init` now accepts a file name or directory as an argument (#2008, #2018 by
@HeCorr).
- Fix a bug where an HTTP node's location was being mutated incorrectly (#2007
by @jeongukjae).
- Fixed a bug where allowed values didn't work with dynamic var (#2032, #2033 by
@vmaerten).
- Use only the relevant checker (timestamp or checksum) to improve performance
(#2029, #2031 by @vmaerten).
- Print warnings when attempting to enable an inactive experiment or an active
experiment with an invalid value (#1979, #2049 by @pd93).
- Refactored the experiments package and added tests (#2049 by @pd93).
- Show allowed values when a variable with an enum is missing (#2027, #2052 by
@vmaerten).
- Refactored how snippets in error work and added tests (#2068 by @pd93).
- Fixed a bug where errors decoding commands were sometimes unhelpful (#2068 by
@pd93).
- Fixed a bug in the Taskfile schema where `defer` statements in the shorthand
`cmds` syntax were not considered valid (#2068 by @pd93).
- Refactored how task sorting functions work (#1798 by @pd93).
- Added a new `.taskrc.yml` (or `.taskrc.yaml`) file to let users enable
experiments (similar to `.env`) (#1982 by @vmaerten).
- Added new [Getting Started docs](https://taskfile.dev/getting-started) (#2086
by @pd93).
- Allow `matrix` to use references to other variables (#2065, #2069 by @pd93).
- Fixed a bug where, when a dynamic variable is provided, even if it is not
used, all other variables become unavailable in the templating system within
the include (#2092 by @vmaerten).
### Package API
Unlike our CLI tool,
[Task's package API is not currently stable](https://taskfile.dev/reference/package).
In an effort to ease the pain of breaking changes for our users, we will be
providing changelogs for our package API going forwards. The hope is that these
changes will provide a better long-term experience for our users and allow to
stabilize the API in the future. #121 now tracks this piece of work.
- Bumped the minimum required Go version to 1.23 (#2059 by @pd93).
- [`task.InitTaskfile`](https://pkg.go.dev/github.com/go-task/task/v3#InitTaskfile)
(#2011, ff8c913 by @HeCorr and @pd93)
- No longer accepts an `io.Writer` (output is now the caller's
responsibility).
- The path argument can now be a filename OR a directory.
- The function now returns the full path of the generated file.
- [`TaskfileDecodeError.WithFileInfo`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskfileDecodeError.WithFileInfo)
now accepts a string instead of the arguments required to generate a snippet
(#2068 by @pd93).
- The caller is now expected to create the snippet themselves (see below).
- [`TaskfileSnippet`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Snippet)
and related code moved from the `errors` package to the `taskfile` package
(#2068 by @pd93).
- Renamed `TaskMissingRequiredVars` to
[`TaskMissingRequiredVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskMissingRequiredVarsError)
(#2052 by @vmaerten).
- Renamed `TaskNotAllowedVars` to
[`TaskNotAllowedVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskNotAllowedVarsError)
(#2052 by @vmaerten).
- The
[`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader)
is now constructed using the functional options pattern (#2082 by @pd93).
- Removed our internal `logger.Logger` from the entire `taskfile` package (#2082
by @pd93).
- Users are now expected to pass a custom debug/prompt functions into
[`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader)
if they want this functionality by using the new
[`WithDebugFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithDebugFunc)
and
[`WithPromptFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithPromptFunc)
functional options.
- Remove `Range` functions in the `taskfile/ast` package in favour of new
iterator functions (#1798 by @pd93).
- `ast.Call` was moved from the `taskfile/ast` package to the main `task`
package (#2084 by @pd93).
- `ast.Tasks.FindMatchingTasks` was moved from the `taskfile/ast` package to the
`task.Executor.FindMatchingTasks` in the main `task` package (#2084 by @pd93).
- The `Compiler` and its `GetVariables` and `FastGetVariables` methods were
moved from the `internal/compiler` package to the main `task` package (#2084
by @pd93).
## v3.41.0 - 2025-01-18
- Fixed an issue where dynamic variables were not properly logged in verbose
mode (#1920, #1921 by @mgbowman).
- Support `silent` for defer statements (#1877, #1879 by @danilobuerger).
- Added an option to exclude some tasks from being included (#1859 by
@vmaerten).
- Fixed an issue where a required variable was incorrectly handled in a template
function (#1950, #1962 by @vmaerten).
- Expose a new `TASK_DIR` special variable, which will contain the absolute path
of task directory. (#1959, #1961 by @vmaerten).
- Fixed fatal bugs that caused concurrent map writes (#1605, #1972, #1974 by
@pd93, @GrahamDennis and @trim21).
- Refactored internal ordered map implementation to use
[github.com/elliotchance/orderedmap](https://github.com/elliotchance/orderedmap)
(#1797 by @pd93).
- Fixed a bug where variables defined at the task level were being ignored in
the `requires` section. (#1960, #1955, #1768 by @vmaerten and @mokeko)
- The `CHECKSUM` and `TIMESTAMP` variables are now accessible within `cmds`
(#1872 by @niklasr22).
- Updated [installation docs](https://taskfile.dev/installation) and added pip
installation method (#935, #1989 by @pd93).
- Fixed a bug where dynamic variables could not access environment variables
(#630, #1869 by @rohm1 and @pd93).
- Disable version check for use as an external library (#1938 by @leaanthony).
## v3.40.1 - 2024-12-06
- Fixed a security issue in `git-urls` by switching to the maintained fork
`chainguard-dev/git-urls` (#1917 by @AlekSi).
- Added missing `platforms` property to `cmds` that use `for` (#1915 by
@dkarter).
- Added misspell linter to check for misspelled English words (#1883 by
@christiandins).
## v3.40.0 - 2024-11-05
- Fixed output of some functions (e.g. `splitArgs`/`splitLines`) not working in
for loops (#1822, #1823 by @stawii).
- Added a new `TASK_OFFLINE` environment variable to configure the `--offline`
flag and expose it as a special variable in the templating system (#1470,
#1716 by @vmaerten and @pd93).
- Fixed a bug where multiple remote includes caused all prompts to display
without waiting for user input (#1832, #1833 by @vmaerten and @pd93).
- When using the
"[Remote Taskfiles](https://taskfile.dev/experiments/remote-taskfiles/)".
experiment, you can now include Taskfiles from Git repositories (#1652 by
@vmaerten).
- Improved the error message when a dotenv file cannot be parsed (#1842 by
@pbitty).
- Fix issue with directory when using the remote experiment (#1757 by @pbitty).
- Fixed an issue where a special variable was used in combination with a dotenv
file (#1232, #1810 by @vmaerten).
- Refactor the way Task reads Taskfiles to improve readability (#1771 by
@pbitty).
- Added a new option to ensure variable is within the list of values (#1827 by
@vmaerten).
- Allow multiple prompts to be specified for a task (#1861, #1866 by @mfbmina).
- Added new template function: `numCPU`, which returns the number of logical
CPUs usable (#1890, #1887 by @Amoghrd).
- Fixed a bug where non-nil, empty dynamic variables are returned as an empty
interface (#1903, #1904 by @pd93).
## v3.39.2 - 2024-09-19
- Fix dynamic variables not working properly for a defer: statement (#1803,
#1818 by @vmaerten).
## v3.39.1 - 2024-09-18
- Added Renovate configuration to automatically create PRs to keep dependencies
up to date (#1783 by @vmaerten).
- Fixed a bug where the help was displayed twice (#1805, #1806 by @vmaerten).
- Fixed a bug where ZSH and PowerShell completions did not work when using the
recommended method. (#1813, #1809 by @vmaerten and @shirayu)
- Fix variables not working properly for a `defer:` statement (#1803, #1814 by
@vmaerten and @andreynering).
## v3.39.0 - 2024-09-07
- Added
[Env Precedence Experiment](https://taskfile.dev/experiments/env-precedence)
(#1038, #1633 by @vmaerten).
- Added a CI lint job to ensure that the docs are updated correctly (#1719 by
@vmaerten).
- Updated minimum required Go version to 1.22 (#1758 by @pd93).
- Expose a new `EXIT_CODE` special variable on `defer:` when a command finishes
with a non-zero exit code (#1484, #1762 by @dorimon-1 and @andreynering).
- Expose a new `ALIAS` special variable, which will contain the alias used to
call the current task. Falls back to the task name. (#1764 by @DanStory).
- Fixed `TASK_REMOTE_DIR` environment variable not working when the path was
absolute. (#1715 by @vmaerten).
- Added an option to declare an included Taskfile as flattened (#1704 by
@vmaerten).
- Added a new
[`--completion` flag](https://taskfile.dev/installation/#setup-completions) to
output completion scripts for various shells (#293, #1157 by @pd93).
- This is now the preferred way to install completions.
- The completion scripts in the `completion` directory
[are now deprecated](https://taskfile.dev/deprecations/completion-scripts/).
- Added the ability to
[loop over a matrix of values](https://taskfile.dev/usage/#looping-over-a-matrix)
(#1766, #1767, #1784 by @pd93).
- Fixed a bug in fish completion where aliases were not displayed (#1781, #1782
by @vmaerten).
- Fixed panic when having a flattened included Taskfile that contains a
`default` task (#1777, #1778 by @vmaerten).
- Optimized file existence checks for remote Taskfiles (#1713 by @vmaerten).
## v3.38.0 - 2024-06-30
- Added `TASK_EXE` special variable (#1616, #1624 by @pd93 and @andreynering).
- Some YAML parsing errors will now show in a more user friendly way (#1619 by
@pd93).
- Prefixed outputs will now be colorized by default (#1572 by
@AlexanderArvidsson)
- [References](https://taskfile.dev/usage/#referencing-other-variables) are now
generally available (no experiments required) (#1654 by @pd93).
- Templating functions can now be used in references (#1645, #1654 by @pd93).
- Added a new
[templating reference page](https://taskfile.dev/reference/templating/) to the
documentation (#1614, #1653 by @pd93).
- If using the
[Map Variables experiment (1)](https://taskfile.dev/experiments/map-variables/?proposal=1),
references are available by
[prefixing a string with a `#`](https://taskfile.dev/experiments/map-variables/?proposal=1#references)
(#1654 by @pd93).
- If using the
[Map Variables experiment (2)](https://taskfile.dev/experiments/map-variables/?proposal=2),
the `yaml` and `json` keys are no longer available (#1654 by @pd93).
- Added a new `TASK_REMOTE_DIR` environment variable to configure where cached
remote Taskfiles are stored (#1661 by @vmaerten).
- Added a new `--clear-cache` flag to clear the cache of remote Taskfiles (#1639
by @vmaerten).
- Improved the readability of cached remote Taskfile filenames (#1636 by
@vmaerten).
- Starting releasing a binary for the `riscv64` architecture on Linux (#1699 by
@mengzhuo).
- Added `CLI_SILENT` and `CLI_VERBOSE` variables (#1480, #1669 by @Vince-Smith).
- Fixed a couple of bugs with the `prompt:` feature (#1657 by @pd93).
- Fixed JSON Schema to disallow invalid properties (#1657 by @pd93).
- Fixed version checks not working as intended (#872, #1663 by @vmaerten).
- Fixed a bug where included tasks were run multiple times even if `run: once`
was set (#852, #1655 by @pd93).
- Fixed some bugs related to column formatting in the terminal (#1350, #1637,
#1656 by @vmaerten).
## v3.37.2 - 2024-05-12
- Fixed a bug where an empty Taskfile would cause a panic (#1648 by @pd93).
- Fixed a bug where includes Taskfile variable were not being merged correctly
(#1643, #1649 by @pd93).
## v3.37.1 - 2024-05-09
- Fix bug where non-string values (numbers, bools) added to `env:` weren't been
correctly exported (#1640, #1641 by @vmaerten and @andreynering).
## v3.37.0 - 2024-05-08
- Released the
[Any Variables experiment](https://taskfile.dev/blog/any-variables), but
[_without support for maps_](https://github.com/go-task/task/issues/1415#issuecomment-2044756925)
(#1415, #1547 by @pd93).
- Refactored how Task reads, parses and merges Taskfiles using a DAG (#1563,
#1607 by @pd93).
- Fix a bug which stopped tasks from using `stdin` as input (#1593, #1623 by
@pd93).
- Fix error when a file or directory in the project contained a special char
like `&`, `(` or `)` (#1551, #1584 by @andreynering).
- Added alias `q` for template function `shellQuote` (#1601, #1603 by @vergenzt)
- Added support for `~` on ZSH completions (#1613 by @jwater7).
- Added the ability to pass variables by reference using Go template syntax when
the
[Map Variables experiment](https://taskfile.dev/experiments/map-variables/) is
enabled (#1612 by @pd93).
- Added support for environment variables in the templating engine in `includes`
(#1610 by @vmaerten).
## v3.36.0 - 2024-04-08
- Added support for
[looping over dependencies](https://taskfile.dev/usage/#looping-over-dependencies)
(#1299, #1541 by @pd93).
- When using the
"[Remote Taskfiles](https://taskfile.dev/experiments/remote-taskfiles/)"
experiment, you are now able to use
[remote Taskfiles as your entrypoint](https://taskfile.dev/experiments/remote-taskfiles/#root-remote-taskfiles).
- `includes` in remote Taskfiles will now also resolve correctly (#1347 by
@pd93).
- When using the
"[Any Variables](https://taskfile.dev/experiments/any-variables/)"
experiments, templating is now supported in collection-type variables (#1477,
#1511, #1526 by @pd93).
- Fixed a bug where variables being passed to an included Taskfile were not
available when defining global variables (#1503, #1533 by @pd93).
- Improved support to customized colors by allowing 8-bit colors and multiple
ANSI attributes (#1576 by @pd93).
## v3.35.1 - 2024-03-04
- Fixed a bug where the `TASKFILE_DIR` variable was sometimes incorrect (#1522,
#1523 by @pd93).
- Added a new `TASKFILE` special variable that holds the root Taskfile path
(#1523 by @pd93).
- Fixed various issues related to running a Taskfile from a subdirectory (#1529,
#1530 by @pd93).
## v3.35.0 - 2024-02-28
- Added support for
[wildcards in task names](https://taskfile.dev/usage/#wildcard-arguments)
(#836, #1489 by @pd93).
- Added the ability to
[run Taskfiles via stdin](https://taskfile.dev/usage/#reading-a-taskfile-from-stdin)
(#655, #1483 by @pd93).
- Bumped minimum Go version to 1.21 (#1500 by @pd93).
- Fixed bug related to the `--list` flag (#1509, #1512 by @pd93, #1514, #1520 by
@pd93).
- Add mention on the documentation to the fact that the variable declaration
order is respected (#1510 by @kirkrodrigues).
- Improved style guide docs (#1495 by @iwittkau).
- Removed duplicated entry for `requires` on the API docs (#1491 by
@teatimeguest).
## v3.34.1 - 2024-01-27
- Fixed prompt regression on
[Remote Taskfiles experiment](https://taskfile.dev/experiments/remote-taskfiles/)
(#1486, #1487 by @pd93).
## v3.34.0 - 2024-01-25
- Removed support for `version: 2` schemas. See the
[deprecation notice on our website](https://taskfile.dev/deprecations/version-2-schema)
(#1197, #1447 by @pd93).
- Fixed a couple of issues in the JSON Schema + added a CI step to ensure it's
correct (#1471, #1474, #1476 by @sirosen).
- Added
[Any Variables experiment proposal 2](https://taskfile.dev/experiments/any-variables/?proposal=2)
(#1415, #1444 by @pd93).
- Updated the experiments and deprecations documentation format (#1445 by
@pd93).
- Added new template function: `spew`, which can be used to print variables for
debugging purposes (#1452 by @pd93).
- Added new template function: `merge`, which can be used to merge any number of
map variables (#1438, #1464 by @pd93).
- Small change on the API when using as a library: `call.Direct` became
`call.Indirect` (#1459 by @pd93).
- Refactored the public `read` and `taskfile` packages and introduced
`taskfile/ast` (#1450 by @pd93).
- `ast.IncludedTaskfiles` renamed to `ast.Includes` and `orderedmap` package
renamed to `omap` plus some internal refactor work (#1456 by @pd93).
- Fix zsh completion script to allow lowercase `taskfile` file names (#1482 by
@xontab).
- Improvements on how we check the Taskfile version (#1465 by @pd93).
- Added a new `ROOT_TASKFILE` special variable (#1468, #1469 by @pd93).
- Fix experiment flags in `.env` when the `--dir` or `--taskfile` flags were
used (#1478 by @pd93).
## v3.33.1 - 2023-12-21
- Added support for looping over map variables with the
[Any Variables experiment](https://taskfile.dev/experiments/any-variables)
enabled (#1435, #1437 by @pd93).
- Fixed a bug where dynamic variables were causing errors during fast
compilation (#1435, #1437 by @pd93)
## v3.33.0 - 2023-12-20
- Added
[Any Variables experiment](https://taskfile.dev/experiments/any-variables)
(#1415, #1421 by @pd93).
- Updated Docusaurus to v3 (#1432 by @pd93).
- Added `aliases` to `--json` flag output (#1430, #1431 by @pd93).
- Added new `CLI_FORCE` special variable containing whether the `--force` or
`--force-all` flags were set (#1412, #1434 by @pd93).
## v3.32.0 - 2023-11-29
- Added ability to exclude some files from `sources:` by using `exclude:` (#225,
#1324 by @pd93 and @andreynering).
- The
[Remote Taskfiles experiment](https://taskfile.dev/experiments/remote-taskfiles)
now prefers remote files over cached ones by default (#1317, #1345 by @pd93).
variable prefix and `^` command prefix (#642, #644, #645).
- Add support for `.yaml` extension (as an alternative to `.yml`). This was
requested multiple times throughout the years. Enjoy! (#183, #184, #369, #584,
#621).
- Fixed error when computing a variable when the task directory do not exist yet
(#481, #579).
## v3.9.2 - 2021-12-02
- Upgrade [mvdan/sh](https://github.com/mvdan/sh) which contains a fix a for a
important regression on Windows (#619,
[mvdan/sh#768](https://github.com/mvdan/sh/issues/768),
[mvdan/sh#769](https://github.com/mvdan/sh/pull/769)).
## v3.9.1 - 2021-11-28
- Add logging in verbose mode for when a task starts and finishes (#533, #588).
- Fix an issue with preconditions and context errors (#597, #598).
- Quote each <span v-pre>`{{.CLI_ARGS}}`</span> argument to prevent one with
spaces to become many (#613).
- Fix nil pointer when `cmd:` was left empty (#612, #614).
- Upgrade [mvdan/sh](https://github.com/mvdan/sh) which contains two relevant
fixes:
- Fix quote of empty strings in `shellQuote` (#609,
[mvdan/sh#763](https://github.com/mvdan/sh/issues/763)).
- Fix issue of wrong environment variable being picked when there's another
very similar one (#586,
[mvdan/sh#745](https://github.com/mvdan/sh/pull/745)).
- Install shell completions automatically when installing via Homebrew (#264,
#592,
[go-task/homebrew-tap#2](https://github.com/go-task/homebrew-tap/pull/2)).
## v3.9.0 - 2021-10-02
- A new `shellQuote` function was added to the template system
(<span v-pre>`{{shellQuote "a string"}}`</span>) to ensure a string is safe
for use in shell ([mvdan/sh#727](https://github.com/mvdan/sh/pull/727),
[mvdan/sh#737](https://github.com/mvdan/sh/pull/737),
[Documentation](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote))
- In this version [mvdan.cc/sh](https://github.com/mvdan/sh) was upgraded with
some small fixes and features
- The `read -p` flag is now supported (#314,
[mvdan/sh#551](https://github.com/mvdan/sh/issues/551),
[mvdan/sh#772](https://github.com/mvdan/sh/pull/722))
- The `pwd -P` and `pwd -L` flags are now supported (#553,
[mvdan/sh#724](https://github.com/mvdan/sh/issues/724),
[mvdan/sh#728](https://github.com/mvdan/sh/pull/728))
- The `$GID` environment variable is now correctly being set (#561,
[mvdan/sh#723](https://github.com/mvdan/sh/pull/723))
## v3.8.0 - 2021-09-26
- Add `interactive: true` setting to improve support for interactive CLI apps
(#217, #563).
- Fix some `nil` errors (#534, #573).
- Add ability to declare an included Taskfile as optional (#519, #552).
- Add support for including Taskfiles in the home directory by using `~` (#539,
#557).
## v3.7.3 - 2021-09-04
- Add official support to Apple M1 (#564, #567).
- Our [official Homebrew tap](https://github.com/go-task/homebrew-tap) will
support more platforms, including Apple M1
## v3.7.0 - 2021-07-31
- Add `run:` setting to control if tasks should run multiple times or not.
Available options are `always` (the default), `when_changed` (if a variable
modified the task) and `once` (run only once no matter what). This is a long
time requested feature. Enjoy! (#53, #359).
## v3.6.0 - 2021-07-10
- Allow using both `sources:` and `status:` in the same task (#411, #427, #477).
- Small optimization and bug fix: don't compute variables if not needed for
`dotenv:` (#517).
## v3.5.0 - 2021-07-04
- Add support for interpolation in `dotenv:` (#433, #434, #453).
## v3.4.3 - 2021-05-30
- Add support for the `NO_COLOR` environment variable. (#459,
[fatih/color#137](https://github.com/fatih/color/pull/137)).
- Fix bug where sources were not considering the right directory in `--watch`
mode (#484, #485).
## v3.4.2 - 2021-04-23
- On watch, report which file failed to read (#472).
- Do not try to catch SIGKILL signal, which are not actually possible (#476).
- Improve version reporting when building Task from source using Go Modules
(#462, #473).
## v3.4.1 - 2021-04-17
- Improve error reporting when parsing YAML: in some situations where you would
just see an generic error, you'll now see the actual error with more detail:
the YAML line the failed to parse, for example (#467).
- A JSON Schema was published [here](https://json.schemastore.org/taskfile.json)
and is automatically being used by some editors like Visual Studio Code
(#135).
- Print task name before the command in the log output (#398).
## v3.3.0 - 2021-03-20
- Add support for delegating CLI arguments to commands with `--` and a special
`CLI_ARGS` variable (#327).
- Add a `--concurrency` (alias `-C`) flag, to limit the number of tasks that run
concurrently. This is useful for heavy workloads. (#345).
## v3.2.2 - 2021-01-12
- Improve performance of `--list` and `--summary` by skipping running shell
variables for these flags (#332).
- Fixed a bug where an environment in a Taskfile was not always overridable by
the system environment (#425).
- Fixed environment from .env files not being available as variables (#379).
- The install script is now working for ARM platforms (#428).
## v3.2.1 - 2021-01-09
- Fixed some bugs and regressions regarding dynamic variables and directories
(#426).
- The [slim-sprig](https://github.com/go-task/slim-sprig) package was updated
with the upstream [sprig](https://github.com/Masterminds/sprig).
## v3.2.0 - 2021-01-07
- Fix the `.task` directory being created in the task directory instead of the
Taskfile directory (#247).
- Fix a bug where dynamic variables (those declared with `sh:`) were not running
in the task directory when the task has a custom dir or it was in an included
Taskfile (#384).
- The watch feature (via the `--watch` flag) got a few different bug fixes and
should be more stable now (#423, #365).
## v3.1.0 - 2021-01-03
- Fix a bug when the checksum up-to-date resolution is used by a task with a
custom `label:` attribute (#412).
- Starting from this release, we're releasing official ARMv6 and ARM64 binaries
for Linux (#375, #418).
- Task now respects the order of declaration of included Taskfiles when
evaluating variables declaring by them (#393).
- `set -e` is now automatically set on every command. This was done to fix an
issue where multiline string commands wouldn't really fail unless the sentence
was in the last line (#403).
## v3.0.1 - 2020-12-26
- Allow use as a library by moving the required packages out of the `internal`
directory (#358).
- Do not error if a specified dotenv file does not exist (#378, #385).
- Fix panic when you have empty tasks in your Taskfile (#338, #362).
## v3.0.0 - 2020-08-16
- On `v3`, all CLI variables will be considered global variables (#336, #341)
- Add support to `.env` like files (#324, #356).
- Add `label:` to task so you can override the task name in the logs (#321,
#337).
- Refactor how variables work on version 3 (#311).
- Disallow `expansions` on v3 since it has no effect.
- `Taskvars.yml` is not automatically included anymore.
- `Taskfile_{{OS}}.yml` is not automatically included anymore.
- Allow interpolation on `includes`, so you can manually include a Taskfile
based on operation system, for example.
- Expose `.TASK` variable in templates with the task name (#252).
- Implement short task syntax (#194, #240).
- Added option to make included Taskfile run commands on its own directory
(#260, #144)
- Taskfiles in version 1 are not supported anymore (#237).
- Added global `method:` option. With this option, you can set a default method
to all tasks in a Taskfile (#246).
- Changed default method from `timestamp` to `checksum` (#246).
- New magic variables are now available when using `status:`: `.TIMESTAMP` which
contains the greatest modification date from the files listed in `sources:`,
and `.CHECKSUM`, which contains a checksum of all files listed in `status:`.
This is useful for manual checking when using external, or even remote,
artifacts when using `status:` (#216).
- We're now using [slim-sprig](https://github.com/go-task/slim-sprig) instead of
[sprig](https://github.com/Masterminds/sprig), which allowed a file size
reduction of about 22% (#219).
- We now use some colors on Task output to better distinguish message types -
commands are green, errors are red, etc (#207).
## v2.8.1 - 2020-05-20
- Fix error code for the `--help` flag (#300, #330).
- Print version to stdout instead of stderr (#299, #329).
- Suppress `context` errors when using the `--watch` flag (#313, #317).
- Support templating on description (#276, #283).
## v2.8.0 - 2019-12-07
- Add `--parallel` flag (alias `-p`) to run tasks given by the command line in
parallel (#266).
- Fixed bug where calling the `task` CLI only informing global vars would not
execute the `default` task.
- Add ability to silent all tasks by adding `silent: true` a the root of the
Taskfile.
## v2.7.1 - 2019-11-10
- Fix error being raised when `exit 0` was called (#251).
## v2.7.0 - 2019-09-22
- Fixed panic bug when assigning a global variable (#229, #243).
- A task with `method: checksum` will now re-run if generated files are deleted
(#228, #238).
## v2.6.0 - 2019-07-21
- Fixed some bugs regarding minor version checks on `version:`.
- Add `preconditions:` to task (#205).
- Create directory informed on `dir:` if it doesn't exist (#209, #211).
- We now have a `--taskfile` flag (alias `-t`), which can be used to run another
Taskfile (other than the default `Taskfile.yml`) (#221).
- It's now possible to install Task using Homebrew on Linux
([go-task/homebrew-tap#1](https://github.com/go-task/homebrew-tap/pull/1)).
## v2.5.2 - 2019-05-11
- Reverted YAML upgrade due issues with CRLF on Windows (#201,
[go-yaml/yaml#450](https://github.com/go-yaml/yaml/issues/450)).
- Allow setting global variables through the CLI (#192).
## 2.5.1 - 2019-04-27
- Fixed some issues with interactive command line tools, where sometimes the
output were not being shown, and similar issues (#114, #190, #200).
- Upgraded [go-yaml/yaml](https://github.com/go-yaml/yaml) from v2 to v3.
## v2.5.0 - 2019-03-16
- We moved from the taskfile.org domain to the new fancy taskfile.dev domain.
While stuff is being redirected, we strongly recommend to everyone that use
[this install script](https://taskfile.dev/#/installation?id=install-script)
to use the new taskfile.dev domain on scripts from now on.
- Fixed to the ZSH completion (#182).
- Add
[`--summary` flag along with `summary:` task attribute](https://taskfile.org/#/usage?id=display-summary-of-task)
(#180).
## v2.4.0 - 2019-02-21
- Allow calling a task of the root Taskfile from an included Taskfile by
prefixing it with `:` (#161, #172).
- Add flag to override the `output` option (#173).
- Fix bug where Task was persisting the new checksum on the disk when the Dry
Mode is enabled (#166).
- Fix file timestamp issue when the file name has spaces (#176).
- Mitigating path expanding issues on Windows (#170).
## v2.3.0 - 2019-01-02
- On Windows, Task can now be installed using [Scoop](https://scoop.sh/) (#152).
- Fixed issue with file/directory globing (#153).
- Added ability to globally set environment variables (#138, #159).
## v2.2.1 - 2018-12-09
- This repository now uses Go Modules (#143). We'll still keep the `vendor`
directory in sync for some time, though;
- Fixing a bug when the Taskfile has no tasks but includes another Taskfile
(#150);
- Fix a bug when calling another task or a dependency in an included Taskfile
(#151).
## v2.2.0 - 2018-10-25
- Added support for
[including other Taskfiles](https://taskfile.org/#/usage?id=including-other-taskfiles)
(#98)
- This should be considered experimental. For now, only including local files
is supported, but support for including remote Taskfiles is being discussed.
If you have any feedback, please comment on #98.
- Task now have a dedicated documentation site: https://taskfile.org
- Thanks to [Docsify](https://docsify.js.org/) for making this pretty easy. To
check the source code, just take a look at the
[docs](https://github.com/go-task/task/tree/main/docs) directory of this
repository. Contributions to the documentation is really appreciated.
## v2.1.1 - 2018-09-17
- Fix suggestion to use `task --init` not being shown anymore (when a
`Taskfile.yml` is not found)
- Fix error when using checksum method and no file exists for a source glob
(#131)
- Fix signal handling when the `--watch` flag is given (#132)
## v2.1.0 - 2018-08-19
- Add a `ignore_error` option to task and command (#123)
- Add a dry run mode (`--dry` flag) (#126)
## v2.0.3 - 2018-06-24
- Expand environment variables on "dir", "sources" and "generates" (#116)
- Fix YAML merging syntax (#112)
- Add ZSH completion (#111)
- Implement new `output` option. Please check out the
[documentation](https://github.com/go-task/task#output-syntax)
## v2.0.2 - 2018-05-01
- Fix merging of YAML anchors (#112)
## v2.0.1 - 2018-03-11
- Fixes panic on `task --list`
## v2.0.0 - 2018-03-08
Version 2.0.0 is here, with a new Taskfile format.
Please, make sure to read the
[Taskfile versions](https://github.com/go-task/task/blob/main/TASKFILE_VERSIONS.md)
document, since it describes in depth what changed for this version.
- New Taskfile version 2 (#77)
- Possibility to have global variables in the `Taskfile.yml` instead of
`Taskvars.yml` (#66)
- Small improvements and fixes
## v1.4.4 - 2017-11-19
- Handle SIGINT and SIGTERM (#75);
- List: print message with there's no task with description;
- Expand home dir ("~" symbol) on paths (#74);
- Add Snap as an installation method;
- Move examples to its own repo;
- Watch: also walk on tasks called on on "cmds", and not only on "deps";
- Print logs to stderr instead of stdout (#68);
- Remove deprecated `set` keyword;
- Add checksum based status check, alternative to timestamp based.
## v1.4.3 - 2017-09-07
- Allow assigning variables to tasks at run time via CLI (#33)
- Added support for multiline variables from sh (#64)
- Fixes env: remove square braces and evaluate shell (#62)
- Watch: change watch library and few fixes and improvements
- When use watching, cancel and restart long running process on file change (#59
and #60)
## v1.4.2 - 2017-07-30
- Flag to set directory of execution
- Always echo command if is verbose mode
- Add silent mode to disable echoing of commands
- Fixes and improvements of variables (#56)
## v1.4.1 - 2017-07-15
- Allow use of YAML for dynamic variables instead of $ prefix
- `VAR: {sh: echo Hello}` instead of `VAR: $echo Hello`
- Add `--list` (or `-l`) flag to print existing tasks
- OS specific Taskvars file (e.g. `Taskvars_windows.yml`, `Taskvars_linux.yml`,
etc)
- Consider task up-to-date on equal timestamps (#49)
- Allow absolute path in generates section (#48)
- Bugfix: allow templating when calling deps (#42)
- Fix panic for invalid task in cyclic dep detection
- Better error output for dynamic variables in Taskvars.yml (#41)
- Allow template evaluation in parameters
## v1.4.0 - 2017-07-06
- Cache dynamic variables
- Add verbose mode (`-v` flag)
- Support to task parameters (overriding vars) (#31) (#32)
- Print command, also when "set:" is specified (#35)
- Improve task command help text (#35)
## v1.3.1 - 2017-06-14
- Fix glob not working on commands (#28)
- Add ExeExt template function
- Add `--init` flag to create a new Taskfile
- Add status option to prevent task from running (#27)
- Allow interpolation on `generates` and `sources` attributes (#26)
## v1.3.0 - 2017-04-24
- Migrate from os/exec.Cmd to a native Go sh/bash interpreter
- This is a potentially breaking change if you use Windows.
- Now, `cmd` is not used anymore on Windows. Always use Bash-like syntax for
your commands, even on Windows.
- Add "ToSlash" and "FromSlash" to template functions
- Use functions defined on github.com/Masterminds/sprig
- Do not redirect stdin while running variables commands
- Using `context` and `errgroup` packages (this will make other tasks to be
cancelled, if one returned an error)
## v1.2.0 - 2017-04-02
- More tests and Travis integration
- Watch a task (experimental)
- Possibility to call another task
- Fix "=" not being recognized in variables/environment variables
- Tasks can now have a description, and help will print them (#10)
- Task dependencies now run concurrently
- Support for a default task (#16)
## v1.1.0 - 2017-03-08
- Support for YAML, TOML and JSON (#1)
- Support running command in another directory (#4)
- `--force` or `-f` flag to force execution of task even when it's up-to-date
- Detection of cyclic dependencies (#5)
- Support for variables (#6, #9, #14)
- Operation System specific commands and variables (#13)
## v1.0.0 - 2017-02-28
- Add LICENSE file

41
website/src/docs/community.md Normal file
View File

@@ -0,0 +1,41 @@
---
title: Community
description:
Task community contributions, installation methods, and integrations
maintained by third parties
outline: deep
---
# Community
Some of the work to improve the Task ecosystem is done by the community, be it
installation methods or integrations with code editor. I (the author) am
thankful for everyone that helps me to improve the overall experience.
## Integrations
Many of our integrations are contributed and maintained by the community. You
can view the full list of community integrations
[here](./integrations.md#community-integrations).
## Installation methods
Some installation methods are maintained by third party:
- [GitHub Actions](https://github.com/arduino/setup-task) by @arduino
- [AUR](https://aur.archlinux.org/packages/go-task-bin) by @carlsmedstad
- [Scoop](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json)
- [Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/)
- [NixOS](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/tools/go-task/default.nix)
- [Conda](https://github.com/conda-forge/go-task-feedstock/)
## More
Also, thanks for all the
[code contributors](https://github.com/go-task/task/graphs/contributors),
[financial contributors](https://opencollective.com/task), all those who
[reported bugs](https://github.com/go-task/task/issues?q=is%3Aissue) and
[answered questions](https://github.com/go-task/task/discussions).
If you know something that is missing in this document, please submit a pull
request.

179
website/src/docs/contributing.md Normal file
View File

@@ -0,0 +1,179 @@
---
title: Contributing
description:
Comprehensive guide for contributing to the Task project, including setup,
development, testing, and submitting PRs
outline: deep
---
# Contributing
Contributions to Task are very welcome, but we ask that you read this document
before submitting a PR.
::: info
This document applies to the core [Task][task] repository _and_ [Task for Visual
Studio Code][vscode-task].
:::
## Before you start
- **Check existing work** - Is there an existing PR? Are there issues discussing
the feature/change you want to make? Please make sure you consider/address
these discussions in your work.
- **Backwards compatibility** - Will your change break existing Taskfiles? It is
much more likely that your change will merged if it backwards compatible. Is
there an approach you can take that maintains this compatibility? If not,
consider opening an issue first so that API changes can be discussed before
you invest your time into a PR.
- **Experiments** - If there is no way to make your change backward compatible
then there is a procedure to introduce breaking changes into minor versions.
We call these "[experiments](./experiments/index.md)". If you're intending to work on
an experiment, then please read the
[experiments workflow](./experiments/index.md#workflow) document carefully and submit a
proposal first.
## 1. Setup
- **Go** - Task is written in [Go][go]. We always support the latest two major
Go versions, so make sure your version is recent enough.
- **Node.js** - [Node.js][nodejs] is used to host Task's documentation server
and is required if you want to run this server locally. It is also required if
you want to contribute to the Visual Studio Code extension.
- **Pnpm** - [Pnpm][pnpm] is the Node.js package manager used by Task.
## 2. Making changes
- **Code style** - Try to maintain the existing code style where possible. Go
code should be formatted and linted by [`golangci-lint`][golangci-lint]. This
wraps the [`gofumpt`][gofumpt] and [`gci`][gci] formatters and a number of
linters. We recommend that you take a look at the [golangci-lint
docs][golangci-lint-docs] for a guide on how to setup your editor to
auto-format your code. Any Markdown or TypeScript files should be formatted
and linted by [Prettier][prettier]. This style is enforced by our CI to ensure
that we have a consistent style across the project. You can use the
`task lint` command to lint the code locally and the `task lint:fix` command
to try to automatically fix any issues that are found. You can also use the
`task fmt` command to auto-format the files if your editor doesn't do it for
you.
- **Documentation** - Ensure that you add/update any relevant documentation. See
the [updating documentation](#updating-documentation) section below.
- **Tests** - Ensure that you add/update any relevant tests and that all tests
are passing before submitting the PR. See the [writing tests](#writing-tests)
section below.
### Running your changes
To run Task with working changes, you can use `go run ./cmd/task`. To run a
development build of task against a test Taskfile in `testdata`, you can use
`go run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>`.
To run Task for Visual Studio Code, you can open the project in VSCode and hit
F5 (or whatever you debug keybind is set to). This will open a new VSCode window
with the extension running. Debugging this way is recommended as it will allow
you to set breakpoints and step through the code. Otherwise, you can run
`task package` which will generate a `.vsix` file that can be used to manually
install the extension.
### Updating documentation
Task uses [Vitepress][vitepress] to host a documentation server. The code for
this is located in the core Task repository. This can be setup and run locally
by using `task website` (requires `nodejs` & `pnpm`). All content is written in
Markdown and is located in the `website/src` directory. All Markdown documents
should have an 80 character line wrap limit (enforced by Prettier).
When making a change, consider whether a change to the [Usage Guide](/docs/guide) is
necessary. This document contains descriptions and examples of how to use Task
features. If you're adding a new feature, try to find an appropriate place to
add a new section. If you're updating an existing feature, ensure that the
documentation and any examples are up-to-date. Ensure that any examples follow
the [Taskfile Styleguide](./styleguide.md).
If you added a new command or flag, ensure that you add it to the
[CLI Reference](./reference/cli.md). New fields also need to be added to the
[Schema Reference](./reference/schema.md) and [JSON Schema][json-schema]. The
descriptions for fields in the docs and the schema should match.
### Writing tests
A lot of Task's tests are held in the `task_test.go` file in the project root
and this is where you'll most likely want to add new ones too. Most of these
tests also have a subdirectory in the `testdata` directory where any
Taskfiles/data required to run the tests are stored.
When making a changes, consider whether new tests are required. These tests
should ensure that the functionality you are adding will continue to work in the
future. Existing tests may also need updating if you have changed Task's
behavior.
You may also consider adding unit tests for any new functions you have added.
The unit tests should follow the Go convention of being location in a file named
`*_test.go` in the same package as the code being tested.
## 3. Committing your code
Try to write meaningful commit messages and avoid having too many commits on the
PR. Most PRs should likely have a single commit (although for bigger PRs it may
be reasonable to split it in a few). Git squash and rebase is your friend!
If you're not sure how to format your commit message, check out [Conventional
Commits][conventional-commits]. This style is not enforced, but it is a good way
to make your commit messages more readable and consistent.
## 4. Submitting a PR
- **Describe your changes** - Ensure that you provide a comprehensive
description of your changes.
- **Issue/PR links** - Link any previous work such as related issues or PRs.
Please describe how your changes differ to/extend this work.
- **Examples** - Add any examples or screenshots that you think are useful to
demonstrate the effect of your changes.
- **Draft PRs** - If your changes are incomplete, but you would like to discuss
them, open the PR as a draft and add a comment to start a discussion. Using
comments rather than the PR description allows the description to be updated
later while preserving any discussions.
## FAQ
> I want to contribute, where do I start?
Take a look at the list of [open issues for Task][task-open-issues] or [Task for
Visual Studio Code][vscode-task-open-issues]. We have a [good first
issue][good-first-issue] label for simpler issues that are ideal for first time
contributions.
All kinds of contributions are welcome, whether its a typo fix or a shiny new
feature. You can also contribute by upvoting/commenting on issues, helping to
answer questions or contributing to other [community projects](./community.md).
> I'm stuck, where can I get help?
If you have questions, feel free to ask them in the `#help` forum channel on our
[Discord server][discord-server] or open a [Discussion][discussion] on GitHub.
---
[task]: https://github.com/go-task/task
[vscode-task]: https://github.com/go-task/vscode-task
[go]: https://go.dev
[gofumpt]: https://github.com/mvdan/gofumpt
[gci]: https://github.com/daixiang0/gci
[golangci-lint]: https://golangci-lint.run
[golangci-lint-docs]: https://golangci-lint.run/welcome/integrations/
[prettier]: https://prettier.io
[nodejs]: https://nodejs.org/en/
[pnpm]: https://pnpm.io/
[vitepress]: https://vitepress.dev
[json-schema]:
https://github.com/go-task/task/blob/main/website/static/schema.json
[task-open-issues]: https://github.com/go-task/task/issues
[vscode-task-open-issues]: https://github.com/go-task/vscode-task/issues
[good-first-issue]:
https://github.com/go-task/task/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
[discord-server]: https://discord.gg/6TY36E39UK
[discussion]: https://github.com/go-task/task/discussions
[conventional-commits]: https://www.conventionalcommits.org
[mdx]: https://mdxjs.com/

25
website/src/docs/deprecations/completion-scripts.md Normal file
View File

@@ -0,0 +1,25 @@
---
title: 'Completion Scripts'
description: Deprecation of direct completion scripts in Task’s Git directory
outline: deep
---
# Completion Scripts
::: danger
This deprecation breaks the following functionality:
- Any direct references to the completion scripts in the Task git repository
:::
Direct use of the completion scripts in the `completion/*` directory of the
[github.com/go-task/task][task] Git repository is deprecated. Any shell
configuration that directly refers to these scripts will potentially break in
the future as the scripts may be moved or deleted entirely. Any configuration
should be updated to use the [new method for generating shell
completions][completions] instead.
[completions]: /docs/installation#setup-completions
[task]: https://github.com/go-task/task

22
website/src/docs/deprecations/index.md Normal file
View File

@@ -0,0 +1,22 @@
---
title: Deprecations
description:
Guide to deprecated features in Task and how to migrate to the new
alternatives
outline: deep
---
# Deprecations
As Task evolves, it occasionally outgrows some of its functionality. This can be
because they are no longer useful, because another feature has replaced it or
because of a change in the way that Task works internally.
When this happens, we mark the functionality as deprecated. This means that it
will be removed in a future version of Task. This functionality will continue to
work until that time, but we strongly recommend that you do not implement this
functionality in new Taskfiles and make a plan to migrate away from it as soon
as possible.
You can view a full list of active deprecations in the "Deprecations" section of
the sidebar.

27
website/src/docs/deprecations/template-functions.md Normal file
View File

@@ -0,0 +1,27 @@
---
title: 'Template Functions'
description:
Deprecation of some templating functions in Task, with guidance on their
replacements.
outline: deep
---
# Template Functions
::: danger
This deprecation breaks the following functionality:
- A small set of templating functions
:::
The following templating functions are deprecated. Any replacement functions are
listed besides the function being removed.
| Deprecated function | Replaced by |
| ------------------- | ----------- |
| `IsSH` | - |
| `FromSlash` | `fromSlash` |
| `ToSlash` | `toSlash` |
| `ExeExt` | `exeExt` |

24
website/src/docs/deprecations/template.md Normal file
View File

@@ -0,0 +1,24 @@
---
# This is a template for deprecation documentation
# Copy this page and fill in the details as necessary
title: '--- Template ---'
description: Template for documenting deprecated features in Task
draft: true # Hide in production
outline: deep
---
# {Name of Deprecated Feature} (#{Issue})
::: danger
This deprecation breaks the following functionality:
- {list any existing functionality that will be broken by this deprecation}
- {if there are no breaking changes, remove this admonition}
:::
{Short description of the feature/behavior and why it is being deprecated}
{Short explanation of any replacement features/behaviors and how users should
migrate to it}

33
website/src/docs/deprecations/version-2-schema.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: 'Version 2 Schema (#1197)'
description: Deprecation of Taskfile schema version 2 and migration to version 3
outline: deep
---
# Version 2 Schema (#1197)
::: danger
This deprecation breaks the following functionality:
- Any Taskfiles that use the version 2 schema
- `Taskvar.yml` files
:::
The Taskfile version 2 schema was introduced in March 2018 and replaced by
version 3 in August 2019. In May 2023 [we published a deprecation
notice][deprecation-notice] for the version 2 schema on the basis that the vast
majority of users had already upgraded to version 3 and removing support for
version 2 would allow us to tidy up the codebase and focus on new functionality
instead.
In December 2023, the final version of Task that supports the version 2 schema
([v3.33.0][v3.33.0]) was published and all legacy code was removed from Task's
main branch. To use a more recent version of Task, you will need to ensure that
your Taskfile uses the version 3 schema instead. A list of changes between
version 2 and version 3 are available in the [Task v3 Release Notes][v3.0.0].
[v3.0.0]: https://github.com/go-task/task/releases/tag/v3.0.0
[v3.33.0]: https://github.com/go-task/task/releases/tag/v3.33.0
[deprecation-notice]: https://github.com/go-task/task/issues/1197

77
website/src/docs/experiments/env-precedence.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: 'Env Precedence (#1038)'
description:
Experiment to change the precedence of environment variables in Task
outline: deep
---
# Env Precedence (#1038)
::: warning
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
::: danger
This experiment breaks the following functionality:
- environment variable will take precedence over OS environment variables
:::
::: info
To enable this experiment, set the environment variable:
`TASK_X_ENV_PRECEDENCE=1`. Check out
[our guide to enabling experiments](./index.md#enabling-experiments) for more
information.
:::
Before this experiment, the OS variable took precedence over the task
environment variable. This experiment changes the precedence to make the task
environment variable take precedence over the OS variable.
Consider the following example:
```yml
version: '3'
tasks:
default:
env:
KEY: 'other'
cmds:
- echo "$KEY"
```
Running `KEY=some task` before this experiment, the output would be `some`, but
after this experiment, the output would be `other`.
If you still want to get the OS variable, you can use the template function env
like follow : <span v-pre>`{{env "OS_VAR"}}`</span>.
```yml
version: '3'
tasks:
default:
env:
KEY: 'other'
cmds:
- echo "$KEY"
- echo {{env "KEY"}}
```
Running `KEY=some task`, the output would be `other` and `some`.
Like other variables/envs, you can also fall back to a given value using the
default template function:
```yml
MY_ENV: '{{.MY_ENV | default "fallback"}}'
```

48
website/src/docs/experiments/gentle-force.md Normal file
View File

@@ -0,0 +1,48 @@
---
title: 'Gentle Force (#1200)'
description: Experiment to modify the behavior of the --force flag in Task
outline: deep
---
# Gentle Force (#1200)
::: warning
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
::: danger
This experiment breaks the following functionality:
- The `--force` flag
:::
::: info
To enable this experiment, set the environment variable:
`TASK_X_GENTLE_FORCE=1`. Check out
[our guide to enabling experiments](./index.md#enabling-experiments) for more
information.
:::
The `--force` flag currently forces _all_ tasks to run regardless of the status
checks. This can be useful, but we have found that most of the time users only
expect the direct task they are calling to be forced and _not_ all of its
dependant tasks.
This experiment changes the `--force` flag to only force the directly called
task. All dependant tasks will have their statuses checked as normal and will
only run if Task considers them to be out of date. A new `--force-all` flag will
also be added to maintain the current behavior for users that need this
functionality.
If you want to migrate, but continue to force all dependant tasks to run, you
should replace all uses of the `--force` flag with `--force-all`. Alternatively,
if you want to adopt the new behavior, you can continue to use the `--force`
flag as you do now!

148
website/src/docs/experiments/index.md Normal file
View File

@@ -0,0 +1,148 @@
---
title: Experiments
description: Guide to Task’s experimental features and how to use them
outline: deep
---
# Experiments
::: warning
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
In order to allow Task to evolve quickly, we sometimes roll out breaking changes
to minor versions behind experimental flags. This allows us to gather feedback
on breaking changes before committing to a major release. This process can also
be used to gather feedback on important non-breaking features before their
design is completed. This document describes the
[experiment workflow](#workflow) and how you can get involved.
You can view the full list of active experiments in the sidebar submenu to the
left of the page and click on each one to find out more about it.
## Enabling Experiments
Task uses environment variables to detect whether or not an experiment is
enabled. All of the experiment variables will begin with the same `TASK_X_`
prefix followed by the name of the experiment. You can find the exact name for
each experiment on their respective pages in the sidebar. If the variable is set
`=1` then it will be enabled. Some experiments may have multiple proposals, in
which case, you will need to set the variable equal to the number of the
proposal that you want to enable (`=2`, `=3` etc).
There are three main ways to set the environment variables for an experiment.
Which method you use depends on how you intend to use the experiment:
1. Prefixing your task commands with the relevant environment variable(s). For
example, `TASK_X_{FEATURE}=1 task {my-task}`. This is intended for one-off
invocations of Task to test out experimental features.
2. Adding the relevant environment variable(s) in your "dotfiles" (e.g.
`.bashrc`, `.zshrc` etc.). This will permanently enable experimental features
for your personal environment.
```shell
# ~/.bashrc
export TASK_X_FEATURE=1
```
3. Creating a `.env` or a `.taskrc.yml` file in the same directory as your root
Taskfile.\
The `.env` file should contain the relevant environment variable(s), while
the `.taskrc.yml` file should use a YAML format where each experiment is
defined as a key with a corresponding value.
This allows you to enable an experimental feature at a project level. If you
commit this file to source control, then other users of your project will
also have these experiments enabled.
If both files are present, the values in the `.taskrc.yml` file will take
precedence.
::: code-group
```yaml [.taskrc.yml]
experiments:
FEATURE: 1
```
```shell [.env]
TASK_X_FEATURE=1
```
:::
## Workflow
Experiments are a way for us to test out new features in Task before committing
to them in a major release. Because this concept is built around the idea of
feedback from our community, we have built a workflow for the process of
introducing these changes. This ensures that experiments are given the attention
and time that they need and that we are getting the best possible results out of
them.
The sections below describe the various stages that an experiment must go
through from its proposal all the way to being released in a major version of
Task.
### 1. Proposal
All experimental features start with a proposal in the form of a GitHub issue.
If the maintainers decide that an issue has enough support and is a breaking
change or is complex/controversial enough to require user feedback, then the
issue will be marked with the `status: proposal` label. At this point, the issue
becomes a proposal and a period of consultation begins. During this period, we
request that users provide feedback on the proposal and how it might effect
their use of Task. It is up to the discretion of the maintainers to decide how
long this period lasts.
### 2. Draft
Once a proposal's consultation ends, a contributor may pick up the work and
begin the initial implementation. Once a PR is opened, the maintainers will
ensure that it meets the requirements for an experimental feature (i.e. flags
are in the right format etc) and merge the feature. Once this code is released,
the status will be updated via the `status: draft` label. This indicates that an
implementation is now available for use in a release and the experiment is open
for feedback.
::: info
During the draft period, major changes to the implementation may be made based
on the feedback received from users. There are _no stability guarantees_ and
experimental features may be abandoned _at any time_.
:::
### 3. Candidate
Once an acceptable level of consensus has been reached by the community and
feedback/changes are less frequent/significant, the status may be updated via
the `status: candidate` label. This indicates that a proposal is _likely_ to
accepted and will enter a period for final comments and minor changes.
### 4. Stable
Once a suitable amount of time has passed with no changes or feedback, an
experiment will be given the `status: stable` label. At this point, the
functionality will be treated like any other feature in Task and any changes
_must_ be backward compatible. This allows users to migrate to the new
functionality without having to worry about anything breaking in future
releases. This provides the best experience for users migrating to a new major
version.
### 5. Released
When making a new major release of Task, all experiments marked as
`status: stable` will move to `status: released` and their behaviors will become
the new default in Task. Experiments in an earlier stage (i.e. not stable)
cannot be released and so will continue to be experiments in the new version.
### Abandoned / Superseded
If an experiment is unsuccessful at any point then it will be given the
`status: abandoned` or `status: superseded` labels depending on which is more
suitable. These experiments will be removed from Task.

292
website/src/docs/experiments/remote-taskfiles.md Normal file
View File

@@ -0,0 +1,292 @@
---
title: 'Remote Taskfiles (#1317)'
description: Experimentation for using Taskfiles stored in remote locations
outline: deep
---
# Remote Taskfiles (#1317)
::: warning
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
::: info
To enable this experiment, set the environment variable:
`TASK_X_REMOTE_TASKFILES=1`. Check out
[our guide to enabling experiments](./index.md#enabling-experiments) for more
information.
:::
::: danger
Never run remote Taskfiles from sources that you do not trust.
:::
This experiment allows you to use Taskfiles which are stored in remote
locations. This applies to both the root Taskfile (aka. Entrypoint) and also
when including Taskfiles.
Task uses "nodes" to reference remote Taskfiles. There are a few different types
of node which you can use:
::: code-group
```text [HTTP/HTTPS]
https://raw.githubusercontent.com/go-task/task/main/website/static/Taskfile.yml
```
```text [Git over HTTP]
https://github.com/go-task/task.git//website/static/Taskfile.yml?ref=main
```
```text [Git over SSH]
git@github.com/go-task/task.git//website/static/Taskfile.yml?ref=main
```
:::
## Node Types
### HTTP/HTTPS
`https://raw.githubusercontent.com/go-task/task/main/website/static/Taskfile.yml`
This is the most basic type of remote node and works by downloading the file
from the specified URL. The file must be a valid Taskfile and can be of any
name. If a file is not found at the specified URL, Task will append each of the
supported file names in turn until it finds a valid file. If it still does not
find a valid Taskfile, an error is returned.
### Git over HTTP
`https://github.com/go-task/task.git//website/static/Taskfile.yml?ref=main`
This type of node works by downloading the file from a Git repository over
HTTP/HTTPS. The first part of the URL is the base URL of the Git repository.
This is the same URL that you would use to clone the repo over HTTP.
- You can optionally add the path to the Taskfile in the repository by appending
`//<path>` to the URL.
- You can also optionally specify a branch or tag to use by appending
`?ref=<ref>` to the end of the URL. If you omit a reference, the default
branch will be used.
### Git over SSH
`git@github.com/go-task/task.git//website/static/Taskfile.yml?ref=main`
This type of node works by downloading the file from a Git repository over SSH.
The first part of the URL is the user and base URL of the Git repository. This
is the same URL that you would use to clone the repo over SSH.
To use Git over SSH, you need to make sure that your SSH agent has your private
SSH keys added so that they can be used during authentication.
- You can optionally add the path to the Taskfile in the repository by appending
`//<path>` to the URL.
- You can also optionally specify a branch or tag to use by appending
`?ref=<ref>` to the end of the URL. If you omit a reference, the default
branch will be used.
Task has an example remote Taskfile in our repository that you can use for
testing and that we will use throughout this document:
```yaml
version: '3'
tasks:
default:
cmds:
- task: hello
hello:
cmds:
- echo "Hello Task!"
```
## Specifying a remote entrypoint
By default, Task will look for one of the supported file names on your local
filesystem. If you want to use a remote file instead, you can pass its URI into
the `--taskfile`/`-t` flag just like you would to specify a different local
file. For example:
::: code-group
```shell [HTTP/HTTPS]
$ task --taskfile https://raw.githubusercontent.com/go-task/task/main/website/static/Taskfile.yml
task: [hello] echo "Hello Task!"
Hello Task!
```
```shell [Git over HTTP]
$ task --taskfile https://github.com/go-task/task.git//website/static/Taskfile.yml?ref=main
task: [hello] echo "Hello Task!"
Hello Task!
```
```shell [Git over SSH]
$ task --taskfile git@github.com/go-task/task.git//website/static/Taskfile.yml?ref=main
task: [hello] echo "Hello Task!"
Hello Task!
```
:::
## Including remote Taskfiles
Including a remote file works exactly the same way that including a local file
does. You just need to replace the local path with a remote URI. Any tasks in
the remote Taskfile will be available to run from your main Taskfile.
::: code-group
```yaml [HTTP/HTTPS]
version: '3'
includes:
my-remote-namespace: https://raw.githubusercontent.com/go-task/task/main/website/static/Taskfile.yml
```
```yaml [Git over HTTP]
version: '3'
includes:
my-remote-namespace: https://github.com/go-task/task.git//website/static/Taskfile.yml?ref=main
```
```yaml [Git over SSH]
version: '3'
includes:
my-remote-namespace: git@github.com/go-task/task.git//website/static/Taskfile.yml?ref=main
```
:::
```shell
$ task my-remote-namespace:hello
task: [hello] echo "Hello Task!"
Hello Task!
```
### Authenticating using environment variables
The Taskfile location is processed by the templating system, so you can
reference environment variables in your URL if you need to add authentication.
For example:
```yaml
version: '3'
includes:
my-remote-namespace: https://{{.TOKEN}}@raw.githubusercontent.com/my-org/my-repo/main/Taskfile.yml
```
## Security
### Automatic checksums
Running commands from sources that you do not control is always a potential
security risk. For this reason, we have added some automatic checks when using
remote Taskfiles:
1. When running a task from a remote Taskfile for the first time, Task will
print a warning to the console asking you to check that you are sure that you
trust the source of the Taskfile. If you do not accept the prompt, then Task
will exit with code `104` (not trusted) and nothing will run. If you accept
the prompt, the remote Taskfile will run and further calls to the remote
Taskfile will not prompt you again.
2. Whenever you run a remote Taskfile, Task will create and store a checksum of
the file that you are running. If the checksum changes, then Task will print
another warning to the console to inform you that the contents of the remote
file has changed. If you do not accept the prompt, then Task will exit with
code `104` (not trusted) and nothing will run. If you accept the prompt, the
checksum will be updated and the remote Taskfile will run.
Sometimes you need to run Task in an environment that does not have an
interactive terminal, so you are not able to accept a prompt. In these cases you
are able to tell task to accept these prompts automatically by using the `--yes`
flag. Before enabling this flag, you should:
1. Be sure that you trust the source and contents of the remote Taskfile.
2. Consider using a pinned version of the remote Taskfile (e.g. A link
containing a commit hash) to prevent Task from automatically accepting a
prompt that says a remote Taskfile has changed.
### Manual checksum pinning
Alternatively, if you expect the contents of your remote files to be a constant
value, you can pin the checksum of the included file instead:
```yaml
version: '3'
includes:
included:
taskfile: https://taskfile.dev
checksum: c153e97e0b3a998a7ed2e61064c6ddaddd0de0c525feefd6bba8569827d8efe9
```
This will disable the automatic checksum prompts discussed above. However, if
the checksums do not match, Task will exit immediately with an error. When
setting this up for the first time, you may not know the correct value of the
checksum. There are a couple of ways you can obtain this:
1. Add the include normally without the `checksum` key. The first time you run
the included Taskfile, a `.task/remote` temporary directory is created. Find
the correct set of files for your included Taskfile and open the file that
ends with `.checksum`. You can copy the contents of this file and paste it
into the `checksum` key of your include. This method is safest as it allows
you to inspect the downloaded Taskfile before you pin it.
2. Alternatively, add the include with a temporary random value in the
`checksum` key. When you try to run the Taskfile, you will get an error that
will report the incorrect expected checksum and the actual checksum. You can
copy the actual checksum and replace your temporary random value.
### TLS
Task currently supports both `http` and `https` URLs. However, the `http`
requests will not execute by default unless you run the task with the
`--insecure` flag. This is to protect you from accidentally running a remote
Taskfile that is downloaded via an unencrypted connection. Sources that are not
protected by TLS are vulnerable to man-in-the-middle attacks and should be
avoided unless you know what you are doing.
## Caching & Running Offline
Whenever you run a remote Taskfile, the latest copy will be downloaded from the
internet and cached locally. This cached file will be used for all future
invocations of the Taskfile until the cache expires. Once it expires, Task will
download the latest copy of the file and update the cache. By default, the cache
is set to expire immediately. This means that Task will always fetch the latest
version. However, the cache expiry duration can be modified by setting the
`--expiry` flag.
If for any reason you lose access to the internet or you are running Task in
offline mode (via the `--offline` flag or `TASK_OFFLINE` environment variable),
Task will run the any available cached files _even if they are expired_. This
means that you should never be stuck without the ability to run your tasks as
long as you have downloaded a remote Taskfile at least once.
By default, Task will timeout requests to download remote files after 10 seconds
and look for a cached copy instead. This timeout can be configured by setting
the `--timeout` flag and specifying a duration. For example, `--timeout 5s` will
set the timeout to 5 seconds.
By default, the cache is stored in the Task temp directory, represented by the
`TASK_TEMP_DIR` environment variable. You can override the location of the cache
by setting the `TASK_REMOTE_DIR` environment variable. This way, you can share
the cache between different projects.
You can force Task to ignore the cache and download the latest version by using
the `--download` flag.
You can use the `--clear-cache` flag to clear all cached remote files.

36
website/src/docs/experiments/template.md Normal file
View File

@@ -0,0 +1,36 @@
---
title: '--- Template ---'
---
# \{Name of Experiment\} (#\{Issue\})
::: warning
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
::: warning
This experiment breaks the following functionality:
- \{list any existing functionality that will be broken by this experiment\}
- \{if there are no breaking changes, remove this admonition\}
:::
:::info
To enable this experiment, set the environment variable: `TASK_X_{feature}=1`.
Check out [our guide to enabling experiments ][enabling-experiments] for more
information.
:::
\{Short description of the feature\}
\{Short explanation of how users should migrate to the new behavior\}
[enabling-experiments]: /docs/experiments/#enabling-experiments

122
website/src/docs/faq.md Normal file
View File

@@ -0,0 +1,122 @@
---
title: FAQ
description:
Frequently asked questions about Task, including ETAs, shell limitations, and
Windows compatibility
outline: deep
---
# FAQ
This page contains a list of frequently asked questions about Task.
## When will \<feature\> be released? / ETAs
Task is _free_ and _open source_ project maintained by a small group of
volunteers with full time jobs and lives outside of the project. Because of
this, it is difficult to predict how much time we will be able to dedicate to
the project in advance and we don't want to make any promises that we can't
keep. For this reason, we are unable to provide ETAs for new features or
releases. We make a "best effort" to provide regular releases and fix bugs in a
timely fashion, but sometimes our personal lives must take priority.
ETAs are probably the number one question we (and maintainers of other open
source projects) get asked. We understand that you are passionate about the
project, but it can be overwhelming to be asked this question so often. Please
be patient and avoid asking for ETAs.
The best way to speed things up is to contribute to the project yourself. We
always appreciate new contributors. If you are interested in contributing, check
out the [contributing guide](./contributing.md).
## Why won't my task update my shell environment?
This is a limitation of how shells work. Task runs as a subprocess of your
current shell, so it can't change the environment of the shell that started it.
This limitation is shared by other task runners and build tools too.
A common way to work around this is to create a task that will generate output
that can be parsed by your shell. For example, to set an environment variable on
your shell you can write a task like this:
```yaml
my-shell-env:
cmds:
- echo "export FOO=foo"
- echo "export BAR=bar"
```
Now run `eval $(task my-shell-env)` and the variables `$FOO` and `$BAR` will be
available in your shell.
## I can't reuse my shell in a task's commands
Task runs each command as a separate shell process, so something you do in one
command won't effect any future commands. For example, this won't work:
```yaml
version: '3'
tasks:
foo:
cmds:
- a=foo
- echo $a
# outputs ""
```
To work around this you can either use a multiline command:
```yaml
version: '3'
tasks:
foo:
cmds:
- |
a=foo
echo $a
# outputs "foo"
```
Or for more complex multi-line commands it is recommended to move your code into
a separate file and call that instead:
```yaml
version: '3'
tasks:
foo:
cmds:
- ./foo-printer.bash
```
```shell
#!/bin/bash
a=foo
echo $a
```
## 'x' builtin command doesn't work on Windows
The default shell on Windows (`cmd` and `powershell`) do not have commands like
`rm` and `cp` available as builtins. This means that these commands won't work.
If you want to make your Taskfile fully cross-platform, you'll need to work
around this limitation using one of the following methods:
- Use the <span v-pre>`{{OS}}`</span> function to run an OS-specific script.
- Use something like
<span v-pre>`{{if eq OS "windows"}}powershell {{end}}<my_cmd>`</span> to
detect windows and run the command in Powershell directly.
- Use a shell on Windows that supports these commands as builtins, such as [Git
Bash][git-bash] or [WSL][wsl].
We want to make improvements to this part of Task and the issues below track
this work. Constructive comments and contributions are very welcome!
- #197
- [mvdan/sh#93](https://github.com/mvdan/sh/issues/93)
- [mvdan/sh#97](https://github.com/mvdan/sh/issues/97)
[git-bash]: https://gitforwindows.org/
[wsl]: https://learn.microsoft.com/en-us/windows/wsl/install

133
website/src/docs/getting-started.md Normal file
View File

@@ -0,0 +1,133 @@
---
title: Getting Started
description: Guide for getting started with Task
outline: deep
---
# Getting Started
The following guide will help introduce you to the basics of Task. We'll cover
how to create a Taskfile, how to write a basic task and how to call it. If you
haven't installed Task yet, head over to our [installation guide](installation).
## Creating your first Taskfile
Once Task is installed, you can create your first Taskfile by running:
```shell
task --init
```
This will create a file called `Taskfile.yml` in the current directory. If you
want to create the file in another directory, you can pass an absolute or
relative path to the directory into the command:
```shell
task --init ./subdirectory
```
Or if you want the Taskfile to have a specific name, you can pass in the name of
the file:
```shell
task --init Custom.yml
```
This will create a Taskfile that looks something like this:
```yaml [Taskfile.yml]
version: '3'
vars:
GREETING: Hello, World!
tasks:
default:
cmds:
- echo "{{.GREETING}}"
silent: true
```
As you can see, all Taskfiles are written in [YAML format](https://yaml.org/).
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
`GREETING` variable. The `silent` attribute is set to `true`, which means that
the task metadata will not be printed when the task is run - only the output of
the commands.
## Calling a task
To call the task, invoke `task` followed by the name of the task you want to
run. In this case, the name of the task is `default`, so you should run:
```shell
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](/docs/guide#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.
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`
flag:
```shell
task --dir ./subdirectory
```
Or if you created a Taskfile with a different name, you can run it by passing
the name of the Taskfile as an argument using the `--taskfile` flag:
```shell
task --taskfile Custom.yml
```
## Adding a build task
Let's create a task to build a program in Go. Start by adding a new task called
`build` below the existing `default` task. We can then add a `cmds` attribute
with a single command to build the program.
Task uses [mvdan/sh](https://github.com/mvdan/sh), a native Go sh interpreter.
So you can write sh/bash-like commands - even in environments where `sh` or
`bash` are usually not available (like Windows). Just remember any executables
called must be available as a built-in or in the system's `PATH`.
When you're done, it should look something like this:
```yaml
version: '3'
vars:
GREETING: Hello, World!
tasks:
default:
cmds:
- echo "{{.GREETING}}"
silent: true
build:
cmds:
- go build ./cmd/main.go
```
Call the task by running:
```shell
task build
```
That's about it for the basics, but there's _so much_ more that you can do with
Task. Check out the rest of the documentation to learn more about all the
features Task has to offer! We recommend taking a look at the
[usage guide](/docs/guide) next. Alternatively, you can check out our reference docs
for the [Taskfile schema](reference/schema) and [CLI](reference/cli).

2391
website/src/docs/guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

323
website/src/docs/installation.md Normal file
View File

@@ -0,0 +1,323 @@
---
title: Installation
description: Installation methods for Task
outline: deep
---
# Installation
Task offers many installation methods. Check out the available methods below.
::: info
Some of the methods below are marked as
![Community](https://img.shields.io/badge/Community%20Owned-orange). This means
they are not maintained by the Task team and may not be up-to-date.
:::
## Package Managers
### [Homebrew](https://brew.sh) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black) {#homebrew}
Task is available via our official Homebrew tap
[[source](https://github.com/go-task/homebrew-tap/blob/main/Formula/go-task.rb)]:
```shell
brew install go-task/tap/go-task
```
Alternatively it can be installed from the official Homebrew repository
[[package](https://formulae.brew.sh/formula/go-task)]
[[source](https://github.com/Homebrew/homebrew-core/blob/master/Formula/g/go-task.rb)]
by running:
```shell
brew install go-task
```
### [Macports](https://macports.org) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple&logoColor=F0F0F0) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#macports}
Task repository is tracked by Macports
[[package](https://ports.macports.org/port/go-task/details/)]
[[source](https://github.com/macports/macports-ports/blob/master/devel/go-task/Portfile)]:
```shell
port install go-task
```
### [Snap](https://snapcraft.io/task) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black) {#snap}
Task is available on [Snapcraft](https://snapcraft.io/task)
[[source](https://github.com/go-task/snap/blob/main/snap/snapcraft.yaml)], but
keep in mind that your Linux distribution should allow classic confinement for
Snaps to Task work correctly:
```shell
sudo snap install task --classic
```
### [npm](https://www.npmjs.com) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11&logoColor=white) {#npm}
Npm can be used as cross-platform way to install Task globally or as a
dependency of your project
[[package](https://www.npmjs.com/package/@go-task/cli)]
[[source](https://github.com/go-task/task/blob/main/package.json)]:
```shell
npm install -g @go-task/cli
```
### [pip](https://pip.pypa.io) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11&logoColor=white) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#pip}
Like npm, pip can be used as a cross-platform way to install Task
[[package](https://pypi.org/project/go-task-bin)]
[[source](https://github.com/Bing-su/pip-binary-factory/tree/main/task)]:
```shell
pip install go-task-bin
```
### [WinGet](https://github.com/microsoft/winget-cli) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11&logoColor=white) {#winget}
Task is available via the
[community repository](https://github.com/microsoft/winget-pkgs)
[[source](https://github.com/microsoft/winget-pkgs/tree/master/manifests/t/Task/Task)]:
```shell
winget install Task.Task
```
### [Chocolatey](https://chocolatey.org) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11&logoColor=white) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#chocolatey}
[[package](https://community.chocolatey.org/packages/go-task)]
[[source](https://github.com/Starz0r/ChocolateyPackagingScripts/blob/master/src/go-task_gh_build.py)]
```shell
choco install go-task
```
### [Scoop](https://scoop.sh) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11&logoColor=white) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#scoop}
[[source](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json)]
```shell
scoop install task
```
### Arch ([pacman](https://wiki.archlinux.org/title/Pacman)) ![Arch Linux](https://img.shields.io/badge/Arch%20Linux-1793D1?logo=arch-linux&logoColor=fff) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#arch}
[[package](https://archlinux.org/packages/extra/x86_64/go-task/)]
[[source](https://gitlab.archlinux.org/archlinux/packaging/packages/go-task)]
```shell
pacman -S go-task
```
### Fedora ([dnf](https://docs.fedoraproject.org/en-US/quick-docs/dnf)) ![Fedora](https://img.shields.io/badge/Fedora-51A2DA?logo=fedora&logoColor=fff) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#fedora}
[[package](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/)]
[[source](https://src.fedoraproject.org/rpms/golang-github-task)]
```shell
dnf install go-task
```
### FreeBSD ([Ports](https://ports.freebsd.org/cgi/ports.cgi)) ![FreeBSD](https://img.shields.io/badge/FreeBSD-990000?logo=freebsd&logoColor=fff) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#freebsd}
[[package](https://cgit.freebsd.org/ports/tree/devel/task)]
[[source](https://cgit.freebsd.org/ports/tree/devel/task/Makefile)]
```shell
pkg install task
```
### NixOS ([nix](https://nixos.org)) ![NixOS](https://img.shields.io/badge/NixOS-5277C3?logo=nixos&logoColor=fff) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#nix}
[[source](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/go/go-task/package.nix)]
```shell
nix-env -iA nixpkgs.go-task
```
### [pacstall](https://github.com/pacstall/pacstall) ![Debian](https://img.shields.io/badge/Debian-A81D33?logo=debian&logoColor=fff) ![Ubuntu](https://img.shields.io/badge/Ubuntu-E95420?logo=ubuntu&logoColor=fff) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#pacstall}
[[package](https://pacstall.dev/packages/go-task-deb)]
[[source](https://github.com/pacstall/pacstall-programs/blob/master/packages/go-task-deb/go-task-deb.pacscript)]
```shell
pacstall -I go-task-deb
```
### [pkgx](https://pkgx.sh) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black) ![Community](https://img.shields.io/badge/Community%20Owned-orange) {#pkgx}
[[package](https://pkgx.dev/pkgs/taskfile.dev)]
[[source](https://github.com/pkgxdev/pantry/blob/main/projects/taskfile.dev/package.yml)]
```shell
pkgx task
```
or, if you have pkgx integration enabled:
```shell
task
```
## Get The Binary
### Binary
You can download the binary from the
[releases page on GitHub](https://github.com/go-task/task/releases) and add to
your `$PATH`.
DEB and RPM packages are also available.
The `task_checksums.txt` file contains the SHA-256 checksum for each file.
### Install Script
We also have an
[install script](https://github.com/go-task/task/blob/main/install-task.sh)
which is very useful in scenarios like CI. Many thanks to
[GoDownloader](https://github.com/goreleaser/godownloader) for enabling the easy
generation of this script.
By default, it installs on the `./bin` directory relative to the working
directory:
```shell
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d
```
It is possible to override the installation directory with the `-b` parameter.
On Linux, common choices are `~/.local/bin` and `~/bin` to install for the
current user or `/usr/local/bin` to install for all users:
```shell
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
```
::: warning
On macOS and Windows, `~/.local/bin` and `~/bin` are not added to `$PATH` by
default.
:::
By default, it installs the latest version available. You can also specify a tag
(available in [releases](https://github.com/go-task/task/releases)) to install a
specific version:
```shell
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d v3.36.0
```
Parameters are order specific, to set both installation directory and version:
```shell
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin v3.42.1
```
### GitHub Actions
If you want to install Task in GitHub Actions you can try using
[this action](https://github.com/arduino/setup-task) by the Arduino team:
```yaml
- name: Install Task
uses: arduino/setup-task@v2
with:
version: 3.x
repo-token: ${{ secrets.GITHUB_TOKEN }}
```
This installation method is community owned.
## Build From Source
### Go Modules
Ensure that you have a supported version of [Go](https://golang.org) properly
installed and setup. You can find the minimum required version of Go in the
[go.mod](https://github.com/go-task/task/blob/main/go.mod#L3) file.
You can then install the latest release globally by running:
```shell
go install github.com/go-task/task/v3/cmd/task@latest
```
Or you can install into another directory:
```shell
env GOBIN=/bin go install github.com/go-task/task/v3/cmd/task@latest
```
::: tip
For CI environments we recommend using the [install script](#install-script)
instead, which is faster and more stable, since it'll just download the latest
released binary.
:::
## Setup completions
Some installation methods will automatically install completions too, but if
this isn't working for you or your chosen method doesn't include them, you can
run `task --completion <shell>` to output a completion script for any supported
shell. There are a couple of ways these completions can be added to your shell
config:
### Option 1. Load the completions in your shell's startup config (Recommended)
This method loads the completion script from the currently installed version of
task every time you create a new shell. This ensures that your completions are
always up-to-date.
::: code-group
```shell [bash]
# ~/.bashrc
eval "$(task --completion bash)"
```
```shell [zsh]
# ~/.zshrc
eval "$(task --completion zsh)"
```
```shell [fish]
# ~/.config/fish/config.fish
task --completion fish | source
```
```powershell [powershell]
# $PROFILE\Microsoft.PowerShell_profile.ps1
Invoke-Expression (&task --completion powershell | Out-String)
```
:::
### Option 2. Copy the script to your shell's completions directory
This method requires you to manually update the completions whenever Task is
updated. However, it is useful if you want to modify the completions yourself.
::: code-group
```shell [bash]
task --completion bash > /etc/bash_completion.d/task
```
```shell [zsh]
task --completion zsh > /usr/local/share/zsh/site-functions/_task
```
```shell [fish]
task --completion fish > ~/.config/fish/completions/task.fish
```
:::

87
website/src/docs/integrations.md Normal file
View File

@@ -0,0 +1,87 @@
---
title: Integrations
description:
Official and community integrations for Task, including VS Code, JSON schemas,
and other tools
outline: deep
---
# Integrations
## Visual Studio Code Extension
Task has an
[official extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=task.vscode-task).
The code for this project can be found
[here](https://github.com/go-task/vscode-task). To use this extension, you must
have Task v3.23.0+ installed on your system.
This extension provides the following features (and more):
- View tasks in the sidebar.
- Run tasks from the sidebar and command palette.
- Go to definition from the sidebar and command palette.
- Run last task command.
- Multi-root workspace support.
- Initialize a Taskfile in the current workspace.
To get autocompletion and validation for your Taskfile, see the
[Schema](#schema) section below.
![Task for Visual Studio Code](https://github.com/go-task/vscode-task/blob/main/res/preview.png?raw=true)
## Schema
This was initially created by @KROSF in
[this Gist](https://gist.github.com/KROSF/c5435acf590acd632f71bb720f685895) and
is now officially maintained in
[this file](https://github.com/go-task/task/blob/main/website/static/schema.json)
and made available at https://taskfile.dev/schema.json. This schema can be used
to validate Taskfiles and provide autocompletion in many code editors:
### Visual Studio Code
To integrate the schema into VS Code, you need to install the
[YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
by Red Hat. Any `Taskfile.yml` in your project should automatically be detected
and validation/autocompletion should work. If this doesn't work or you want to
manually configure it for files with a different name, you can add the following
to your `settings.json`:
```json
// settings.json
{
"yaml.schemas": {
"https://taskfile.dev/schema.json": [
"**/Taskfile.yml",
"./path/to/any/other/taskfile.yml"
]
}
}
```
You can also configure the schema directly inside of a Taskfile by adding the
following comment to the top of the file:
```yaml
# yaml-language-server: $schema=https://taskfile.dev/schema.json
version: '3'
```
You can find more information on this in the
[YAML language server project](https://github.com/redhat-developer/yaml-language-server).
## Community Integrations
In addition to our official integrations, there is an amazing community of
developers who have created their own integrations for Task:
- [Sublime Text Plugin](https://packagecontrol.io/packages/Taskfile)
[[source](https://github.com/biozz/sublime-taskfile)] by @biozz
- [IntelliJ Plugin](https://plugins.jetbrains.com/plugin/17058-taskfile)
[[source](https://github.com/lechuckroh/task-intellij-plugin)] by @lechuckroh
- [mk](https://github.com/pycontribs/mk) command line tool recognizes Taskfiles
natively.
If you have made something that integrates with Task, please feel free to open a
PR to add it to this list.

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"}}'
```

74
website/src/docs/releasing.md Normal file
View File

@@ -0,0 +1,74 @@
---
title: Releasing
description:
Task release process including GoReleaser, Homebrew, npm, Snapcraft, winget,
and other package managers
outline: deep
---
# Releasing
The release process of Task is done with the help of [GoReleaser][goreleaser].
You can test the release process locally by calling the `test-release` task of
the Taskfile.
[GitHub Actions](https://github.com/go-task/task/actions) should release
artifacts automatically when a new Git tag is pushed to `main` branch (raw
executables and DEB and RPM packages).
Since v3.15.0, raw executables can also be reproduced and verified locally by
checking out a specific tag and calling `goreleaser build`, using the Go version
defined in the above GitHub Actions.
## Homebrew
Goreleaser will automatically push a new commit to the
[Formula/go-task.rb][gotaskrb] file in the [Homebrew tap][homebrewtap]
repository to release the new version.
## npm
To release to npm update the version in the [`package.json`][packagejson] file
and then run `task npm:publish` to push it.
## Snapcraft
The [snap package][snappackage] requires to manual steps to release a new
version:
- Updating the current version on [snapcraft.yaml][snapcraftyaml].
- Moving both `amd64`, `armhf` and `arm64` new artifacts to the stable channel
on the [Snapcraft dashboard][snapcraftdashboard].
## winget
winget also requires manual steps to be completed. By running
`task goreleaser:test` locally, manifest files will be generated on
`dist/winget/manifests/t/Task/Task/v{version}`.
[Upload the manifest directory into this fork](https://github.com/go-task/winget-pkgs/tree/master/manifests/t/Task/Task)
and open a pull request into
[this repository](https://github.com/microsoft/winget-pkgs).
## Scoop
Scoop is a command-line package manager for the Windows operating system. Scoop
package manifests are maintained by the community. Scoop owners usually take
care of updating versions there by editing
[this file](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json).
If you think its Task version is outdated, open an issue to let us know.
## Nix
Nix is a community owned installation method. Nix package maintainers usually
take care of updating versions there by editing
[this file](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/go/go-task/package.nix).
If you think its Task version is outdated, open an issue to let us know.
[goreleaser]: https://goreleaser.com/
[homebrewtap]: https://github.com/go-task/homebrew-tap
[gotaskrb]: https://github.com/go-task/homebrew-tap/blob/main/Formula/go-task.rb
[packagejson]: https://github.com/go-task/task/blob/main/package.json#L3
[snappackage]: https://github.com/go-task/snap
[snapcraftyaml]:
https://github.com/go-task/snap/blob/main/snap/snapcraft.yaml#L2
[snapcraftdashboard]: https://snapcraft.io/task/releases

230
website/src/docs/styleguide.md Normal file
View File

@@ -0,0 +1,230 @@
---
title: Style Guide
description:
Official style guide for Taskfile.yml files with best practices and
recommended conventions
outline: deep
---
# 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 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
or want to. Any improvements to this guide are welcome! Please open an issue or
create a pull request to contribute.
## Use the suggested ordering of the main sections
```yaml
version:
includes:
# optional configurations (output, silent, method, run, etc.)
vars:
env: # followed or replaced by dotenv
tasks:
```
## Use two spaces for indentation
This is the most common convention for YAML files, and Task follows it.
```yaml
# bad
tasks:
foo:
cmds:
- echo 'foo'
# good
tasks:
foo:
cmds:
- echo 'foo'
```
## Separate the main sections with empty lines
```yaml
# bad
version: '3'
includes:
docker: ./docker/Taskfile.yml
output: prefixed
vars:
FOO: bar
env:
BAR: baz
tasks:
# ...
# good
version: '3'
includes:
docker: ./docker/Taskfile.yml
output: prefixed
vars:
FOO: bar
env:
BAR: baz
tasks:
# ...
```
## Separate tasks with empty lines
```yaml
# bad
version: '3'
tasks:
foo:
cmds:
- echo 'foo'
bar:
cmds:
- echo 'bar'
baz:
cmds:
- echo 'baz'
# good
version: '3'
tasks:
foo:
cmds:
- echo 'foo'
bar:
cmds:
- echo 'bar'
baz:
cmds:
- echo 'baz'
```
## Use only uppercase letters for variable names
```yaml
# bad
version: '3'
vars:
binary_name: myapp
tasks:
build:
cmds:
- go build -o {{.binary_name}} .
# good
version: '3'
vars:
BINARY_NAME: myapp
tasks:
build:
cmds:
- go build -o {{.BINARY_NAME}} .
```
## Avoid using whitespace when templating variables
```yaml
# bad
version: '3'
tasks:
greet:
cmds:
- echo '{{ .MESSAGE }}'
# good
version: '3'
tasks:
greet:
cmds:
- echo '{{.MESSAGE}}'
```
This convention is also commonly used in templates for the Go programming
language.
## Use kebab case for task names
```yaml
# bad
version: '3'
tasks:
do_something_fancy:
cmds:
- echo 'Do something'
# good
version: '3'
tasks:
do-something-fancy:
cmds:
- echo 'Do something'
```
## Use a colon to separate the task namespace and name
```yaml
# good
version: '3'
tasks:
docker:build:
cmds:
- docker ...
docker:run:
cmds:
- docker-compose ...
```
This is also done automatically when using included Taskfiles.
## Prefer using external scripts instead of multi-line commands
```yaml
# bad
version: '3'
tasks:
build:
cmds:
- |
for i in $(seq 1 10); do
echo $i
echo "some other complex logic"
done'
# good
version: '3'
tasks:
build:
cmds:
- ./scripts/my_complex_script.sh
```

75
website/src/docs/taskfile-versions.md Normal file
View File

@@ -0,0 +1,75 @@
---
title: Taskfile Versions
description:
How to use the Taskfile schema version to ensure users are using the correct
versions of Task
outline: deep
---
# Taskfile Versions
The Taskfile schema slowly changes as new features are added and old ones are
removed. This document explains how to use a Taskfile's schema version to ensure
that the users of your Taskfile are using the correct versions of Task.
## What the Taskfile version means
The schema version at the top of every Taskfile corresponds to a version of the
Task CLI, and by extension, the features that are provided by that version. When
creating a Taskfile, you should specify the _minimum_ version of Task that
supports the features you require. If you try to run a Taskfile with a version
of Task that does not meet this minimum required version, it will exit with an
error. For example, given a Taskfile that starts with:
```yaml
version: '3.2.1'
```
When executed with Task `v3.2.0`, it will exit with an error. Running with
version `v3.2.1` or higher will work as expected.
Task accepts any [SemVer][semver] compatible string including versions which
omit the minor or patch numbers. For example, `3`, `3.0`, and `3.0.0` all mean
the same thing and are all valid. Most Taskfiles only specify the major version
number. However it can be useful to be more specific when you intend to share a
Taskfile with others.
For example, the Taskfile below makes use of aliases:
```yaml
version: '3'
tasks:
hello:
aliases:
- hi
- hey
cmds:
- echo "Hello, world!"
```
Aliases were introduced in Task `v3.17.0`, but the Taskfile only specifies `3`
as the version. This means that a user who has `v3.16.0` or lower installed will
get a potentially confusing error message when trying to run the Task as the
Taskfile specifies that any version greater or equal to `v3.0.0` is fine.
Instead, we should start the file like this:
```yaml
version: '3.17'
```
Now when someone tries to run the Taskfile with an older version of Task, they
will receive an error prompting them to upgrade their version of Task to
`v3.17.0` or greater.
## Versions 1 & 2
Version 1 and 2 of Task are no longer officially supported and anyone still
using them is strongly encouraged to upgrade to the latest version of Task.
While `version: 2` of Task did support schema versions, the behavior did not
work in quite the same way and cannot be relied upon for the purposes discussed
above.
[semver]: https://semver.org/