What is the improvement or update you wish to see?

I would like to see a better explanation of how affected behaves, or renaming of the flag.

when I see turbo run test --affected, I read this as saying "run all test tasks in projects that are affected by the changes between main and HEAD"

However, what it actually means is "run all tests in projects that were changed between main and HEAD"

This is a very distinct difference. I expect --affected to correlate with --filter=...[main...HEAD] but it is actually --filter=[main...HEAD]

Is there any context that might help us understand?

We have been using --affected in our CI workflows for months, and kept running into issues where changes to our UI library were not triggering test runs in our dependant apps. This started a whole debate around how --affected wasn't reliable and doesn't work. It turns out it does work as implemented, it's just the name is misleading. We have now updated our CI workflows to use --filter=...[main...HEAD] and are seeing the results we expected.

According to the documentation:

Automatically filter to only packages that are affected by changes on the current branch.

If a package dependency has been changed, then the dependant package is affected by that change.

Either --affected was should be named --changed, or the documentation should be clearer. Better yet, the --affected implementation could be changed to do what it claims to do, and run against packages that are affected by the changes on the current branch.

Does the docs page already exist? Please link to it.

https://turbo.build/repo/docs/reference/run#--affected