buf.lock

If your buf.yaml declares any deps, it will be accompanied by a buf.lock file that contains your module's dependency manifest. This manifest represents a single, reproducible build of your module.

You can create or update a buf.lock file for your module by running the buf mod update command. For example, suppose that we have this directory layout and buf.lock content for the buf.build/acme/petapis module:

.
├── acme
│   └── pet
│       └── v1
│           └── pet.proto
├── buf.lock
└── buf.yaml

# Generated by buf. DO NOT EDIT.
version: v1
deps:
  - remote: buf.build
    owner: acme
    repository: paymentapis
    commit: 9a877cf260e1488d869a31fce3bea26d
    digest: shake256:4af5b88c9a1d9b36421ad84a2cff211fc74995040188dafc1c8508d36406140e40eb0ab82d21e761961e4a71631d4474e3d0608b987ca3d02d5d19012edff21d

deps

Each entry in the buf.lock deps key is a module pin, which uniquely represents a specific snapshot of the given module (buf.build/acme/paymentapis:9a877cf260e1488d869a31fce3bea26d in this case), protected with a cryptographic digest of all of the files in it (see how we protect dependencies against tampering). With this, the local snapshot of the buf.build/acme/petapis module and all of its dependencies are uniquely represented, reproducible, and protected against tampering.

Push and update modules

You can then publish and share this particular snapshot with your consumers and/or collaborators by pushing it to the BSR with the command:

$ buf push

With this, modules that depend on buf.build/acme/petapis can run buf mod update and notice a new module pin in their buf.lock! For example, we can update the content found in this module's buf.lock by running this:

# Generated by buf. DO NOT EDIT.
version: v1
deps:
  - remote: buf.build
    owner: acme
    repository: paymentapis
    commit: 9a877cf260e1488d869a31fce3bea26d
    digest: shake256:4af5b88c9a1d9b36421ad84a2cff211fc74995040188dafc1c8508d36406140e40eb0ab82d21e761961e4a71631d4474e3d0608b987ca3d02d5d19012edff21d

Older versions of buf may include branch, commit, and create_time as a part of the dependencies. Your buf.lock shouldn't include these fields if you've run buf mod update with a newer version of buf.

For more on updating dependencies and pushing modules, see the guide to iterating on Modules.