mirror of
https://github.com/go-task/task.git
synced 2026-06-27 06:34:18 +00:00
feat: XDG taskrc config (#2380)
Co-authored-by: Valentin Maerten <maerten.valentin@gmail.com>
This commit is contained in:
Pete Davison
GitHub
@@ -1,13 +1,26 @@
|
||||
---
|
||||
title: CLI Reference
|
||||
title: Command Line Interface Reference
|
||||
description: Complete reference for Task CLI commands, flags, and exit codes
|
||||
permalink: /reference/cli/
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Command Line Interface
|
||||
# Command Line Interface Reference
|
||||
|
||||
Task CLI commands have the following syntax:
|
||||
Task has multiple ways of being configured. These methods are parsed, in
|
||||
sequence, in the following order with the highest priority last:
|
||||
|
||||
- [Environment variables](./environment.md)
|
||||
- [Configuration files](./config.md)
|
||||
- _Command-line flags_
|
||||
|
||||
In this document, we will look at the last of the three options, command-line
|
||||
flags. All CLI commands override their configuration file and environment
|
||||
variable equivalents.
|
||||
|
||||
## Format
|
||||
|
||||
Task commands have the following syntax:
|
||||
|
||||
```bash
|
||||
task [options] [tasks...] [-- CLI_ARGS...]
|
||||
@@ -16,7 +29,7 @@ task [options] [tasks...] [-- CLI_ARGS...]
|
||||
::: tip
|
||||
|
||||
If `--` is given, all remaining arguments will be assigned to a special
|
||||
`CLI_ARGS` variable
|
||||
`CLI_ARGS` variable.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
70
website/src/docs/reference/config.md
Normal file
70
website/src/docs/reference/config.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Configuration Reference
|
||||
description: Complete reference for the Task config files and env vars
|
||||
permalink: /reference/config/
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Configuration Reference
|
||||
|
||||
Task has multiple ways of being configured. These methods are parsed, in
|
||||
sequence, in the following order with the highest priority last:
|
||||
|
||||
- [Environment variables](./environment.md)
|
||||
- _Configuration files_
|
||||
- [Command-line flags](./cli.md)
|
||||
|
||||
In this document, we will look at the second of the three options, configuration
|
||||
files.
|
||||
|
||||
## File Precedence
|
||||
|
||||
Task's configuration files are named `.taskrc.yml` or `.taskrc.yaml`. Task will
|
||||
automatically look for directories containing files with these names in the
|
||||
following order with the highest priority first:
|
||||
|
||||
- Current directory (or the one specified by the `--taskfile`/`--entrypoint`
|
||||
flags).
|
||||
- Each directory walking up the file tree from the current directory (or the one
|
||||
specified by the `--taskfile`/`--entrypoint` flags) until we reach the user's
|
||||
home directory or the root directory of that drive.
|
||||
- `$XDG_CONFIG_HOME/task`.
|
||||
|
||||
All config files will be merged together into a unified config, starting with
|
||||
the lowest priority file in `$XDG_CONFIG_HOME/task` with each subsequent file
|
||||
overwriting the previous one if values are set.
|
||||
|
||||
For example, given the following files:
|
||||
|
||||
```yaml [$XDG_CONFIG_HOME/task/.taskrc.yml]
|
||||
# lowest priority global config
|
||||
option_1: foo
|
||||
option_2: foo
|
||||
option_3: foo
|
||||
```
|
||||
|
||||
```yaml [$HOME/.taskrc.yml]
|
||||
option_1: bar
|
||||
option_2: bar
|
||||
```
|
||||
|
||||
```yaml [$HOME/path/to/project/.taskrc.yml]
|
||||
# highest priority project config
|
||||
option_1: baz
|
||||
```
|
||||
|
||||
You would end up with the following configuration:
|
||||
|
||||
```yaml
|
||||
option_1: baz # Taken from $HOME/path/to/project/.taskrc.yml
|
||||
option_2: bar # Taken from $HOME/.taskrc.yml
|
||||
option_3: foo # Taken from $XDG_CONFIG_HOME/task/.taskrc.yml
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### `experiments`
|
||||
|
||||
The experiments section allows you to enable Task's experimental features. These
|
||||
options are not enumerated here. Instead, please refer to our
|
||||
[experiments documentation](../experiments/index.md) for more information.
|
||||
@@ -6,33 +6,43 @@ outline: deep
|
||||
|
||||
# Environment Reference
|
||||
|
||||
Task allows you to configure some behavior using environment variables. This
|
||||
page lists all the environment variables that Task supports.
|
||||
Task has multiple ways of being configured. These methods are parsed, in
|
||||
sequence, in the following order with the highest priority last:
|
||||
|
||||
| ENV | Default | Description |
|
||||
| ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
|
||||
| `TASK_REMOTE_DIR` | `TASK_TEMP_DIR` | Location of the remote temp dir (used for caching). Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
|
||||
| `TASK_OFFLINE` | `false` | Set the `--offline` flag through the environment variable. Only for remote experiment. CLI flag `--offline` takes precedence over the env variable |
|
||||
| `FORCE_COLOR` | | Force color output usage. |
|
||||
- _Environment variables_
|
||||
- [Configuration files](./config.md)
|
||||
- [Command-line flags](./cli.md)
|
||||
|
||||
## Custom Colors
|
||||
In this document, we will look at the first of the three options, environment
|
||||
variables. All Task-specific variables are prefixed with `TASK_` and override
|
||||
their configuration file equivalents.
|
||||
|
||||
| ENV | Default | Description |
|
||||
| --------------------------- | ------- | ----------------------- |
|
||||
| `TASK_COLOR_RESET` | `0` | Color used for white. |
|
||||
| `TASK_COLOR_RED` | `31` | Color used for red. |
|
||||
| `TASK_COLOR_GREEN` | `32` | Color used for green. |
|
||||
| `TASK_COLOR_YELLOW` | `33` | Color used for yellow. |
|
||||
| `TASK_COLOR_BLUE` | `34` | Color used for blue. |
|
||||
| `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. |
|
||||
| `TASK_COLOR_CYAN` | `36` | Color used for cyan. |
|
||||
| `TASK_COLOR_BRIGHT_RED` | `91` | Color used for red. |
|
||||
| `TASK_COLOR_BRIGHT_GREEN` | `92` | Color used for green. |
|
||||
| `TASK_COLOR_BRIGHT_YELLOW` | `93` | Color used for yellow. |
|
||||
| `TASK_COLOR_BRIGHT_BLUE` | `94` | Color used for blue. |
|
||||
| `TASK_COLOR_BRIGHT_MAGENTA` | `95` | Color used for magenta. |
|
||||
| `TASK_COLOR_BRIGHT_CYAN` | `96` | Color used for cyan. |
|
||||
## Variables
|
||||
|
||||
### `TASK_TEMP_DIR`
|
||||
|
||||
Defines the location of Task's temporary directory which is used for storing
|
||||
checksums and temporary metadata. Can be relative like `tmp/task` or absolute
|
||||
like `/tmp/.task` or `~/.task`. Relative paths are relative to the root
|
||||
Taskfile, not the working directory. Defaults to: `./.task`.
|
||||
|
||||
### `TASK_REMOTE_DIR`
|
||||
|
||||
Defines the location of Task's remote temporary directory which is used for
|
||||
caching remote files. Can be relative like `tmp/task` or absolute like
|
||||
`/tmp/.task` or `~/.task`. Relative paths are relative to the root Taskfile, not
|
||||
the working directory. Defaults to: `./.task`.
|
||||
|
||||
### `TASK_OFFLINE`
|
||||
|
||||
Set the `--offline` flag through the environment variable. Only for remote
|
||||
experiment. CLI flag `--offline` takes precedence over the env variable.
|
||||
|
||||
### `FORCE_COLOR`
|
||||
|
||||
Force color output usage.
|
||||
|
||||
### Custom Colors
|
||||
|
||||
All color variables are [ANSI color codes][ansi]. You can specify multiple codes
|
||||
separated by a semicolon. For example: `31;1` will make the text bold and red.
|
||||
@@ -45,4 +55,22 @@ For convenience, we allow foreground colors to be specified using shorthand,
|
||||
comma-separated syntax: `R,G,B`. For example, `255,0,0` is equivalent to
|
||||
`38;2;255:0:0`.
|
||||
|
||||
A table of variables and their defaults can be found below:
|
||||
|
||||
| ENV | Default |
|
||||
| --------------------------- | ------- |
|
||||
| `TASK_COLOR_RESET` | `0` |
|
||||
| `TASK_COLOR_RED` | `31` |
|
||||
| `TASK_COLOR_GREEN` | `32` |
|
||||
| `TASK_COLOR_YELLOW` | `33` |
|
||||
| `TASK_COLOR_BLUE` | `34` |
|
||||
| `TASK_COLOR_MAGENTA` | `35` |
|
||||
| `TASK_COLOR_CYAN` | `36` |
|
||||
| `TASK_COLOR_BRIGHT_RED` | `91` |
|
||||
| `TASK_COLOR_BRIGHT_GREEN` | `92` |
|
||||
| `TASK_COLOR_BRIGHT_YELLOW` | `93` |
|
||||
| `TASK_COLOR_BRIGHT_BLUE` | `94` |
|
||||
| `TASK_COLOR_BRIGHT_MAGENTA` | `95` |
|
||||
| `TASK_COLOR_BRIGHT_CYAN` | `96` |
|
||||
|
||||
[ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
title: CLI Reference
|
||||
description: Complete reference for Task CLI commands, flags, and exit codes
|
||||
title: Package API Reference
|
||||
description: A reference for Task's Golang package API
|
||||
---
|
||||
|
||||
# Package API
|
||||
# Package API Reference
|
||||
|
||||
::: warning
|
||||
|
||||
|
||||
@@ -1,11 +1,10 @@
|
||||
---
|
||||
title: Schema Reference
|
||||
description:
|
||||
Complete reference for the Taskfile schema based on the official JSON schema
|
||||
title: Taskfile Schema Reference
|
||||
description: A reference for the Taskfile schema
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Schema Reference
|
||||
# Taskfile Schema Reference
|
||||
|
||||
This page documents all available properties and types for the Taskfile schema
|
||||
version 3, based on the
|
||||
|
||||
Reference in New Issue
Block a user