git: 22b66edfc1 - main - PHB(special>go): Add instructions for overriding go.mod

The branch main has been updated by adamw:

URL: https://cgit.FreeBSD.org/doc/commit/?id=22b66edfc15fa035d9e43f39522a15c11212cfbe

commit 22b66edfc15fa035d9e43f39522a15c11212cfbe
Author:     Adam Weinberger <adamw@FreeBSD.org>
AuthorDate: 2026-03-01 02:17:26 +0000
Commit:     Adam Weinberger <adamw@FreeBSD.org>
CommitDate: 2026-03-01 02:17:26 +0000

    PHB(special>go): Add instructions for overriding go.mod
    
    The USES=go:modules system is smart and clever, but it does all its
    evaluation of go.mod during fetch phase, which means that porters can't
    patch it first (say, to alter dependencies or change the toolchain
    version).
    
    Instead, it's possible to override go.mod by specifying a new one as
    a second distfile (and go.sum can be overridden in the same way). We've
    supported that for a long time, but we've never documented it before.
    
    Reviewed by:    fuz, ziaee
    Approved by:    ziaee (doc)
    Differential Revision:  https://reviews.freebsd.org/D55580
---
 .../en/books/porters-handbook/special/_index.adoc  | 28 ++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc
index ea0b1b3b22..9501ff8ef3 100644
--- a/documentation/content/en/books/porters-handbook/special/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/special/_index.adoc
@@ -990,6 +990,34 @@ GO_TARGET=  ./dnscrypt-proxy:${PREFIX}/sbin/dnscrypt-proxy
 will install `dnscrypt-proxy` to `${PREFIX}/sbin`.
 ====
 
+[[overriding-go-mod]]
+.Overriding go.mod in Modules Mode
+[example]
+====
+During the fetch phase, modules-aware mode (that is, `USES=go:modules`) obtains sources for dependent packages by fetching the port's [.filename]#go.mod# and then immediately running `go mod download` against it.
+Because the fetch phase occurs long before patching, regular patches in [.filename]#files/# are applied far too late to affect those dependency resolution and fetch steps.
+
+While patching the upstream [.filename]#go.mod# to alter dependencies isn't possible at this time, you can still *override* it by listing another [.filename]#go.mod# as a second distfile.
+
+[.programlisting]
+....
+PORTNAME=	miller
+DISTVERSIONPREFIX=	v
+DISTVERSION=	6.17.0
+CATEGORIES=	textproc
+MASTER_SITES=	https://raw.githubusercontent.com/johnkerl/${PORTNAME}/${DISTVERSIONFULL}/:gomod
+
+DISTFILES=	go.mod:gomod
+....
+
+To override [.filename]#go.sum# as well, just add it to `DISTFILES`:
+
+[.programlisting]
+....
+DISTFILES=	go.mod:gomod go.sum:gomod
+....
+====
+
 [[using-cabal]]
 === Building Haskell Applications with `cabal`