Migrate from Protolock#

Protolock was a Protobuf breaking-change detector that compared a current schema against a stored proto.lock file representing the previous version.

This guide is a lookup reference for repositories still using Protolock. Each section maps a Protolock surface to its current Buf CLI equivalent. buf breaking covers the same ground, with a wider rule set, configurable categories, and file:line:column diagnostics.

For installation, see the Buf CLI installation guide; for a hands-on intro to breaking-change detection, see the breaking quickstart.

Command mapping#

For new projects, comparing against a Git ref or a BSR module is usually simpler than maintaining a checked-in lock file. The mappings below assume the lock-file workflow Protolock uses; for the alternatives, see the breaking quickstart.

Protolock	Buf CLI	Notes
`protolock init`	`buf build -o lock.binpb`	Writes a binary Buf image of the current schema. Add `--exclude-source-info` if the file is only used for breaking checks; the resulting image is significantly smaller.
`protolock status`	`buf breaking --against lock.binpb`	Compares the current schema against the lock file.
`protolock commit`	`buf breaking --against lock.binpb && buf build -o lock.binpb`	Run before commits or in CI: check for breaking changes, then refresh the lock file if the check passes.

Flag mapping#

Protolock flag	Buf equivalent	Notes
`--ignore`	`breaking.ignore` and `breaking.ignore_only` in `buf.yaml`	Path-only or path-and-rule scoped ignores.
`--protoroot`	none direct	Define the workspace root in `buf.yaml`; modules under that root resolve their own imports.
`--lockdir`	`--against path/to/lock.binpb`	The lock file is the argument to `--against` rather than a directory flag.

Rule mapping#

Buf’s preset categories (FILE, PACKAGE, WIRE_JSON, WIRE) are usually a better starting point than reproducing Protolock’s exact rule set. See breaking rules for what each category covers.

For migrations that need to match Protolock’s existing coverage, this buf.yaml enables the rules Protolock checks:

buf.yaml

version: v2
breaking:
  use:
    - ENUM_VALUE_NO_DELETE_UNLESS_NAME_RESERVED
    - ENUM_VALUE_NO_DELETE_UNLESS_NUMBER_RESERVED
    - FIELD_NO_DELETE_UNLESS_NAME_RESERVED
    - FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED
    - FIELD_SAME_NAME
    - FIELD_SAME_TYPE
    - RESERVED_ENUM_NO_DELETE
    - RESERVED_MESSAGE_NO_DELETE
    - RPC_NO_DELETE
    - RPC_SAME_CLIENT_STREAMING
    - RPC_SAME_REQUEST_TYPE
    - RPC_SAME_RESPONSE_TYPE
    - RPC_SAME_SERVER_STREAMING

The same coverage is roughly WIRE_JSON plus RPC_NO_DELETE, with a few exclusions:

buf.yaml

version: v2
breaking:
  use:
    - WIRE_JSON
    - RPC_NO_DELETE
  except:
    - ENUM_VALUE_SAME_NAME
    - FIELD_SAME_CARDINALITY
    - FIELD_SAME_JSON_NAME
    - FIELD_SAME_ONEOF
    - RPC_SAME_IDEMPOTENCY_LEVEL

Buf’s rule set evolves; if a name doesn’t load, run buf config ls-breaking-rules to confirm it.

Lock file format#

buf build -o writes the schema as a binary Buf image (.binpb), wire-compatible with FileDescriptorSet. This is the recommended format.

If you prefer JSON storage like Protolock’s proto.lock, write to a .json filename instead. The file contents are still a Buf image (the JSON form of a FileDescriptorSet), not Protolock’s custom JSON shape; it’s only the file format that matches:

$ buf build -o lock.json

Source code info is included by default. Add --exclude-source-info if you’re only using the file for breaking checks; the resulting image is significantly smaller, at the cost of editor-quality diagnostics from this file.

Docker#

The Buf CLI is published at bufbuild/buf. The image’s ENTRYPOINT is buf, so omit buf from the docker run invocation:

$ docker pull bufbuild/buf:1.71.0
$ docker run --rm --volume "$(pwd):/workspace" --workdir "/workspace" \
    bufbuild/buf:1.71.0 breaking --against lock.binpb

Pin to a specific tag in CI so behavior stays reproducible.

Differences worth knowing#

Schema representation: Buf uses FileDescriptorSet-based Buf images instead of Protolock’s custom JSON structure. FileDescriptorSet is the Protobuf compiler’s own intermediate format and covers every part of a .proto schema, including options.
Plugin interface: Buf doesn’t expose Protolock’s external-binary plugin interface for adding breaking-change rules. Custom rules live in Buf check plugins instead.
Diagnostics: buf breaking reports violations with file:line:column:message references, suitable for editor integration. Protolock prints unreferenced messages.
Comparison sources: --against accepts more than a checked-in lock file. It also accepts a Git URL with branch or tag, a tarball, a BSR module name, and any other input the CLI recognizes.