mirror of
https://github.com/go-task/task.git
synced 2026-06-11 09:51:50 +00:00
docs(experiments): add SCOPED_TASKFILES documentation
Document the new experiment with:
- Environment namespace ({{.env.XXX}}) explanation
- Variable scoping between includes
- CLI variables priority
- Migration guide from legacy mode
- Comparison table between legacy and scoped modes
This commit is contained in:
Valentin Maerten
@@ -302,6 +302,10 @@ export default defineConfig({
|
||||
{
|
||||
text: 'Remote Taskfiles (#1317)',
|
||||
link: '/docs/experiments/remote-taskfiles'
|
||||
},
|
||||
{
|
||||
text: 'Scoped Taskfiles',
|
||||
link: '/docs/experiments/scoped-taskfiles'
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
201
website/src/docs/experiments/scoped-taskfiles.md
Normal file
201
website/src/docs/experiments/scoped-taskfiles.md
Normal file
@@ -0,0 +1,201 @@
|
||||
---
|
||||
title: 'Scoped Taskfiles'
|
||||
description:
|
||||
Experiment for variable isolation and env namespace in included Taskfiles
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Scoped Taskfiles
|
||||
|
||||
::: 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 variables are no longer available at root level in templates**
|
||||
- Before: <span v-pre>`{{.PATH}}`</span>, <span v-pre>`{{.MY_ENV}}`</span>
|
||||
- After: <span v-pre>`{{.env.PATH}}`</span>,
|
||||
<span v-pre>`{{.env.MY_ENV}}`</span>
|
||||
- **Variables from sibling includes are no longer visible**
|
||||
- Include A cannot access variables defined in Include B
|
||||
- Each include only sees: root vars + its own vars + parent vars
|
||||
|
||||
:::
|
||||
|
||||
::: info
|
||||
|
||||
To enable this experiment, set the environment variable:
|
||||
`TASK_X_SCOPED_TASKFILES=1`. Check out
|
||||
[our guide to enabling experiments](./index.md#enabling-experiments) for more
|
||||
information.
|
||||
|
||||
:::
|
||||
|
||||
This experiment introduces two major changes to how variables work in Task:
|
||||
|
||||
1. **Environment namespace**: Environment variables (both OS and Taskfile `env:`
|
||||
sections) are moved to a dedicated <span v-pre>`{{.env.XXX}}`</span>
|
||||
namespace, separating them from regular variables
|
||||
2. **Variable scoping**: Variables defined in included Taskfiles are isolated -
|
||||
sibling includes cannot see each other's variables
|
||||
|
||||
## Environment Namespace
|
||||
|
||||
With this experiment enabled, environment variables are no longer mixed with
|
||||
regular variables at the template root level. Instead, they are accessible
|
||||
through the <span v-pre>`{{.env.XXX}}`</span> namespace.
|
||||
|
||||
### Comparison Table
|
||||
|
||||
| Template | Legacy | SCOPED_TASKFILES |
|
||||
| ----------------------------------------------- | ------ | ------------------------- |
|
||||
| <span v-pre>`{{.MY_VAR}}`</span> (from `vars:`) | Works | Works |
|
||||
| <span v-pre>`{{.MY_ENV}}`</span> (from `env:`) | Works | `<no value>` |
|
||||
| <span v-pre>`{{.env.MY_ENV}}`</span> | - | Works |
|
||||
| <span v-pre>`{{.PATH}}`</span> (OS) | Works | `<no value>` |
|
||||
| <span v-pre>`{{.env.PATH}}`</span> (OS) | - | Works |
|
||||
| <span v-pre>`{{.TASK}}`</span> (special) | Works | Works (stays at root) |
|
||||
|
||||
### Example
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
env:
|
||||
DB_HOST: localhost
|
||||
|
||||
vars:
|
||||
DB_NAME: mydb
|
||||
|
||||
tasks:
|
||||
show:
|
||||
cmds:
|
||||
# Access Taskfile env: section
|
||||
- echo "Host: {{.env.DB_HOST}}"
|
||||
|
||||
# Access regular vars (unchanged)
|
||||
- echo "Name: {{.DB_NAME}}"
|
||||
|
||||
# Access OS environment variables
|
||||
- echo "Path: {{.env.PATH}}"
|
||||
|
||||
# Special variables stay at root level
|
||||
- echo "Task: {{.TASK}}"
|
||||
```
|
||||
|
||||
## Variable Scoping
|
||||
|
||||
Variables defined in included Taskfiles are now isolated from each other.
|
||||
Sibling includes cannot access each other's variables, but child includes can
|
||||
still inherit variables from their parent.
|
||||
|
||||
### Example
|
||||
|
||||
```yaml
|
||||
# Taskfile.yml
|
||||
version: '3'
|
||||
|
||||
vars:
|
||||
ROOT_VAR: from_root
|
||||
|
||||
includes:
|
||||
api: ./api
|
||||
web: ./web
|
||||
```
|
||||
|
||||
```yaml
|
||||
# api/Taskfile.yml
|
||||
version: '3'
|
||||
|
||||
vars:
|
||||
API_VAR: from_api
|
||||
|
||||
tasks:
|
||||
show:
|
||||
cmds:
|
||||
# Inherited from root - works
|
||||
- echo "ROOT_VAR={{.ROOT_VAR}}"
|
||||
|
||||
# Own variable - works
|
||||
- echo "API_VAR={{.API_VAR}}"
|
||||
|
||||
# From sibling include - NOT visible
|
||||
- echo "WEB_VAR={{.WEB_VAR}}"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# web/Taskfile.yml
|
||||
version: '3'
|
||||
|
||||
vars:
|
||||
WEB_VAR: from_web
|
||||
|
||||
tasks:
|
||||
show:
|
||||
cmds:
|
||||
# Inherited from root - works
|
||||
- echo "ROOT_VAR={{.ROOT_VAR}}"
|
||||
|
||||
# Own variable - works
|
||||
- echo "WEB_VAR={{.WEB_VAR}}"
|
||||
|
||||
# From sibling include - NOT visible
|
||||
- echo "API_VAR={{.API_VAR}}"
|
||||
```
|
||||
|
||||
## CLI Variables Priority
|
||||
|
||||
With this experiment, CLI variables (passed as `task foo VAR=value`) have the
|
||||
highest priority and will override task-level variables.
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
tasks:
|
||||
greet:
|
||||
vars:
|
||||
NAME: from_task
|
||||
cmds:
|
||||
- echo "Hello {{.NAME}}"
|
||||
```
|
||||
|
||||
```bash
|
||||
# CLI vars now override task vars
|
||||
TASK_X_SCOPED_TASKFILES=1 task greet NAME=cli
|
||||
# Output: Hello cli
|
||||
```
|
||||
|
||||
## Migration Guide
|
||||
|
||||
To migrate your Taskfiles to use this experiment:
|
||||
|
||||
1. **Update environment variable references** in your templates:
|
||||
|
||||
- <span v-pre>`{{.PATH}}`</span> becomes
|
||||
<span v-pre>`{{.env.PATH}}`</span>
|
||||
- <span v-pre>`{{.HOME}}`</span> becomes
|
||||
<span v-pre>`{{.env.HOME}}`</span>
|
||||
- <span v-pre>`{{.MY_TASKFILE_ENV}}`</span> becomes
|
||||
<span v-pre>`{{.env.MY_TASKFILE_ENV}}`</span>
|
||||
|
||||
2. **Variables in `vars:` sections remain unchanged**:
|
||||
|
||||
- <span v-pre>`{{.MY_VAR}}`</span> still works the same way
|
||||
|
||||
3. **Special variables stay at root level**:
|
||||
|
||||
- <span v-pre>`{{.TASK}}`</span>, <span v-pre>`{{.ROOT_DIR}}`</span>,
|
||||
<span v-pre>`{{.TASKFILE}}`</span>, <span v-pre>`{{.TASKFILE_DIR}}`</span>,
|
||||
etc.
|
||||
|
||||
4. **Review cross-include variable dependencies**:
|
||||
- If your included Taskfiles rely on variables from sibling includes, you'll
|
||||
need to either move those variables to the root Taskfile or pass them
|
||||
explicitly via the `vars:` attribute in the `includes:` section.
|
||||
Reference in New Issue
Block a user