Generated Media Storage

Betamax produces screenshots, GIFs, and videos as build artifacts. These files can be large and regenerated frequently, which means committing them directly to source control will cause your repository history to grow quickly. Trimming that history later requires a history rewrite.

This page describes recommended patterns for handling generated media, based on how the Betamax project itself manages its own examples.

Keep Generated Outputs Out of Source Control

The most important rule is to add generated output directories to .gitignore.

.gitignore

examples/output/

Regenerated files create noisy diffs and bloat the repository. Betamax itself follows this pattern: the examples/output/ directory is ignored and its contents are never committed. Rust projects usually already ignore target/, which also covers target/betamax-examples/ in this repository.

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

Committing generated media is appropriate when the file is small, stable, and serves as intentional test data. A small PNG snapshot used in a visual regression test is reasonable to commit because a change to the snapshot means the rendering changed intentionally.

Large GIFs regenerated on every release should never be committed.

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

For most projects, the recommended combination is:

1. Ignore all generated output directories in .gitignore.
2. Attach final demo assets to GitHub Releases for stable documentation links.
3. Use a web host for media that belongs to a documentation site.
4. Upload intermediate outputs as CI artifacts for pull request review.
5. Commit only small stable test fixtures.