DevLog 20250927: Use Fossil as Binary Asset VCS

Fri, 17 Oct 2025 14:50:27 +0000

It's clean and elegant.

Overview

As discussed in a previous post about binary file version control, keeping binaries well-versioned has always been challenging.

Years ago, when I first discovered SQLite, I also found Fossil. At that time, it didn't meet my needs - Git proved far better for collaboration and text-based workflows (especially with GitHub and GitHub Desktop).

However, Fossil may perform better for binary files under ~2GB, provided some manual bookkeeping and syncing.

Beyond versioning, Fossil offers several useful built-in tools:

Chatroom: Configurable 7-day ephemeral chat for authorized users. Supports HTTP API.
Wiki
Embedded Documentation
Tech Notes
Web UI Server
Direct file views: HEX, Text, Download
Forum: Permanent records; CDN support for images
Bug Tracking / Tickets / Issues
Full-text search

Framework

This framework describes how I'm beginning to use Fossil alongside Git for version control.

Using Fossil + Git

The plan is simple: Use git for text files; fossil for binary assets.

# Create repo
cd "<Repo Folder>"
fossil init ../MyRepo.fossil    # The convention is to create fossil repository outside the repo folder
fossil open -k ../MyRepo.fossil # Creates the _FOSSIL_ tracking file; -k skips checkout

# Create fossil-settings (See commit message below)
mkdir -p .fossil-settings
printf ".git\n.git/*\n.gitignore\n" > .fossil-settings/ignore-glob
fossil add .fossil-settings
fossil commit -m "Add Fossil ignore rules for Git files"

# Manually ignore files already tracked by Git, then commit again if needed
# fossil changes
# fossil commit -m "Update ignore file"

# In Git (e.g. via GitHub Desktop), ignore Fossil's contents, especially:
# *.fossil
# _FOSSIL_

# Treat all files as binary
printf "*" > .fossil-settings/binary-glob
fossil add .fossil-settings/binary-glob
fossil commit -m "Treat all files as binary in Fossil"

# Inspect
# fossil changes
# fossil extras

fossil add .
fossil commit -m "Initial Fossil import alongside Git"

This setup cannot keep Fossil and Git perfectly synchronized. Manual bookkeeping is necessary to restore past states accurately.

Summary

Key conventions:

Keep the .fossil file outside the Git repo folder.
.fossil-settings/binary-glob: mark all files as binary.
.fossil-settings/ignore-glob: define ignore patterns.
_FOSSIL_ and .fossil-settings can be deleted safely.

Quick Reference

Common commands:

fossil init <Repo> [--project-name <Name>] - create repo; edit name later in UI if omitted
fossil add . - add all
fossil add <File> - add file
fossil rm <File> - remove file
fossil commit -m <Message> - commit all local changes
fossil commit file1.c file2.h -m <Message> - commit specific files
fossil open --keep <DB> - open repo without checkout
fossil open --force <DB> - open repo, overwrite with latest
fossil status or fossil info - show repo info
fossil changes - list modified tracked files
fossil extras - list untracked files
fossil diff - show content changes
fossil timeline - history view
fossil ui [<Repo>] - launch web UI
fossil server [<Repo>] - start web server for push/pull

The typical git status is achieved with fossil changes + fossil extras.

Recipes

Ignore Blender versioning files

Use this pattern:

*.blend[0-9]*

Importing Git Repos

Not required here, but reference: https://fossil-scm.org/home/doc/trunk/www/inout.wiki

Stashing and Committing Specific Files

Fossil lacks Git's staging (git add -p) feature. The checkout directory is treated as one working tree snapshot. Still, you can commit selectively.

Commit specific files

You can pass the filenames explicitly to fossil commit:

fossil commit file1.c file2.h

This will commit only the listed files, even if you changed other files in the checkout. The other modified files will stay uncommitted.

Use stash to isolate changes

If you want to set aside changes temporarily:

Stash away all changes: fossil stash
Reapply only the files you want: fossil stash pop file1.c file2.h
Commit those files: fossil commit file1.c file2.h
Optionally reapply remaining changes: fossil stash pop

Revert unwanted files

If you've edited several files but only want to commit some:

fossil revert fileX.c fileY.c

This discards edits to those files, leaving only the desired ones for commit. Use stash first if you want to preserve them.

References

Learn Fossil quickly:

Quickstart Guide

Coder Legion - Recent posts tagged fossil