docs: help agents unblock golangci-lint cross-worktree cache contamination - #6584
Open
janniklasrose wants to merge 2 commits into
Open
docs: help agents unblock golangci-lint cross-worktree cache contamination#6584janniklasrose wants to merge 2 commits into
janniklasrose wants to merge 2 commits into
Conversation
…ontamination golangci-lint's results cache is machine-global and shared across worktrees. It keys entries on file contents but stores each issue's absolute path, so a worktree with byte-identical packages (usually the near-static tools/ module) gets a cross-worktree cache hit and inherits another worktree's paths. When that worktree was deleted, the //nolint post-processor can't reopen the paths to apply suppressions, so suppressed issues leak through as phantom lint failures pointing at a gone path. This is a rare, known upstream trade-off (golangci/golangci-lint#6656, won't-fix). Rather than working around it in the Taskfile, document the symptom and the one-line fix (`golangci-lint cache clean`) in AGENTS.md so an agent that hits it recognizes it immediately instead of investigating the phantom issues as a real problem. Co-authored-by: Isaac <no-reply@databricks.com>
Collaborator
Integration test reportCommit: 643e121
Top 6 slowest tests (at least 2 minutes):
|
pietern
approved these changes
Sep 9, 2026
| - Use `./task test-update` to regenerate acceptance test outputs after changes. | ||
| - The CLI binary supports both `databricks` and `pipelines` command modes based on executable name. | ||
|
|
||
| **If `task lint` reports issues in files from a *different* worktree — paths under another `*.worktrees/*` directory, often one that no longer exists, typically alongside `no such file or directory` warnings — it is stale-cache contamination, not a real problem with your code. Clear the cache and re-run; do not investigate the reported issues.** golangci-lint's results cache is machine-global (`~/.cache/golangci-lint` on Linux, `~/Library/Caches/golangci-lint` on macOS) and shared across every worktree. It keys entries on file *contents* but stores each cached issue's *absolute* path, so a worktree whose packages are byte-identical to another's (usually the near-static `tools/` module) gets a cross-worktree cache hit and inherits the other worktree's paths. When that worktree was deleted, the `//nolint` post-processor can't reopen those paths to apply suppressions, so suppressed issues (e.g. `dupword`) leak through as phantom failures. This is [golangci/golangci-lint#6656](https://github.com/golangci/golangci-lint/issues/6656), closed as an accepted trade-off (won't-fix) of the shared-cache work in #6445. To unblock yourself: |
Contributor
There was a problem hiding this comment.
Could we move the analysis of the problem to a separate file for posterity?
These are expensive tokens.
Member
Author
There was a problem hiding this comment.
Probably sufficient to keep it in the PR descriptions (this and linked #5925), which is git blame-able. Slimmed down now
AGENTS.md is always in context, so drop the background (cause, upstream issue link) and keep just what an agent needs: what surfaces the phantom failures and the one-line command to clear the cache. Co-authored-by: Isaac <no-reply@databricks.com>
janniklasrose
enabled auto-merge
September 9, 2026 11:49
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a note to
AGENTS.md(Development Tips) describing golangci-lint's cross-worktree results-cache contamination: the symptom (phantomtask lintfailures pointing at files in another/deleted*.worktrees/*path, plusno such file or directorywarnings), the cause, and the one-line fix (golangci-lint cache clean).Why
golangci-lint's results cache is machine-global and shared across worktrees. It keys entries on file contents but stores each issue's absolute path, so a worktree with byte-identical packages (usually the near-static
tools/module) gets a cross-worktree cache hit and inherits another worktree's paths. If that worktree was deleted, the//nolintpost-processor can't reopen the paths to apply suppressions, so suppressed issues leak through as phantom failures. This is golangci/golangci-lint#6656, closed as an accepted trade-off (won't-fix).This is a rare, known upstream issue. Rather than work around it in the
Taskfile(superseding #5925, which is being closed), this simply documents the symptom and fix so an agent that hits it recognizes it immediately instead of investigating the phantom issues as a real problem.This pull request and its description were written by Isaac.