Export modules from the BSR#
With the Buf CLI and the BSR, moving .proto
files around is unnecessary. However, other tools may require all .proto
files to be present locally, requiring you to export your .proto
files.
To export modules, you can either:
- Use the Buf CLI's
buf export
command with a variety of inputs. - Download and extract an archive file from the BSR.
Export with the Buf CLI#
The buf export
command allows you to copy .proto
files to your local environment from many types of sources, including the BSR, a Git repository, or a .tar
file.
Exporting a BSR module#
The most common use of buf export
is to export a BSR module. By default, exporting from the BSR exports latest
and includes all dependencies:
When exporting from the BSR, you can also specify a commit or label, preceded by a colon (:
):
Exporting from Git#
You can also use a Git repository as the source:
Exporting a local directory#
The basic buf export
command defaults to the current local directory as the source and requires a local destination directory path for the output:
Limiting output#
You can limit the output to a subset of the source by either excluding or including specific paths to a directory or file (multiple paths must be separated by commas):
$ buf export buf.build/googleapis/googleapis -o /path/to/directory --exclude-path google/geo
$ buf export buf.build/googleapis/googleapis -o /path/to/directory --path google/geo,google/longrunning
Including documentation#
Use the --all
flag to include any available documentation and license file. If the input has more than one module, then the documentation and license file names will be suffixed with the module name.
Export with curl
#
You can also request an archive of a module from the BSR using the curl
command.
It downloads a zip or tarball archive to your local environment.
The download command requires a BSR module as the source, and has this syntax:
$ curl -fsSL -O https://BSR_INSTANCE/MODULE_OWNER/MODULE_NAME/archive/REFERENCE.FILE_EXT
# Examples:
# The latest commit on the default label.
curl -fsSL -O https://buf.build/acme/petapis/archive/main.tar.gz
# A specific commit.
curl -fsSL -O https://buf.build/acme/petapis/archive/7abdb7802c8f4737a1a23a35ca8266ef.tar.gz
The URL contains these elements:
- BSR_INSTANCE is the domain name of your BSR instance. (Default: buf.build)
- MODULE_OWNER is the owner of the module.
- MODULE_NAME is the name of the module.
- REFERENCE must be one of the following:
- A label name: uses the latest commit for the given label.
- A commit ID: uses the explicit BSR module commit. This must be the full module commit ID.
- FILE_EXT is the file extension of the archive.
This can be either
tar.gz
orzip
.
Including dependencies#
By default, the module archive includes only the specified module's content, excluding any dependencies.
You can include all of the target module's dependencies, including the Well Known Types, by adding the imports=true
query parameter: