[vmaerten]

Summary

Problem

Customising a shared Taskfile locally today means copying the whole file over a .dist variant (see #1873).

Solution

When Task discovers the root Taskfile itself, it now also loads an optional Taskfile.override.yml next to it:

• vars and env merge by key with the override winning
• dotenv files are read first
• includes can be added but not redefined
• tasks are added or replaced whole
• other settings (output, method, run, interval, set, shopt, use_gitignore) replace the main ones.
• silent is rejected, since a plain boolean can't express turning it off and the config file already covers it.

Naming the file with --taskfile skips the override; included, remote and stdin Taskfiles never load one.

Tasks are replaced whole rather than merged field by field, so #1873's own example (overriding only a task's env) needs the value moved to a variable. The override's version must share the main Taskfile's major and not be newer, so bumping the shared Taskfile doesn't break local overrides.

Examples

Replace a task, add a personal one, change vars and env

# Taskfile.yml (committed)
version: '3'

vars:
  PORT: 3000

env:
  DATABASE_URL: postgres://localhost:5432/app

tasks:
  db:
    desc: Start the database
    cmds:
      - echo "docker compose up -d postgres"

  dev:
    desc: Run the server
    deps: [db]
    cmds:
      - echo "server on :{{.PORT}} using $DATABASE_URL"

# Taskfile.override.yml (git-ignored)
version: '3'

vars:
  PORT: 4000

env:
  DATABASE_URL: postgres://localhost:5433/app

tasks:
  db:
    desc: Start the database (Homebrew)
    cmds:
      - echo "brew services start postgresql@17"

  seed:
    desc: Load local fixtures
    cmds:
      - echo "psql $DATABASE_URL -f seed.sql"

$ task --list
task: Available tasks for this project:
* db:         Start the database (Homebrew)
* dev:        Run the server
* seed:       Load local fixtures

$ task dev
task: [db] echo "brew services start postgresql@17"
brew services start postgresql@17
task: [dev] echo "server on :4000 using $DATABASE_URL"
server on :4000 using postgres://localhost:5433/app

$ task -t Taskfile.yml dev
task: [db] echo "docker compose up -d postgres"
docker compose up -d postgres
task: [dev] echo "server on :3000 using $DATABASE_URL"
server on :3000 using postgres://localhost:5432/app

Personal dotenv, output style and an extra include

# Taskfile.yml (committed)
version: '3'

dotenv: [.env]

tasks:
  test:
    desc: Run the tests
    cmds:
      - echo "go test ./... against $API_URL"

# Taskfile.override.yml (git-ignored)
version: '3'

output: prefixed

dotenv: [.env.local]

includes:
  me: ./personal

With API_URL=https://staging.example.com in .env and API_URL=http://localhost:8080 in .env.local:

$ task --list
task: Available tasks for this project:
* test:             Run the tests
* me:standup:       Print yesterday's commits

$ task test me:standup
task: [test] echo "go test ./... against $API_URL"
[test] go test ./... against http://localhost:8080
task: [me:standup] echo "git log --since=yesterday --author=me"
[me:standup] git log --since=yesterday --author=me

TODO after merging

• JSON schema: editors won't recognise Taskfile.override.yml until SchemaStore maps it, and the main schema would accept keys the override rejects.

Test plan

• Integration tests in the CI are green.

[vmaerten]

@leaanthony Hey!

I gave the override feature a shot! I remember you were pretty interested in it.

What do you think of this proposal? Would it fit your needs?

cc @andreynering as you also followed the topic