REPROTO(1)

✨ NAME ✨

reproto — reconstruct .proto source files from compiled protobuf descriptor sets. okay so this is the REPROTO(1) page, bestie, and this tool is lowkey iconic: it takes compiled protobuf descriptor sets and regenerates the original .proto source files with correct syntax, field types, and options. no cap, that's the whole main character energy 💅

🌈 SYNOPSIS 🌈

reproto [OPTIONS] DESCRIPTOR_FILES...

🦋 DESCRIPTION 🦋

reproto reads one or more binary or text-format protobuf descriptor sets and regenerates the original .proto source files with correct syntax, field types, and options. it's giving "uncompile my heart" in the best way possible 😭💖

it supports proto2, proto3, and editions syntax, and accepts both .pb (binary FileDescriptorSet) and .textpb (text-format) descriptor files as input. fr fr, all the syntax eras are invited to the party 🎉

🌸 ARGUMENTS 🌸

• DESCRIPTOR_FILES — One or more descriptor files to process. Accepts binary FileDescriptorSet, binary FileDescriptorProto, #@ prototext-format descriptors, or directories (processed recursively). Any file extension is accepted; .pb and .desc are conventional. Paths are resolved relative to directories given by -I (--desc-root), or relative to the current working directory if -I is not provided. iykyk, the -I thing is the vibe check for path resolution 🧭

💖 OPTIONS 💖

okay bestie, here's the full menu — every flag is here, periodt. no skipping the "boring" ones, because they all matter 💖

🧊 Input

• -I, --desc-root PATH — Root for resolving relative DESCRIPTOR_FILES paths and for locating imports (repeatable; like protoc -I). A directory is read as-is; a file is read as a blob, standing for the descriptors embedded in it, one member per FileDescriptorProto found (what protoscan would have extracted). Defaults to the current directory.

🎀 Output

• -O, --proto-out DIRECTORY — Output directory for generated .proto files (created if absent). Not required when using --schema-db-out, --scoring-html-out, or --dry-run. Defaults to the --schema-db-out stub´s ´proto´ child when that option is given; --no-proto-out suppresses that default. When --schema-db-out is also given, DIR may not be inside its stub directory unless DIR is that stub´s immediate ´proto´ child.
• --no-proto-out — Do not write .proto files. Suppresses the -O directory that --schema-db-out otherwise implies; an error if -O is also given.
• -b, --emit-binary — Also write binary descriptor files (.pb) alongside .proto output.
• --source-info — Embed a SourceCodeInfo synthesized from the reconstructed .proto text in binary descriptor output (-b, --schema-db-out). On by default.
• --dry-run — Do not actually create .proto files.

🌱 Variant / Schema

• --proto-variant FILE — Path to a variant specification YAML file. If omitted, $REPROTO_VARIANT is used; otherwise the built-in google.protobuf default applies.
• --use-variant CHOICE — Use the variant´s embedded copy of a well-known file instead of whatever the input .pb files contain. Accepts: any, empty, timestamp, duration, struct, wrappers, descriptor, all. May be repeated.
• --keep-descriptor-path — Keep the variant descriptor import path as-is (do not rewrite to google/protobuf/descriptor.proto).

🔎 Filtering

• -s, --seed TEXT — FQDN or path pattern to treat as an output root. FQDN (needs a prefix): desc:my.pkg.MyMsg, file:foo.proto (the FDP named foo.proto). Path (bare, or path: prefix): foo.pb (every FDP in that physical file), matched against the -I-relative path. Glob (either form): one *.proto (one level), borg/** (recursive).
• -p, --prune TEXT — FQDN or path pattern to exclude from output. FQDN (needs a prefix): desc:my.pkg.MyMsg, file:foo.proto (the FDP named foo.proto). Path (bare, or path: prefix): foo.pb (that physical file, never loaded), matched against the -I-relative path. Glob (either form): one *.proto (one level), borg/** (recursive).
• -C, --filter-config FILE — Path to a YAML file with "seed:"/"prune:" lists of FQDNs or path patterns (same syntax as -s/--seed and -p/--prune). Merged with any -s/-p flags given on the command line.

🎨 Rendering

• --force-proto2-output — Force all output to proto2 syntax, regardless of the input syntax. Without this flag, output syntax matches the input (polyglot mode).
• --force-proto2-for-editions — Translate editions-syntax files to proto2 in output and binary descriptors, the schema DB included. Symmetric with --force-proto2-output but limited to editions files only. Use this for readers that do not support editions, such as prost-reflect.
• --redact-comments — Redact comments from reconstructed .proto files.
• --redact-orphans — Redact orphans from reconstructed .proto files.
• --go-root TEXT — Force go_package option in reconstructed .proto files.

🛠️ Advanced

• --schema-db-out FILE — Write the schema DB to FILE (must end in .desc). Writes FILE (FileDescriptorSet of all loaded FDPs), FILE-stem/hopcroft.rkyv (compiled scoring graph), and FILE-stem/index.rkyv (lazy-loading FDS index). If -O is also given, it may not be inside FILE-stem unless it is exactly FILE-stem/proto.
• --emit-scoring-yaml — Write per-file scoring-graph YAML files alongside .proto output under --proto-out.
• --emit-extension-ranges — Record each message´s extension ranges in the scoring graph, so that an unknown field number inside a declared range is not counted against the type.
• --scoring-html-out FILE — Write scoring-graph HTML visualisations to FILE; requires --schema-db-out.
• --with-leaf-nodes — Include leaf (wire-type sink) nodes in --scoring-html-out graphs (hidden by default).
• --hide TEXT — FQDN or glob pattern to hide from --scoring-html-out graphs (same syntax as --prune). Matched nodes and their incident edges are dropped from the HTML; no effect on the schema DB.
• --debug — Print detailed debug information (development only).
• --fdp-plugin PATH — Python file executed as a transformation hook on every FileDescriptorProto reproto parses, before anything reads it. Must define fdp_plugin(fdp), which mutates fdp in place. Called more than once per input file, so it must be deterministic; it must not read reproto state.
• --keep-duplicates — Do not prune files whose symbols conflict with already-loaded files (legacy behaviour; by default conflicting files are silently pruned and a warning is emitted).

🩺 Diagnostics

• --detailed-warnings — Print every warning occurrence immediately as it is emitted (default: squash repeated warnings and show a count summary at the end).
• --quiet, -q — Suppress progress messages and warnings. Errors are always printed.
• --debug-fqdn — Print detailed information about FQDNs (development only).

🎁 Other

• --emit-descriptor — Write descriptor.proto to the output directory (default: on).
• --version — Print version and exit.
• --help — Show a help message and exit.

🌿 ENVIRONMENT 🌿

• REPROTO_VARIANT — Path to a variant YAML file used when --proto-variant is not given.
• REPROTO_GEN_MAN — When set to a directory, write the man pages of reproto and reproto-instantiate-schema into it and exit.
• _REPROTO_COMPLETE — When set to bash_source, zsh_source or fish_source, print the completion script for that shell and exit. The scripts set it to bash_complete, zsh_complete or fish_complete to get the candidates.

⚠️ NOTES ⚠️

bestie, important vibe check: reproto does not support multi-file FileDescriptorSet inputs (i.e. .pb files produced with protoc --include_imports). Each .pb file must contain exactly one FileDescriptorProto. Pass all .pb files together on the command line and let reproto resolve cross-file imports. no cap, this one matters 💀

🧪 EXAMPLES 🧪

🧸 Reconstruct a descriptor set

Compile each .proto to its own descriptor set (without --include_imports), then pass all .pb files to reproto:

protoc --descriptor_set_out=phone_number.pb --proto_path=. phone_number.proto
protoc --descriptor_set_out=address_book.pb --proto_path=. address_book.proto
reproto --use-variant descriptor -I . -O out/ phone_number.pb address_book.pb

✨ Selective output (one message and its dependencies)

reproto --use-variant descriptor -I . -O out/ --seed desc:.tutorial.Person \
  phone_number.pb address_book.pb

🦋 Using the embedded descriptor variant

The --use-variant descriptor flag supplies descriptor.proto from the built-in variant bundle, so no separate descriptor .pb is needed:

reproto --use-variant descriptor -I . -O out/ phone_number.pb address_book.pb

🐚 Enable shell completion

Packages usually install the scripts. Otherwise, in bash, zsh or fish:

source <(_REPROTO_COMPLETE=bash_source reproto)
source <(_REPROTO_COMPLETE=zsh_source reproto)
_REPROTO_COMPLETE=fish_source reproto | source

👀 SEE ALSO 👀

protoc(1), prototext(1) — go say hi to the cousins 👋

---

mwah 💋 that's the whole reproto 0.3.6 moment, dated 2026, on page REPROTO(1) — now go reconstruct something iconic ✨🫶