DevLog 20250927: Use Fossil as Binary Asset VCS

Question

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:

1. Stash away all changes: fossil stash
2. Reapply only the files you want: fossil stash pop file1.c file2.h
3. Commit those files: fossil commit file1.c file2.h
4. 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