Buf Docs

Appearance

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:

sh
buf export buf.build/grpc/grpc -o /path/to/directory

When exporting from the BSR, you can also specify a commit or label, preceded by a colon (:):

sh
buf export buf.build/grpc/grpc:334e348dc5854e4b99a3a0d25d8ff376 -o /path/to/directory

Exporting from Git ​

You can also use a Git repository as the source:

sh
buf export https://github.com/bufbuild/protovalidate.git -o /path/to/directory

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:

sh
buf export -o /path/to/directory

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):

Exclude the 'geo' directory

sh
buf export buf.build/googleapis/googleapis -o /path/to/directory --exclude-path google/geo

Only export the 'geo' and 'longrunning' directories

sh
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.

sh
buf export buf.build/grpc/grpc --all -o /path/to/directory

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:

Syntax

bash
$ 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 or zip.

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:

Download a module archive that includes dependencies

sh
curl -fsSL -O "https://buf.build/acme/petapis/archive/main.zip?imports=true"