Dan Streetman (ddstreet) · Oct 21, 2026 · Oct 27, 2026
diff --git a/docs/user/how-to/build-component.md b/docs/user/how-to/build-component.md
@@ -32,6 +32,7 @@ Built packages are placed in structured subdirectories under the project's outpu
 | `--srpm-only` | Build only the SRPM, not the binary RPMs |
 | `--preserve-buildenv on-failure` | Keep the mock chroot on build failure for debugging |
 | `--continue-on-error` / `-k` | Continue building remaining components if one fails |
+| `--unique-mockroot` | Use distinct mock roots instead of the shared default root |
 | `--local-repo <path>` | Add a local RPM repository for build dependencies |
 | `--local-repo-with-publish <path>` | Use a local repo and publish built RPMs into it |
 
@@ -49,6 +50,39 @@ azldev comp build --local-repo-with-publish ./base/out -p dep-package -p main-pa
 2. Enter the chroot with `azldev adv mock shell` to inspect the build environment
 3. Check build logs in the project's log directory
 
+## Isolate Mock Roots
+
+Use the global `--unique-mockroot` flag to avoid sharing mock roots with other
+azldev operations:
+
+```bash
+azldev --unique-mockroot comp build -p curl
+azldev --unique-mockroot comp render -p curl -p zlib
+```
+
+Each mock runner passes `--uniqueext` with an extension of at most 24 ASCII
+characters: an abbreviated action, a component label of up to 12 characters,
+and six random characters, for example `bld-curl-a2b3c4`.
+An extension such as `rndr-abcdefghijkl-a2b3c4` uses the full 24-character limit.
+Action codes are `bld` for builds (including advanced mock builds), `rndr` for
+rendering, `qry` for queries, and `shl` for mock shells with or without packages.
+These codes are never shortened further. Other actions use an abbreviated
+command name.
+
+Batch roots label the first component and include the component count when it
+fits; otherwise they use the abbreviated first component without the count.
+Labels use letters, digits, `_`, and `-`, never spaces.
+The extension stays the same for initialization, commands, and cleanup of that
+root; separate roots receive separate random suffixes. Without the flag,
+mock's existing root naming is unchanged.
+
+The flag also applies to queries, custom source generation, and
+`azldev advanced mock` commands. A unique `mock shell` session does not reuse a
+previous session's root. To inspect a preserved unique build root, take its
+`--uniqueext` value from the verbose command log and run
+`mock -r <mock-config> --uniqueext <extension> --shell` directly; a new azldev
+invocation generates a new extension.
+
 ## Related Resources
 
 - [Components Reference](../reference/config/components.md) — component definition format

diff --git a/docs/user/reference/cli/azldev.md b/docs/user/reference/cli/azldev.md
diff --git a/docs/user/reference/cli/azldev_advanced.md b/docs/user/reference/cli/azldev_advanced.md
diff --git a/docs/user/reference/cli/azldev_advanced_download-sources.md b/docs/user/reference/cli/azldev_advanced_download-sources.md
diff --git a/docs/user/reference/cli/azldev_advanced_mcp.md b/docs/user/reference/cli/azldev_advanced_mcp.md
diff --git a/docs/user/reference/cli/azldev_advanced_mock.md b/docs/user/reference/cli/azldev_advanced_mock.md
diff --git a/docs/user/reference/cli/azldev_advanced_mock_build-rpms.md b/docs/user/reference/cli/azldev_advanced_mock_build-rpms.md
diff --git a/docs/user/reference/cli/azldev_advanced_mock_shell.md b/docs/user/reference/cli/azldev_advanced_mock_shell.md
diff --git a/docs/user/reference/cli/azldev_advanced_wget.md b/docs/user/reference/cli/azldev_advanced_wget.md
diff --git a/docs/user/reference/cli/azldev_completion.md b/docs/user/reference/cli/azldev_completion.md
diff --git a/docs/user/reference/cli/azldev_completion_bash.md b/docs/user/reference/cli/azldev_completion_bash.md
diff --git a/docs/user/reference/cli/azldev_completion_fish.md b/docs/user/reference/cli/azldev_completion_fish.md
diff --git a/docs/user/reference/cli/azldev_completion_powershell.md b/docs/user/reference/cli/azldev_completion_powershell.md
diff --git a/docs/user/reference/cli/azldev_completion_zsh.md b/docs/user/reference/cli/azldev_completion_zsh.md
diff --git a/docs/user/reference/cli/azldev_component.md b/docs/user/reference/cli/azldev_component.md
diff --git a/docs/user/reference/cli/azldev_component_add.md b/docs/user/reference/cli/azldev_component_add.md
diff --git a/docs/user/reference/cli/azldev_component_build.md b/docs/user/reference/cli/azldev_component_build.md
diff --git a/docs/user/reference/cli/azldev_component_changed.md b/docs/user/reference/cli/azldev_component_changed.md
diff --git a/docs/user/reference/cli/azldev_component_diff-sources.md b/docs/user/reference/cli/azldev_component_diff-sources.md
diff --git a/docs/user/reference/cli/azldev_component_history.md b/docs/user/reference/cli/azldev_component_history.md
diff --git a/docs/user/reference/cli/azldev_component_list.md b/docs/user/reference/cli/azldev_component_list.md
diff --git a/docs/user/reference/cli/azldev_component_metadata.md b/docs/user/reference/cli/azldev_component_metadata.md
diff --git a/docs/user/reference/cli/azldev_component_prepare-sources.md b/docs/user/reference/cli/azldev_component_prepare-sources.md
diff --git a/docs/user/reference/cli/azldev_component_query.md b/docs/user/reference/cli/azldev_component_query.md
diff --git a/docs/user/reference/cli/azldev_component_render.md b/docs/user/reference/cli/azldev_component_render.md
diff --git a/docs/user/reference/cli/azldev_component_test.md b/docs/user/reference/cli/azldev_component_test.md
diff --git a/docs/user/reference/cli/azldev_component_update.md b/docs/user/reference/cli/azldev_component_update.md
diff --git a/docs/user/reference/cli/azldev_config.md b/docs/user/reference/cli/azldev_config.md
diff --git a/docs/user/reference/cli/azldev_config_dump.md b/docs/user/reference/cli/azldev_config_dump.md
diff --git a/docs/user/reference/cli/azldev_config_generate-schema.md b/docs/user/reference/cli/azldev_config_generate-schema.md
diff --git a/docs/user/reference/cli/azldev_docs.md b/docs/user/reference/cli/azldev_docs.md