Replace directives

Canonical guidance

• use replace deliberately, 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 replace as normal version-management policy

Preferred pattern

module example.com/app

replace example.com/lib => ../lib

Anti-pattern

• leaving a local ../fork replacement in committed go.mod for a shared repository

Explanation: This anti-pattern is tempting because it works on one machine, but it breaks reproducibility everywhere else.

Why

• replace is powerful, but it changes dependency resolution in ways other developers and CI must be able to explain