cmd/go: add documentation for the -overlay flag

Also add -overlay to the Go 1.16 release notes.

For #40700
Fixes #39958
Fixes #42893

Change-Id: Ifd397549e368b255e7b8800986cfa0563a942af5
Reviewed-on: https://go-review.googlesource.com/c/go/+/274714
Trust: Michael Matloob <matloob@golang.org>
Run-TryBot: Michael Matloob <matloob@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Jay Conrod <jayconrod@google.com>

1 files changed, 11 insertions, 0 deletions

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index daa407197c..c4913ce695 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -164,6 +164,17 @@
 // 		directory, but it is not accessed. When -modfile is specified, an
 // 		alternate go.sum file is also used: its path is derived from the
 // 		-modfile flag by trimming the ".mod" extension and appending ".sum".
+// 	-overlay file
+// 		read a JSON config file that provides an overlay for build operations.
+// 		The file is a JSON struct with a single field, named 'Replace', that
+// 		maps each disk file path (a string) to its backing file path, so that
+// 		a build will run as if the disk file path exists with the contents
+// 		given by the backing file paths, or as if the disk file path does not
+// 		exist if its backing file path is empty. Support for the -overlay flag
+// 		has some limitations:importantly, cgo files included from outside the
+// 		include path must be  in the same directory as the Go package they are
+// 		included from, and overlays will not appear when binaries and tests are
+// 		run through go run and go test respectively.
 // 	-pkgdir dir
 // 		install and load all packages from dir instead of the usual locations.
 // 		For example, when building with a non-standard configuration,