Replace directives
Use `replace` for deliberate local development or controlled forks; keep it explicit and temporary when possible.
Canonical guidance
- use
replacedeliberately, not casually - prefer short-lived local replacements for local iteration
- if a committed replacement points to a fork, document the reason and exit path
Use when
- patching a dependency locally
- testing an unpublished sibling module without a workspace
- pinning to a reviewed fork
Avoid
- committing personal filesystem paths
- hiding dependency drift behind long-lived unexplained replacements
- using
replaceas normal version-management policy
Preferred pattern
module example.com/app
replace example.com/lib => ../lib
Anti-pattern
- leaving a local
../forkreplacement in committedgo.modfor a shared repository
Explanation: This anti-pattern is tempting because it works on one machine, but it breaks reproducibility everywhere else.
Why
replaceis powerful, but it changes dependency resolution in ways other developers and CI must be able to explain
Related pages
Sources
- Go Modules Reference - Go Team