From 68d36dd0b800706e8eddcfef07df9295f9978bf4 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 28 Sep 2022 20:46:31 -0500
Subject: [PATCH] Explain how to handle ambiguous local environments (#17048)

See https://github.com/pantsbuild/pants/pull/17043 for a demo of this, and an explanation why we take this approach.

[ci skip-rust]
[ci skip-build-wheels]
---
 .../pants/core/util_rules/environments.py     | 20 ++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/src/python/pants/core/util_rules/environments.py b/src/python/pants/core/util_rules/environments.py
index dd293ef7635..3d35e83c6a3 100644
--- a/src/python/pants/core/util_rules/environments.py
+++ b/src/python/pants/core/util_rules/environments.py
@@ -416,7 +416,6 @@ async def determine_local_environment(
         result_name, _tgt = compatible_name_and_targets[0]
         return ChosenLocalEnvironmentName(result_name)
 
-    # TODO(#7735): Maybe allow the user to disambiguate what __local__ means via an option?
     raise AmbiguousEnvironmentError(
         softwrap(
             f"""
@@ -428,6 +427,25 @@ async def determine_local_environment(
             To fix, either adjust the `{CompatiblePlatformsField.alias}` field from those
             targets so that only one includes the value `{platform.value}`, or change
             `[environments-preview].names` so that it does not define some of those targets.
+
+            It is often useful to still keep the same `local_environment` target definitions in
+            BUILD files; instead, do not give a name to each of them in
+            `[environments-preview].names` to avoid ambiguity. Then, you can override which target
+            a particular name points to by overriding `[environments-preview].names`. For example,
+            you could set this in `pants.toml`:
+
+                [environments-preview.names]
+                linux = "//:linux_env"
+                macos = "//:macos_local_env"
+
+            Then, for CI, override what the name `macos` points to by setting this in
+            `pants.ci.toml`:
+
+                [environments-preview.names.add]
+                macos = "//:macos_ci_env"
+
+            Locally, you can override `[environments-preview].names` like this by using a
+            `.pants.rc` file, for example.
             """
         )
     )