An Image is a set of Protobuf files compiled into an Image binary. An Image represents everything inside a Protobuf project and can be used as the input to most commands.
Description
Images in Protobuf are encoded as Image Protobuf messages, with the mechanics of Buf images explained in detail on the Image explanation page. An image can be in either binary or JSON format.
Using images can greatly simplify working with Protobuf projects, as it allows for state to be saved, compared, and used as input for other commands. All Buf images are stored as files, which can be read from a local path, a remote HTTP/HTTPS location, or stdin (using '-').
The commands that take an image are:
Usage
When Using an image as an input the following options are available. Options are parsed to input parameters in the following form:
path#option_key1=option_value1,option_key2=option_value2
Options
#format=[bin|json]
This page contains image formats, to see all formats see the format page.
| Format | Description | Derived extension | Example |
|---|---|---|---|
| bin | protobuf binary | .bin | image.bin, image#format=bin |
| json | json image | .json | image.json, image#format=json |
#format=bin
Protobuf binary format. The path to this archive can be either a local file, a remote
http/https location, or stdin. To use stdin use -, for example cat image.bin | buf build -#format=bin or just cat image.bin | buf build -.
When the format is bin the compression option is available.
Usage
#format=bin,compression=[gzip|zstd]
Options
| Option | Value | Description | Example |
|---|---|---|---|
| compression | gzip,zstd | compression to use | buf build image#format=bin,compression=gzip |
Automatically derived formats and compressions
As well as using the format and compression options, the following file extensions can be used instead.
| Extension | Derived Compression | Example |
|---|---|---|
| .bin | none | image.bin |
| .bin.gz | gzip | image.bin.gz |
| .bin.zst | zstd | image.bin.zst |
#format=json
Protobuf in JSON format. This creates files that use much more space and are
slower to parse but result in diffs that show the actual differences between two
Protobuf objects in a readable format. The path to this archive can be either a local file, a remote
http/https location, or stdin. To use stdin use -, for example cat image.json | buf build -#format=bin.
When the format is json, the compression option is available.
Usage
#format=json,compression=[gzip|zstd]
Options
| Option | Value | Description | Example |
|---|---|---|---|
| compression | gzip,zstd | compression to use | buf build image#format=json,compression=gzip |
Automatically derived formats and compressions
As well as using the format and compression options, the following file extensions can be used instead.
| Extension | Derived Compression | Example |
|---|---|---|
| .json | none | image.json |
| .json.gz | gzip | image.json.gz |
| .json.zst | zstd | image.json.zst |
Examples
Use buf breaking --against:
buf breaking image.bin --agaist image.bin
Use a binary 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=eliza.bin