b8476563cadocs/misc/asciinema/README.rst was picked up by sphinx but not part of any toctree, causing a "document isn't included in any toctree" warning in CI. As this README is developer notes, not part of the built docs, rename it to README.md: conf.py has source_suffix = ".rst", so sphinx ignores markdown. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRRe8BEFk4sV2GHVxDRo5A |
||
|---|---|---|
| .. | ||
| borg2-demo.cast | ||
| Containerfile | ||
| demo-data.py | ||
| demo.tcl | ||
| entrypoint.sh | ||
| README.md | ||
| record.exp | ||
| record.sh | ||
The borg2 demo screencast
The screencast linked from our README and website is not recorded by hand:
demo.tcl is "typed" into a shell by expect, while asciinema records the
result. So, when borg's output changes, we just record it again.
Do not run these scripts directly on your machine: they create users,
mount filesystems and write to /media. They are meant to run inside the
container defined by Containerfile.
Recording
./record.sh [output directory] # uses podman, set ENGINE=docker for docker
This exports the borg sources of the git tag given by BORG_VERSION at the
top of record.sh, builds borg from them in a container, generates the demo
data and records the screencast to borg2-demo.cast. So, for a new release,
set BORG_VERSION to its tag (after tagging it) and record again.
While working on the demo itself, you can also record from your work tree:
BORG_VERSION=HEAD ./record.sh
Then have a look at it and upload it:
asciinema play borg2-demo.cast
asciinema upload borg2-demo.cast
Afterwards, update the links in README.rst (in the repository root) and on
borgbackup.org to point to the new screencast.
Editing the demo
demo.tcl contains the commands and comments that get typed, in the order
they appear in the screencast. Keep the typed lines below ~95 characters, the
recording uses a 100x30 terminal (see record.exp).
The lines we type are colored by type_line (comments, commands, options),
see the color array at the top of demo.tcl if you want other colors.
The output of the commands is not touched, it looks like in your terminal.
demo-data.py generates the data that gets backed up: compressible, but not
trivially repetitive, so that both compression and deduplication show
realistic numbers (see #6303).
Known quirks
borg extract runs with --noxattrs: when recording with rootless podman
on a SELinux host, restoring the security.selinux xattrs of the demo data
is not permitted, and the warnings about it would show up in the screencast.