From e9234d599c75a90ec0778f75d9db4c056b996cd2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 15 Jul 2026 14:10:37 +0000
Subject: [PATCH 1/2] docs(go example): document GOPATH/GOROOT and warn against
 GOPATH=$PWD

The Go example's README did not explain its environment configuration, and
the in-repo example (GOPATH=$HOME/go) diverges from the website docs example
(GOPATH=$PWD), which caused confusion (#2640).

Setting GOPATH to the project directory is incorrect for module-based
projects: when a go.mod lives inside GOPATH, the toolchain prints
'go: warning: ignoring go.mod in $GOPATH' and falls back to legacy GOPATH
mode. Document the recommended $HOME/go configuration and the reason to
avoid $PWD.

Fixes #2640

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HVAMekrsEQLDoiD6dp8Pi
---
 examples/development/go/hello-world/README.md | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/examples/development/go/hello-world/README.md b/examples/development/go/hello-world/README.md
index a116931b490..a84a6c36be0 100644
--- a/examples/development/go/hello-world/README.md
+++ b/examples/development/go/hello-world/README.md
@@ -26,3 +26,38 @@ If you need additional C libraries, you can add them along with `gcc` to your pa
     "libcap"
 ]
 ```
+
+## Setting up the Go environment
+
+This example configures a few environment variables in `devbox.json`:
+
+```json
+"env": {
+    "GOPATH": "$HOME/go/",
+    "PATH":   "$PATH:$HOME/go/bin"
+}
+```
+
+- `GOPATH` is set to `$HOME/go`, which is Go's default location. Keeping the
+  `GOPATH` outside of your project directory lets the module cache
+  (`$GOPATH/pkg/mod`) be shared across projects and keeps build artifacts out of
+  your source tree.
+- Adding `$GOPATH/bin` to `PATH` makes tools installed with `go install`
+  available inside the Devbox shell.
+
+The `init_hook` exports `GOROOT` so that the Go toolchain provided by Nix is
+used:
+
+```json
+"shell": {
+    "init_hook": [
+        "export \"GOROOT=$(go env GOROOT)\""
+    ]
+}
+```
+
+> **Note on `GOPATH`:** avoid setting `GOPATH` to your project directory (e.g.
+> `"GOPATH": "$PWD"`). When a module (a directory containing `go.mod`) lives
+> inside `GOPATH`, the Go toolchain prints `go: warning: ignoring go.mod in
+> $GOPATH` and falls back to legacy `GOPATH` mode. Using `$HOME/go` (as above)
+> keeps module-aware builds working as expected.

From 944448d3a24d5761ca221411ef8fb0285160f1ef Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 15 Jul 2026 14:13:48 +0000
Subject: [PATCH 2/2] docs(go example): clarify GOROOT wording and fix warning
 code block

Address review feedback:
- GOROOT does not select the toolchain (PATH does); reword to say the
  init_hook sets GOROOT to match the Nix-provided Go for tooling compatibility.
- Move the 'ignoring go.mod in $GOPATH' warning into a fenced code block so
  the inline span no longer wraps across a blockquote line break.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HVAMekrsEQLDoiD6dp8Pi
---
 examples/development/go/hello-world/README.md | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/examples/development/go/hello-world/README.md b/examples/development/go/hello-world/README.md
index a84a6c36be0..3b6fd25eaa6 100644
--- a/examples/development/go/hello-world/README.md
+++ b/examples/development/go/hello-world/README.md
@@ -45,8 +45,9 @@ This example configures a few environment variables in `devbox.json`:
 - Adding `$GOPATH/bin` to `PATH` makes tools installed with `go install`
   available inside the Devbox shell.
 
-The `init_hook` exports `GOROOT` so that the Go toolchain provided by Nix is
-used:
+Which Go toolchain is active is determined by the `go` binary on `PATH` (here,
+the one provided by Nix). The `init_hook` sets `GOROOT` to match that
+installation, which some tooling relies on:
 
 ```json
 "shell": {
@@ -58,6 +59,11 @@ used:
 
 > **Note on `GOPATH`:** avoid setting `GOPATH` to your project directory (e.g.
 > `"GOPATH": "$PWD"`). When a module (a directory containing `go.mod`) lives
-> inside `GOPATH`, the Go toolchain prints `go: warning: ignoring go.mod in
-> $GOPATH` and falls back to legacy `GOPATH` mode. Using `$HOME/go` (as above)
-> keeps module-aware builds working as expected.
+> inside `GOPATH`, the Go toolchain falls back to legacy `GOPATH` mode and
+> prints a warning:
+>
+> ```
+> go: warning: ignoring go.mod in $GOPATH /path/to/your/project
+> ```
+>
+> Using `$HOME/go` (as above) keeps module-aware builds working as expected.