COWFS - Copy-on-Write Filesystem

A userspace Copy-on-Write filesystem built with FUSE. Every write transparently creates a new version - enabling instant restore, snapshot tagging, and content deduplication.

Status

• Core FUSE read/write path implemented
• Version history + restore implemented
• GC implemented (--dry-run, --keep-last, --before)
• Snapshot lifecycle implemented (create, list, show, restore, delete)
• GitHub Actions CI workflow added (tests + coverage + required static analysis)
• Tag-based PyPI publishing implemented and validated (cowfs 0.2.4 live)

Quick Start

pip install cowfs

# Mount
cowfs mount ~/storage ~/mnt

# Use like a normal filesystem
echo "hello" > ~/mnt/test.txt
echo "world" > ~/mnt/test.txt

# Inspect version history and stats
cowfs history /test.txt --storage ~/storage
cowfs stats --storage ~/storage
cowfs log --storage ~/storage --limit 20

# Restore to an older version
cowfs restore /test.txt --version 1 --storage ~/storage

# Create and inspect snapshot
cowfs snapshot create baseline --storage ~/storage
cowfs snapshot list --storage ~/storage
cowfs snapshot show baseline --storage ~/storage

# Restore filesystem to snapshot
cowfs snapshot restore baseline --storage ~/storage
# keep files created after snapshot:
cowfs snapshot restore baseline --keep-new --storage ~/storage

# Garbage collection
cowfs gc --storage ~/storage --dry-run
cowfs gc --storage ~/storage --keep-last 3
cowfs gc --storage ~/storage --before "2026-01-01 00:00:00"

# Unmount when done
cowfs umount ~/mnt

CLI Commands

cowfs mount <storage_dir> <mount_point> [--debug]
cowfs umount <mount_point>

cowfs history <file_path> --storage <storage_dir> [--json]
cowfs restore <file_path> (--version <n> | --before "<datetime>") --storage <storage_dir> [--dry-run] [--json]
cowfs log --storage <storage_dir> [--limit <n>] [--action <name>] [--path-prefix <prefix>] [--since "<datetime>"] [--until "<datetime>"] [--json]

cowfs stats --storage <storage_dir> [--json]
cowfs gc --storage <storage_dir> [--dry-run] [--keep-last <n>] [--before "<datetime>"] [--json]

cowfs snapshot create <name> [--description "..."] --storage <storage_dir> [--json]
cowfs snapshot list --storage <storage_dir> [--json]
cowfs snapshot show <name> --storage <storage_dir> [--json]
cowfs snapshot restore <name> [--keep-new] --storage <storage_dir> [--dry-run] [--json]
cowfs snapshot delete <name> --storage <storage_dir> [--json]

Development

git clone https://github.com/yourusername/cowfs.git
cd cowfs
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Documentation Site

pip install "mkdocs>=1.6.0,<2.0.0" "mkdocs-material>=9.5.0"
mkdocs serve
# build static site:
mkdocs build

Release

• Tag-based publishing is configured in .github/workflows/publish.yml.
• See full release instructions in RELEASE.md.
• Expected tag format: vX.Y.Z (example: v0.2.0).

Release Checklist

# 1) bump version in pyproject.toml (example: 0.2.2)
git add pyproject.toml
git commit -m "Release 0.2.2"
git push origin master

# 2) create matching release tag
git tag v0.2.2
git push origin v0.2.2

# 3) after Publish workflow succeeds, verify install
pip install -U cowfs==0.2.2

Requirements

• Linux with FUSE support (libfuse3-dev)
• Python 3.11+
• Windows: use WSL2 (Ubuntu) for mount functionality