menu

DevLog 20250927: Use Fossil as Binary Asset VCS

BackerLeader posted Originally published at dev.to 3 min read

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:

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:

If you read this far, tweet to the author to show them you care. Tweet a Thanks

1 Comment

•

Interesting angle using Fossil just for binaries while keeping Git for text feels like a pragmatic split. What if more teams adopted that dual-tool approach instead of forcing one VCS to cover both extremes?

1 vote
•

@[Ben Kiehl] Hi Ben, thanks for the reply. In fact, it's quite common for teams in the gaming industry to use two version control systems: one for source code, the other for binary assets. It's just previously when it comes to binary VC people think of Perforce. The benefit of fossil is that it allows the repository to be stored inside a single (SQLite) file, thus removes the need of complex hosting setup.
In general, I think we should always use appropriate tools for corresponding tasks - and using Git with LFS tends to cause more problems than it solves.

1

More Posts

DevLog 20250806: "Change Version" - File Changes History-Only Version Control for Binary Assets

Methodox - Aug 6

Working with git on large projects with large binary assets.

Trent Polack - Jul 15

Fixing mistakes with Git

Hiruthic Sha - Aug 11

Mastering Collaborative Coding: A Deep Dive into Git Branching and Merging for Teams

Aditya Pratap Bhuyan - Jun 24

️ Obsidian: Restaurant's rating

Oscar Lopez - Feb 24
chevron_left