Documentation

Six pages cover everything the 2.8 line does. If this is your first build, read Install and Quick start in that order; the rest works as reference while you edit a series.

Written for 2.8.1 · checked on 2026-10-09

Start here

• Install

  What a machine needs, how to build the CLI, how to upgrade and remove it.

• Quick start

  Create a series, fetch sources, apply, build, verify. One page, ten minutes of reading.

Reference

• Patch format

  The header fields, ordering rules, how conflicts are resolved, and the built-in catalogue.

• Configuration

  Every key in bep.toml, profiles, environment variables and precedence.

• CLI reference

  Commands, global flags, output modes and exit codes.

• Troubleshooting

  The failures we see most often, with the check that identifies each one.

What changed in 2.8

The 2.8 line added preview support for Gecko-family source trees, replaced the per-patch cache key with a content hash, and made bep verify usable from CI. The patch header format did not change, so a series written for 2.7 loads without edits. The 2.8.0 notes list the migration details for the cache, which is the only part of the upgrade that touches files on disk.

Conventions used in these pages

• Shell blocks assume a POSIX shell and a checkout of the source archive. On Windows, run them in WSL2.
• Paths are relative to the series directory unless stated otherwise.
• Output blocks are copied from a real run on Linux x86_64 with clang 18 and 12 build jobs; timings will differ.
• Commands that change files are shown with the dry-run form first where one exists.

Documentation versions

These pages describe 2.8.1 only. When 2.9 ships, its docs replace these at the same addresses and a dated copy of the 2.8 pages stays online under /docs/ with a banner naming the version. There is no version switcher yet; that arrives with 3.0, together with the search index.