Debugging with Replace Directives
Use local module replacements for development and understand their lockfile and network limits.
A local replace in protobuf.mod lets you edit a dependency alongside its consumer without publishing each intermediate change.
Setting Up a Local Replace
Suppose proto/user requires github.com/acme/weather. Put the dependency checkout at proto/weather-fork, next to proto/user, and add:
// proto/user/protobuf.mod
module github.com/acme/user
require (
github.com/acme/weather v1.2.3
)
replace github.com/acme/weather => ../weather-forkThe relative replacement path is resolved from the directory containing this protobuf.mod, so it points to proto/weather-fork, regardless of the shell's working directory. Absolute paths also work. The replacement's native protobuf.mod must declare github.com/acme/weather; a missing directory or mismatched identity is an error.
Local Development Workflow
With a generator file in proto/user, run from the repository root:
easyp generate --project ./proto/userOnly the main consumer's replacements apply, at every depth of the required graph. EasyP reads the replacement's protobuf.mod requirements and source roots; dependency-owned replacements are ignored. Relative paths always use the main manifest directory. A replacement alone does not add a dependency, and unused replacements are not read or fetched. Ordinary dependency cycles are deduplicated. Legacy dependency metadata remains supported through the existing compatibility reader; dependency plugins are not executed.
Generate, selected dependency generation, both descriptor export modes, lint, ls-files and breaking import resolution use this same effective graph. Replaced modules need no remote fetch and may be unpublished. A fully local graph works offline without a lock.
Reached replacement trees are imports during consumer lint and breaking checks; their policies do not become consumer policies. Use --path to check a replacement explicitly. Unused replacement paths cannot exclude the consumer's own sources. Buf includes/excludes remain effective for replacement sources; see dependency filters.
Local Mode and the Published Lock
While the main manifest contains replacements, EasyP leaves an existing protobuf.lock byte-for-byte unchanged and does not create one if absent. Local paths, local versions/hashes and fork-only transitive dependencies never enter the shared lock. This is an explicit EasyP invariant: protobuf.lock is not go.sum, and this does not mean Go never updates go.sum with replacements. The main-module replacement semantics follow Go's replacement model.
mod tidyresolves and validates the effective graph and installs needed remote snapshots without editing the manifest or lock.getmay edit the explicitly requested requirement.mod updaterefreshes unreplaced direct requirements using the existing version rules; replaced requirements keep their declared versions without a remote lookup. Neither command promotes fork-only transitives or writes a lock.mod downloadverifies/installs only needed unreplaced snapshots. It can resolve new remote requirements of the fork without adding them to the shared lock; replaced roots and unused lock entries are not downloaded.mod vendorcopies current local and verified remote sources intoeasyp_vendorwithout writing the lock. This local artifact does not prove published reproducibility.
The effective graph exists only in memory. Matching published revisions and versionless pins use verified cached snapshots. A new remote requirement of a fork can need network access for resolution and installation; immutable-version and content checks still apply. Remote plugins also retain their network requirements.
Preparing for PR Submission
- Publish the dependency changes in Git at the intended version.
- Update
requirein the consumer'sprotobuf.mod. - Remove the
replacedirective. - Run
easyp mod tidyin that module to updateprotobuf.lock. - Regenerate the selected project, run consumer tests, and commit the reviewed manifest, lock, and generated changes.
For breaking checks, replacements inside the Git repository use each revision's own contents. External local replacements are rejected because the baseline has no recoverable historical copy. A versionless remote requirement from a historical fork needs a historical lock pin; current HEAD cannot substitute for the baseline. See breaking checks.