Dependency Management
A module can declare dependencies on other modules, which is configured in the
deps
key of your buf.yaml
. You can add dependencies by adding their module
name to the deps
list. For example:
version: v1
name: buf.build/acme/weather
deps:
- buf.build/acme/units
Although we do not recommend it, in some situations you may need to pin a
module to a specific version. You can do this by specifying a tag, a commit name,
or a draft name in your deps
after the :
delimiter. Ideally, authors keeps
modules backwards-compatible and avoid breaking changes, so you can always rely
on the latest version.
deps:
- buf.build/acme/units:1c473ad9220a49bca9320f4cc690eba5
Once a dependency is added to the configuration file, you need to run:
$ buf mod update
This updates all your deps to their latest version and is captured in a
buf.lock
file.
You can now import the Protobuf types just like you would if you had the files locally:
package acme.weather.v1;
import "acme/units/v1/unit.proto";
message Forecast {
string description = 1;
acme.units.Degree temperature = 2;
}
The buf
CLI automatically resolves the module(s) specified in the deps
list.
See the Usage section for a detailed example.
To execute buf
commands below make sure you are
authenticated. Obtain a token from the BSR and run:
$ buf registry login
Follow the prompts to enter your username and password (API Token). This adds an
entry into your $HOME/.netrc
(Linux or macOS) or %HOME%/_netrc
(Windows).
Push a module
To push to the BSR, your module must build successfully.
This means that you are able to run buf build
successfully on your module and
your module has no dependencies pinned to a draft commit.
Before you can push a module into the BSR, a repository must exist and you must
own or have access to that repository. A repository can be created either
through the UI or from the command line with buf
.
If you want to collaborate with other users on a module, select an organization as the owner of the repository.
1. Create a Repository
Through the UI log in at https://buf.build/login and navigate to Your repositories and click Create Repository. Select an owner for the repository and give it a repository name. The visibility can be either public or private.
Alternatively, use the CLI run this command:
$ buf beta registry repository create <MODULE_NAME> --visibility [public,private]
The module name takes the form <remote>/<owner>/<repository_name>
(for
example, buf.build/acme/weather
). The --visibility
flag is required
and must be one of: private
or public
.
2. Configure a name
You'll need to configure your buf.yaml
file to match the BSR repository. To do
so, add the module name as a name
key:
version: v1
name: buf.build/acme/weather
3. Push to the Repository
Push your module to the BSR by running this command:
$ buf push
This command returns the commit reference.
One of the main benefits of a centralized, Protobuf-aware registry is you're guaranteed not to push broken modules. This means that consumers can have confidence that modules hosted on the BSR always compile.
Suppose we mistyped an identifier:
syntax = "proto3";
package units.v1;
messag Metric {
int64 other = 1;
}
If we try to buf push
to the BSR we'll get an immediate error:
Failure: units/v1/metric.proto:5:1:syntax error: unexpected identifier.
Sure you can have CI workflows to automatically catch compilation errors, but by using the BSR these guarantees are made available to everyone out-of-the-box.
That's it. This module can now be consumed as a first class dependency and its generated documentation can be viewed on the BSR.
Add a dependency
A module can declare dependencies on other modules, which is configured in the
deps
key of your buf.yaml
. You can add dependencies by adding their module
name to the deps
list. For example:
version: v1
name: buf.build/acme/weather
deps:
- buf.build/acme/units
Although we do not recommend it, in some situations you may need to pin a
module to a specific version. You can do this by specifying a tag, a commit name,
or a draft name in your deps
after the :
delimiter. Ideally, authors would keep
modules backwards-compatible and avoid breaking changes, so you can always rely
on the latest version.
deps:
- buf.build/acme/units:1c473ad9220a49bca9320f4cc690eba5
Once a dependency is added to the configuration file, you need to run:
$ buf mod update
This updates all your deps to their latest version and is captured in a
buf.lock
file.
You can now import the Protobuf types just like you would if you had the files locally:
package acme.weather.v1;
import "acme/units/v1/unit.proto";
message Forecast {
string description = 1;
acme.units.Degree temperature = 2;
}
The buf
CLI automatically resolves the module(s) specified in the deps
list.
Example
If, for example, you are using one of the files from the
googleapis repository in your
Protobuf files, and you're having to copy files into your local Protobuf
generation tree, you can instead use buf
to manage this dependency for you.
To include dependencies in your build add the deps
key to your buf.yaml
file
and list the modules your build depends on. Example:
version: v1
deps:
- buf.build/googleapis/googleapis
lint:
use:
- DEFAULT
breaking:
use:
- FILE
After adding dependencies in buf.yaml
run this command:
$ buf mod update
This updates all your deps
to their latest version and gets captured in a
buf.lock
file. You do not need to make any changes to this file and if using a
version control system, commit it along with your Protobuf files.
# Generated by buf. DO NOT EDIT.
version: v1
deps:
- remote: buf.build
owner: googleapis
repository: googleapis
commit: 62f35d8aed1149c291d606d958a7ce32
Once your dependencies are updated, you can run buf build
and the buf
CLI
resolves hosted module dependencies by leveraging the BSR.
For a more in-depth example see the Tour