Skip to content

docs: add missing CLI/config equivalents in environment.md - #2997

Open
no-hup wants to merge 4 commits into
go-task:mainfrom
no-hup:docs/env-links
Open

docs: add missing CLI/config equivalents in environment.md#2997
no-hup wants to merge 4 commits into
go-task:mainfrom
no-hup:docs/env-links

Conversation

@no-hup

@no-hup no-hup commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

Description

Adds the missing CLI / config cross-links for a few environment variables in environment.md (TASK_CONCURRENCY, TASK_FAILFAST, TASK_DRY, TASK_ASSUME_YES, TASK_INTERACTIVE) so those entries match the rest of the page.

Checklist

  • Code compiles and passes existing tests (go test ./...)
  • Docs-only change; no behavior change
  • Tests added/updated (N/A — docs)

Disclosure: I used an AI assistant to help spot the missing cross-links and draft this change. I've checked the targets against cli.md / config.md and I'm happy to revise anything.

@trulede trulede left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You (or the AI) have missed quite a few ... I would suggest auditing the entire CLI / Environment / Configuration (against the code base) to identify all the missing items, and then see about getting the cross references correct.

Audit every TASK_ variable against internal/flags/flags.go and add the
missing CLI and config equivalents. Also fix the TASK_OUTPUT link, which
pointed at a non-existent #--output-string anchor.
@no-hup

no-hup commented Sep 2, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, that's fair — I'd only patched the entries I happened to be looking at. I went back through the whole Environment reference and cross-checked every TASK_ variable against internal/flags/flags.go, where the flag ↔ env var ↔ config mapping actually lives (the getConfig calls).

What this update fixes:

  • Added the missing CLI equivalents to TASK_VERBOSE, TASK_SILENT, TASK_COLOR and TASK_DISABLE_FUZZY.
  • TASK_OUTPUT linked to #--output-string, which doesn't exist — corrected it to #-o---output-mode.
  • Added CLI + config cross-refs to TASK_TEMP_DIR and the whole remote block (TASK_REMOTE_INSECURE, _OFFLINE, _TIMEOUT, _CACHE_EXPIRY, _CACHE_DIR, _TRUSTED_HOSTS, _CACERT, _CERT, _CERT_KEY).
  • Left TASK_CORE_UTILS, FORCE_COLOR and the TASK_COLOR_* table alone, since they have no flag or config counterpart.

I checked that every new anchor resolves against the current cli.md / config.md headings.

Two things I noticed while doing this but didn't want to fold in without asking:

  1. The reverse direction has gaps too — cli.md's Remote section (--insecure--cert-key) and a few config.md entries (remote.cacert / remote.cert / remote.cert-key, temp-dir's CLI link, interactive's env var) are missing their cross-refs. Happy to fix those here or in a separate PR, whichever you'd prefer.
  2. internal/flags/flags.go reads TASK_REMOTE_DIR as the fallback for --remote-cache-dir, alongside TASK_REMOTE_CACHE_DIR, but it isn't documented anywhere. Is that an intentional legacy alias, or should it be listed?

Disclosure: I use an AI assistant to help with these changes; I've reviewed and verified everything above and can explain or revise any of it.

The anchors added in this branch used the `#--flag-name` style that
already existed in these pages, but VitePress strips leading hyphens
when it slugifies a heading, so every one of them was dead. go-task#3004 had
just fixed four of the pre-existing ones the same way.

- environment.md: repair 19 anchors, document NO_COLOR and CI (both are
  read in internal/flags/flags.go and NO_COLOR takes precedence over the
  already-documented FORCE_COLOR)
- cli.md: the Remote section had no cross-references at all; 9 of its 11
  flags have both a config key and an env var, so link them
- config.md: interactive was missing its env var, temp-dir its CLI flag,
  and remote.cacert/cert/cert-key had neither
@no-hup

no-hup commented Sep 2, 2026

Copy link
Copy Markdown
Contributor Author

I have to correct my last comment. I said all the anchors resolved and that I'd verified it. That was wrong, and the way it was wrong is worth saying out loud: 19 of the links I added were dead.

I'd copied the #--flag-name style that was already in these pages, not realising VitePress strips leading hyphens when it slugifies, so ./cli.md#-v---verbose never pointed at anything. #3004 had just fixed four of the pre-existing ones the same way and I read straight past it. The check I ran used my own slug rule rather than mdit-vue's, so it agreed with me. I've rewritten it to match the real slugifier and sanity-checked it by running it against main first, where it reports zero bad links across all three reference pages and reproduces the anchors you'd hand-written in #3004. Only then did I run it on this branch.

Rebased on main and done the full audit against internal/flags/flags.go this time, across all three pages you named:

  • environment.md — the 19 anchors are fixed. Added NO_COLOR and a note on CI; both are read in the colour auto-detect block, and NO_COLOR actually takes precedence over FORCE_COLOR, which was already documented while NO_COLOR wasn't.
  • cli.md — the whole Remote section had no cross-references. Nine of those flags have both a config key and an env var, so they're linked now. --download and --clear-cache have neither, so I left them.
  • config.mdinteractive was missing its env var, temp-dir its CLI flag, and remote.cacert / remote.cert / remote.cert-key had neither.

Validator is clean on the merged tree. Nothing in latest/.

One thing I didn't touch: TASK_REMOTE_DIR is read as the fallback default for --remote-cache-dir but isn't documented anywhere. Deliberate, or should it get an entry?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants