docs: Clarifications for --affected. (#9078)

### Description

Title!

### Testing Instructions

👀

docs/repo-docs/crafting-your-repository/constructing-ci.mdx

@@ -46,6 +46,8 @@ You can filter your tasks using [the `--filter` flag](/repo/docs/reference/run#-
   available.
 </Callout>
 
+You can also use [the `--affected` flag](#running-only-affected-tasks) to only run tasks in packages that have changes.
+
 ## Docker
 
 Docker is an important part of many deployment pipelines. [Turborepo's `prune` subcommand](/repo/docs/reference/prune) helps you ship lightweight images by removing unnecessary dependencies and code from your images.
@@ -54,7 +56,23 @@ For more on how to deploy from a Turborepo with Docker, visit [the dedicated Doc
 
 ## Skipping tasks and other unnecessary work
 
-Using Turborepo's built-in caching is a great way to speed up your CI. We encourage you to start by relying on Turborepo's caching and parallelization when you're starting out with Turborepo.
+### Running only affected tasks
+
+You can use the `--affected` flag to only run tasks that have changes.
+
+```bash title="Terminal
+turbo run build --affected
+```
+
+You'll want to use this flag in situations like:
+
+- You're running many tasks across packages in your monorepo, and only want to run those tasks in packages with code changes.
+- You’re _not_ using a Remote Cache, but still want to do as little work as possible in CI.
+- You _are_ using a Remote Cache, and you’re in a large repository. By minimizing the amount of tasks that will be restored from cache, there will be less data to send across the network, resulting in faster cache restoration.
+- You’re already using [advanced filtering techniques](/repo/docs/reference/run#advanced-filtering-examples) or [`turbo-ignore`](/repo/docs/reference/turbo-ignore) to create the same or similar behavior as `--affected`. You likely have the opportunity to simplify your scripting using this new flag.
+  - `--affected` will can handle shallow clons more gracefully than bespoke filtering because it falls back to running all tasks.
+
+### Using `turbo-ignore`
 
 As your codebase and CI grow, you may start to look for more ways to get even faster. While hitting cache is useful, you also may be able to skip work entirely. Using `turbo-ignore`, you can skip lengthy container preparation steps like dependency installation that will end up resulting in a cache hit, anyway.
 

docs/repo-docs/reference/run.mdx

@@ -36,19 +36,26 @@ turbo run
 
 Automatically filter to only packages that are affected by changes on the current branch.
 
-By default the changes considered are those between `main` and `HEAD`.
+```bash title="Terminal"
+turbo run build lint test --affected
+```
 
-- You can override `main` as the default base by setting `TURBO_SCM_BASE`.
-- You can override `HEAD` as the default head by setting `TURBO_SCM_HEAD`.
+By default, the flag is equivalent to `--filter=[main...HEAD]`. This considers changes between `main` and `HEAD` from Git's perspective.
+
+You can override the default base and head with their respective [System Environment Variables](/repo/docs/reference/system-environment-variables).
 
 ```bash title="Terminal"
+# Override Git comparison base
 TURBO_SCM_BASE=development turbo run build --affected
+
+# Override Git comparison head
+TURBO_SCM_HEAD=your-branch turbo run build --affected
 ```
 
 <Callout type="warn">
-  Performing this comparison requires everything between base and head to exist in
-  the checkout. If the checkout is too shallow, then all packages will be
-  considered changed.
+  The comparison requires everything between base and head to exist in the
+  checkout. If the checkout is too shallow, then all packages will be considered
+  changed.
 </Callout>
 
 ### `--cache-dir <path>`