A source refers to a collection of uncompiled Protobuf files in a project.
The commands that may take a source are:
Along with these, the following only take a source:
Description
A source refers to a collection of uncompiled Protobuf files, which can be stored in various formats such as git,
directory, module, tar, protofile, or zip. It is important to note that an image built with buf build is not considered
a source.
Several commands in the buf tool can accept a source as their first argument. The export and format commands only accept a source, while other commands such as breaking, build, convert, generate, and lint can accept both a source and an Image.
Additionally, the buf breaking --against command and the buf curl --schema command can accept a source as well.
Usage
Options are parsed to input parameters in the following form:
path#key=value
Options
#format=[dir|git|mod|protofile|tar|zip]
This page contains source formats, to see all formats see the format page.
| Format | Description | Derived extension | Example |
|---|---|---|---|
| dir | directory | path/to/project | |
| git | git repository | .git | https://github.com/foo/bar.git |
| mod | bsr module | buf.build/bufbuild/eliza | |
| protofile | protobuf file | .proto | path/to/file.proto, path/to/file#format=protofile |
| tar | tarball | .tar | archive.tar, archive#format=tar |
| zip | zip archive | .zip | archive.zip, archive#format=zip |
#format=dir
A local directory. The path can be either relative or absolute.
This is the default format. By default, buf uses the current directory as
its input for all commands.
Usage
#format=dir
#format=mod
A Module on the Buf Schema Registry. This uses whatever is in this Module for the sources.
Usage
#format=mod
#format=git
A Git repository. The path to the Git repository can be either a local .git
directory, or a remote http://, https://, ssh://, or git:// location.
When format is git the ref, branch, tag, depth, recurse_submodules, and subdir options are available.
Usage
#format=git,ref=<ref>,branch=<branch>,tag=<tag>,depth=<depth>,recurse_submodules=<bool>,subdir=<subdir>
| Option | Description | Default | Example |
|---|---|---|---|
| ref | A valid git ref | HEAD | buf build https://github.com/foo/bar#format=git,ref=my_branch |
| branch | A valid git branch | HEAD | buf build path/to/module#format=git,branch=my_branch |
| tag | A valid git tag | buf build https://github.com/foo/bar#format=git,tag=v1.0.0 | |
| depth | A valid git depth | 50 | buf build path/to/module#format=git,depth=1 |
| recurse_submodules | Whether to clone submodules recursively | false | buf build https://github.com/foo/bar#format=git,recurse_submodules=true |
| subdir | Which subdir to use as base directory | buf build path/to/archive.tar#format=git,subdir=bar |
#format=tar
A tarball. The path to this tarball can be either a local file, a remote
http/https location, or - for stdin.
When format is tar the compression, strip_components, and subdir options are available.
Usage
#format=tar,compression=[gzip|zstd],subdir=<subdir>,strip_components=<integer>
Options
| Option | Value | Description | Example |
|---|---|---|---|
| compression | gzip,zstd | compression to use | buf build image#format=tar,compression=gzip |
| strip_components | integer | strip first n directories, applied before subdir | buf build path/to/archive.tar#format=tar,strip_components=2 |
| subdir | string | subdirectory to use as base directory | buf build path/to/archive.tar#format=tar,subdir=bar |
Derived extensions
As well as using the format and compression options, the following file extensions can be used instead.
| Extension | Derived Compression | Example |
|---|---|---|
| .tar | none | image.tar |
| .tar.gz | gzip | image.tar.gz |
| .tgz | gzip | image.tgz |
| .tar.zst | zstd | image.tar.zst |
#format=protofile
A local Protobuf file. The path can be either relative or absolute, similar to the
dir input. This is a special input that uses the file and its imports as
the input to buf commands. If a local configuration
file is found, dependencies specified are used to resolve file imports first,
followed by the local filesystem. If there is no local configuration, the local
filesystem is used to resolve file imports.
When format is protofile The include_package_files option is available.
Usage
#format=protofile,include_package_files=<bool>
| Option | Value | Description | Example |
|---|---|---|---|
| include_package_files | bool | include all other files in the package for the specified .proto file | buf build file.proto#format=protofile,include_package_files=true |
#format=zip
A zip archive. The path to this archive can be either a local file, a remote http/https location, or stdin. When using stdin
When format is zip the compression, subdir, and strip_components options are available.
Usage
#format=zip,compression=[gzip|zstd],subdir=<subdir>,strip_components=<integer>
Options
| Option | Value | Description | Example |
|---|---|---|---|
| compression | gzip,zstd | compression to use | buf build image#format=zip,compression=gzip |
| strip_components | integer | strip first n directories, applied before subdir | buf build path/to/archive.tar#format=zip,strip_components=2 |
| subdir | string | subdirectory to use as base directory | buf build path/to/archive.tar#format=zip,subdir=bar |
Examples
Invoke an RPC using a git repo as the input to buf curl --schema:
buf curl --data '{"sentence": "I feel happy."}' https://demo.connect.build/buf.connect.demo.eliza.v1.ElizaService/Say --schema=https://github.com/bufbuild/connect-demo.git
Lint a dir of Protobuf files:
buf lint path/to/directory#format=dir
Export from a tar archive with gzip compression:
buf export path/to/archive#format=tar,compression=gzip --output=path/to/output
Export a git repository:
buf export https://github.com/example/repo#format=git --output=path/to/output
Use a zip as the source for buf convert:
buf convert path/to/archive.zip#format=zip,compression=zstd --from=file.json --to=file.bin --type Person
Lint a git repository on a specific branch:
buf lint https://github.com/example/repo#format=git,branch=my_branch