Files
lazygit/docs-master/dev/Demo_Recordings.md
Stefan HallerandClaude Opus 5.5 ff8d74971f Add a font with the branch drawing symbols for the demo recordings
The terminal that vhs records is xterm.js running in a browser, and the
xterm.js that ttyd bundles doesn't draw the branch drawing symbols
itself. So they have to come from a font, and SauceCodePro NF doesn't
have them, nor does any font that macOS comes with. The detailed commit
graph shows up as garbage.

Newer versions of xterm.js do draw the symbols, but only in the WebGL
renderer. vhs forces the canvas renderer, and xterm.js has removed that
since, so moving to a newer xterm.js would mean patching both ttyd and
vhs.

The Flog Symbols font has the symbols, but it draws its lines for a
smaller cell than the one xterm.js uses at our font settings. As a
fallback font, it leaves a gap at the edges of every cell, and each line
of the graph comes out dashed.

Add a copy of the font that fits the cells of the recordings. xterm.js
clips each character to its row, so the vertical strokes reach well
past the top and bottom of the cell and end exactly at the row's edges.
It doesn't clip a character to its cell horizontally, so the horizontal
strokes reach only a little way into the neighbouring cells. Any
further, and they would show past the start of a bend in the next cell.

Give the font a bold face with the same outlines. lazygit draws the
lines of the selected commit in bold, and without a bold face the
browser makes the symbols bold itself by thickening them. That leaves
gaps where they meet.

Add the script that made the font, and list the font after
SauceCodePro NF in demo/settings.tape so that the browser takes the
symbols from it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-05 18:29:35 +02:00

5.7 KiB

Demo Recordings

We want our demo recordings to be consistent and easy to update if we make changes to Lazygit's UI. Luckily for us, we have an existing recording system for the sake of our integration tests, so we can piggyback on that.

You'll want to familiarise yourself with how integration tests are written: see here.

Prerequisites

Ideally we'd run this whole thing through docker but we haven't got that working. So you will need:

# for recording; vhs drives ttyd and ffmpeg under the hood
brew install ttyd ffmpeg

# vhs 0.12.0 runs the tape, reports success and writes no video at all
# (https://github.com/charmbracelet/vhs/issues/787), so pin the release
# before it
go install github.com/charmbracelet/vhs@v0.11.0

# font with icons
wget https://github.com/ryanoasis/nerd-fonts/releases/download/v3.0.2/SourceCodePro.tar.xz && \
  tar -xf SourceCodePro.tar.xz -C ~/Library/Fonts && \
  rm SourceCodePro.tar.xz

# font with the branch drawing symbols of the commit graph
cp demo/fonts/FlogSymbolsDemo-*.ttf ~/Library/Fonts

Creating a demo

Demos are found in pkg/integration/tests/demo/. They are like regular integration tests but have IsDemo: true which has a few effects:

  • The bottom row of the UI is quieter so that we can render captions
  • Fetch/Push/Pull have artificial latency to mimic a network request
  • The loader at the bottom-right does not appear

In demos, we don't need to be as strict in our assertions as we are in tests. But it's still good to have some basic assertions so that if we automate the process of updating demos we'll know if one of them has broken.

You can use the same flow as we use with integration tests when you're writing a demo:

  • Setup the repo
  • Run the demo in sandbox mode to get a feel of what needs to happen
  • Come back and write the code to make it happen

Adding captions

It's good to add captions explaining what task if being performed. Use the existing demos as a guide.

Setting up the assets worktree

We store assets (which includes demo recordings) in the assets branch, which is a branch that shares no history with the main branch and exists purely for storing assets. Storing them separately means we don't clog up the code branches with large binaries.

The scripts and demo definitions live in the code branches but the output lives in the assets branch so to be able to create a video from a demo you'll need to create a linked worktree for the assets branch which you can do with:

git worktree add .worktrees/assets assets

The mp4 of the recording will be stored in .worktrees/assets/demo/.

Recording the demo

Once you're happy with your demo you can record it using:

scripts/record_demo.sh <path>
# e.g.
scripts/record_demo.sh pkg/integration/tests/demo/interactive_rebase.go

The terminal size, font and colours live in demo/settings.tape, which the script sources into the tape it generates for the demo.

While you are still working on how a demo looks, pass --no-upload. That leaves the video in demo/output (which is git-ignored) and stops there, so you can watch it without uploading anything or touching the assets worktree:

scripts/record_demo.sh --no-upload pkg/integration/tests/demo/interactive_rebase.go

Including demos in README/docs

Recording a demo does three things with the mp4: it writes it to your assets worktree, it uploads a copy to GitHub's attachment store, and it posts that copy as a comment on the issue named by PUBLISH_ISSUE in the script. Then it prints the tag to embed:

<video src="https://github.com/user-attachments/assets/<uuid>" controls></video>

GitHub plays a video in a README only when it is served from its own attachment store. If you commit a video to the assets branch and link it the way we link the images, GitHub drops the whole <video> element when it renders the page. So the README reads the uploaded copy rather than the one in the assets worktree. Keep that one anyway, so that we still have the file if we ever need to upload it again. Stage it and raise a PR against the assets branch as you would for any other asset.

Attachment URLs are opaque and have no path we can predict, so a new recording of an existing demo means a new URL and an edit to the page that embeds it.

That comment on PUBLISH_ISSUE is not bookkeeping; it is what makes the video watchable. An uploaded attachment is readable only by people signed in to GitHub until some posted comment in the repository refers to it, and a README on a branch does not count. Skip that step and the video plays for you and 404s for everyone else, which is easy to miss because you are signed in. The script waits until the video can be fetched without a token before it prints the tag. Referring to an attachment once is enough and cannot be undone, so the comments could be deleted later, but leaving them gives us a dated list of every recording.

Uploading needs push access to the lazygit repository. If you don't have it, record the demo, then ask a maintainer to upload the mp4 for you.

Re-recording every demo on a page

Write the name of the demo above each video, so that we can find our way from a page back to the demo that produced it:

<!-- demo: commit_and_push -->
<video src="https://github.com/user-attachments/assets/<uuid>" controls></video>

GitHub drops the comment when it renders the page. With it in place, a change to demo/settings.tape or to lazygit's own appearance can be rolled out across every recording at once:

scripts/rerecord_demos.sh
# or, to look before you upload anything:
scripts/rerecord_demos.sh --no-upload

That re-records every demo the README embeds and rewrites each URL in place. Name other pages as arguments to do the same for them.