mirror of
https://github.com/borgbackup/borg.git
synced 2026-09-01 22:23:19 +02:00
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
59 lines
2.1 KiB
Markdown
59 lines
2.1 KiB
Markdown
# 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.
|
|
|
|
[expect]: https://core.tcl-lang.org/expect/index
|
|
[asciinema]: https://asciinema.org/
|