Generated media storage

Keep generated screenshots, GIFs, and videos in ignored directories. Host README demos as release assets, publish site media with the site, and upload review recordings as CI artifacts. Committing each regenerated file grows repository history; removing that history later requires a rewrite.

Keep generated outputs out of source control

Add generated output directories to .gitignore:

.gitignore

examples/output/

Betamax ignores examples/output/ and target/, including the local preview directory target/betamax-examples/.

If your project uses coding agents, add a short instruction so generated files do not show up in pull requests:

Keep generated Betamax media in ignored output directories such as `examples/output/` or `target/`.
Track only small, stable screenshots or state files when they are intentional test fixtures.
This keeps regenerated binary files from bloating Git history and creating noisy diffs.

Use release assets for stable demos

When you want to display a GIF or screenshot in your README or docs, host the file externally rather than committing it to the repository.

GitHub Release assets are a good default for stable, versioned demo media:

1. Build your tapes in CI.
2. Attach the generated GIF or PNG to the GitHub release.
3. Reference the release asset URL in your README or docs.

![Demo](https://github.com/your-org/your-repo/releases/download/v1.0.0/demo.gif)

Betamax uses this approach for all GIF previews shown in its own README.

Use CI artifacts for review media

CI artifacts are a good option for ephemeral or pre-release media that reviewers need to inspect before the final docs asset exists:

- name: Upload rendered media
  uses: actions/upload-artifact@v4
  with:
    name: betamax-examples
    path: examples/output/

CI artifacts are not a permanent hosting choice. They expire according to the retention policy for your repository or CI provider, so use them for pull request review rather than long-lived README or documentation links.

Use a web host for site assets

A dedicated web host is another good option when the media belongs to a documentation site instead of a release. GitHub Pages, Cloudflare Pages, an object store, or another static host can serve stable URLs without putting regenerated binary files in the Git history.

This works especially well when the site build already has a deployment pipeline. Render the media in CI, copy the chosen outputs into the site artifact, and let the host publish them with the rest of the documentation.

Commit small, stable fixtures only when intentional

A small PNG baseline for a visual regression test can belong in source control. Review changes to it alongside the renderer change that produced them. Keep large, frequently regenerated GIFs in release assets or on a web host.

Use Git LFS when media must be tracked

Git LFS is an option when media needs to live in the repository, but should not be stored directly in normal Git history. For example, the Ratatui website tracks image formats such as .png, .gif, .svg, .webp, and .xcf with Git LFS so the site can keep curated assets in the checkout without adding every binary revision to ordinary Git objects.

Use Git LFS intentionally. It adds setup requirements for contributors and consumes LFS storage and bandwidth, so it is a better fit for curated site assets than for frequently regenerated build outputs.

Tradeoffs at a glance

Approach	Pros	Cons
Commit generated media	Instantly browsable	Repository bloat on each regeneration
Release assets	Stable public URLs; zero repo bloat	Requires a tagged release
CI artifacts	Available during PR review	Expire after retention window
Web host	Stable site URLs	Requires a deployment path
Git LFS	Keeps large assets in the checkout	Adds contributor setup and LFS storage