From 0d279f3bec28ad65997c60fd58c2dd096847fde1 Mon Sep 17 00:00:00 2001
From: dannark <dannark@google.com>
Date: Tue, 17 Jul 2018 11:49:49 -0700
Subject: Add doc about repo_mapping

RELNOTES: None
PiperOrigin-RevId: 204948309
---
 site/docs/external.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/site/docs/external.md b/site/docs/external.md
index 180011eea2..96d9868838 100644
--- a/site/docs/external.md
+++ b/site/docs/external.md
@@ -133,6 +133,82 @@ By default, external dependencies are fetched as needed during `bazel build`. If
 you would like to disable this behavior or prefetch dependencies, use
 [`bazel fetch`](http://docs.bazel.build/user-manual.html#fetch).
 
+## Shadowing dependencies
+
+Whenever possible, it is recommended to have a single version policy in your
+project. This is required for dependencies that you compile against and end up
+in your final binary. But for cases where this isn't true, it is possible to
+shadow dependencies. Consider the following scenario:
+
+myproject/WORKSPACE
+```python
+local_repository(
+    name = "A",
+    path = "../A",
+)
+local_repository(
+    name = "B",
+    path = "../B",
+)
+```
+
+A/WORKSPACE
+```python
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+http_archive(
+    name = "testrunner",
+    urls = ["https://github.com/testrunner/v1.zip"],
+    sha256 = "...",
+)
+```
+
+B/WORKSPACE
+```python
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+http_archive(
+    name = "testrunner",
+    urls = ["https://github.com/testrunner/v2.zip"],
+    sha256 = "..."
+)
+```
+
+Both dependencies `A` and `B` depend on `testrunner`, but they depend on
+different versions of `testrunner`. There is no reason for these test runners to
+not peacefully coexist within `myproject`, however they will clash with each
+other since they have the same name. To declare both dependencies,
+update myproject/WORKSPACE:
+```python
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+http_archive(
+    name = "testrunner-v1",
+    urls = ["https://github.com/testrunner/v1.zip"],
+    sha256 = "..."
+)
+http_archive(
+    name = "testrunner-v2",
+    urls = ["https://github.com/testrunner/v2.zip"],
+    sha256 = "..."
+)
+local_repository(
+    name = "A",
+    path = "../A",
+    repo_mapping = {"@testrunner" : "@testrunner-v1"}
+)
+local_repository(
+    name = "B",
+    path = "../B",
+    repo_mapping = {"@testrunner" : "@testrunner-v2"}
+)
+```
+
+This mechanism can also be used to join diamonds. For example if `A` and `B`
+had the same dependency but call it by different names, those dependencies can
+be joined in myproject/WORKSPACE.
+
+This behavior is currently gated behind a flag,
+`--experimental_enable_repo_mapping`.
+
+
 ## Using Proxies
 
 Bazel will pick up proxy addresses from the `HTTPS_PROXY` and `HTTP_PROXY`
-- 
cgit v1.2.3