From e1a5f0380096210af28ee0c1203d98e4e99c209b Mon Sep 17 00:00:00 2001
From: Lohit Kolluri <lohitkolluri@gmail.com>
Date: Sun, 28 Jun 2026 02:15:53 +0530
Subject: [PATCH] hack: scope docs validation and show diff on failure

Tighten the validate stage of the docs Dockerfile:

- Drop the unscoped `git add -A`; the validation is a working-tree-vs-HEAD
  check, which `git status --porcelain` answers directly without mutating
  the index.
- Path-scope detection (`git status --porcelain`) and diagnostics
  (`git diff`) to `docs/reference` and `docs/bake-stdlib.md`, so unrelated
  working-tree state cannot cause a false positive.
- Mirror the freshly generated docs with `rsync -a --delete` so any stale
  files left behind are also reset.
- On failure, print the changed paths and a (truncated) diff alongside the
  error message, giving contributors an actionable signal.
- `git add -N` before diffing so untracked files (e.g. a new command's
  docs) appear in the diff instead of only in the path list.

Signed-off-by: Lohit Kolluri <lohitkolluri@gmail.com>
---
 hack/dockerfiles/docs.Dockerfile | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/hack/dockerfiles/docs.Dockerfile b/hack/dockerfiles/docs.Dockerfile
index c16a8b273fc2..9a9f12136661 100644
--- a/hack/dockerfiles/docs.Dockerfile
+++ b/hack/dockerfiles/docs.Dockerfile
@@ -21,7 +21,7 @@ RUN --mount=target=/context \
   --mount=target=.,type=tmpfs <<EOT
 set -e
 rsync -a /context/. .
-docsgen --formats "$FORMATS" --source "docs/reference" --bake-stdlib-source "docs/bake-stdlib.md"
+docsgen --formats "$FORMATS" --source "docs/reference/" --bake-stdlib-source "docs/bake-stdlib.md"
 mkdir /out
 cp -r docs/reference docs/bake-stdlib.md /out
 rm -f /out/reference/*__INTERNAL_SERVE.yaml /out/reference/*__INTERNAL_SERVE.md
@@ -35,12 +35,25 @@ RUN --mount=target=/context \
   --mount=target=.,type=tmpfs <<EOT
 set -e
 rsync -a /context/. .
-git add -A
-rm -rf docs/reference/* docs/bake-stdlib.md
-cp -rf /out/* ./docs/
+
+# Replace the checked-in docs with freshly generated output, then verify that
+# the working tree still matches HEAD under these paths. This enforces the
+# same contract as `make docs`: after regenerating, the repo must be clean.
+rsync -a --delete /out/reference/ docs/reference/
+cp /out/bake-stdlib.md docs/bake-stdlib.md
+
+# Intent-to-add so untracked files (e.g. a new command's docs) appear in the
+# diff below; `git diff` skips untracked files by default.
+git add -N -- docs/reference docs/bake-stdlib.md
+
 if [ -n "$(git status --porcelain -- docs/reference docs/bake-stdlib.md)" ]; then
-  echo >&2 'ERROR: Docs result differs. Please update with "make docs"'
+  echo >&2 'ERROR: Docs are out of date. Run "make docs" and commit the result.'
+  echo >&2
+  echo >&2 '--- changed paths ---'
   git status --porcelain -- docs/reference docs/bake-stdlib.md
+  echo >&2
+  echo >&2 '--- diff (truncated to 200 lines) ---'
+  git diff -- docs/reference docs/bake-stdlib.md | head -n 200
   exit 1
 fi
 EOT