When would you use a replace directive, and why doesn't a dependency's replace affect your build?

replace swaps the content of a module version for another version, another module path (a fork), or a local directory. Typical uses: testing a local fix before it goes upstream, pinning a fork, or working around a broken release.

replace (
    github.com/foo/bar => ../bar                      // local dir (needs its own go.mod)
    github.com/foo/baz v1.4.0 => github.com/me/baz v1.4.1-fix
)

Key rule: replace and exclude apply only in the main module's go.mod (and in go.work). They are ignored in dependencies. Otherwise a library could silently redirect your supply chain, and two libraries with conflicting replaces could never be combined.

Gotchas:

• A local-path replace committed to a library breaks the build for anyone without that directory. Use go.work for local multi-module development.
• go install mod@version fails if the target module's go.mod contains replace directives. This is intentional so that the build is the same everywhere.
• A replacement by path does not change import paths. Your code still imports the original path.