EasyP

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-fork

The 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/user

Only 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 tidy resolves and validates the effective graph and installs needed remote snapshots without editing the manifest or lock.
  • get may edit the explicitly requested requirement. mod update refreshes 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 download verifies/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 vendor copies current local and verified remote sources into easyp_vendor without 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

  1. Publish the dependency changes in Git at the intended version.
  2. Update require in the consumer's protobuf.mod.
  3. Remove the replace directive.
  4. Run easyp mod tidy in that module to update protobuf.lock.
  5. 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.

On this page