From c3dab802d8eacc546a7c9328cdfcd7ee363f870a Mon Sep 17 00:00:00 2001
From: Tonis Tiigi <tonistiigi@gmail.com>
Date: Thu, 27 Jan 2022 18:42:39 -0800
Subject: [PATCH] docs: add examples for bake named contexts

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>
---
 docs/reference/buildx_bake.md | 72 +++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/docs/reference/buildx_bake.md b/docs/reference/buildx_bake.md
index c693dcb8..01439f45 100644
--- a/docs/reference/buildx_bake.md
+++ b/docs/reference/buildx_bake.md
@@ -799,6 +799,78 @@ $ docker buildx bake --print app
 }
 ```
 
+### Defining additional build contexts and linking targets
+
+In addition to the main `context` key that defines the build context each target can also define additional named contexts with a map defined with key `contexts`. These values map to the `--build-context` flag in the [build command](buildx_build.md#build-context).
+
+Inside the Dockerfile these contexts can be used with the `FROM` instruction or `--from` flag.
+
+The value can be a local source directory, container image (with docker-image:// prefix), Git URL, HTTP URL or a name of another target in the Bake file (with target: prefix).
+
+#### Pinning alpine image
+
+```Dockerfile
+# Dockerfile
+FROM alpine
+RUN echo "Hello world"
+```
+
+```hcl
+# docker-bake.hcl
+target "app" {
+    contexts = {
+        alpine = "docker-image://alpine:3.13"
+    }
+}
+```
+
+#### Using a secondary source directory
+
+```Dockerfile
+# Dockerfile
+
+FROM scratch AS src
+
+FROM golang
+COPY --from=src . .
+```
+
+```hcl
+# docker-bake.hcl
+target "app" {
+    contexts = {
+        src = "../path/to/source"
+    }
+}
+```
+
+#### Using a result of one target as a base image in another target
+
+To use a result of one target as a build context of another, specity the target name with `target:` prefix.
+
+```Dockerfile
+# Dockerfile
+FROM baseapp
+RUN echo "Hello world"
+```
+
+```hcl
+# docker-bake.hcl
+
+target "base" {
+    dockerfile = "baseapp.Dockerfile"
+}
+
+target "app" {
+    contexts = {
+        baseapp = "target:base"
+    }
+}
+```
+
+Please note that in most cases you should just use a single multi-stage Dockerfile with multiple targets for similar behavior. This case is recommended when you have multiple Dockerfiles that can't be easily merged into one.
+
+
 ### Extension field with Compose
 
 [Special extension](https://github.com/compose-spec/compose-spec/blob/master/spec.md#extension)