Metadata-Version: 2.4
Name: cowfs
Version: 0.2.8
Summary: Copy-on-Write Filesystem - a FUSE-based versioning filesystem
Author: Atikul Islam Munna
License-Expression: MIT
Keywords: copy-on-write,deduplication,filesystem,fuse,versioning
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.11
Requires-Dist: pyfuse3>=3.3.0; platform_system == 'Linux'
Requires-Dist: rich>=13.0.0
Requires-Dist: trio>=0.22.0
Requires-Dist: typer>=0.9.0
Provides-Extra: blake3
Requires-Dist: blake3>=0.4.0; extra == 'blake3'
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs<2.0.0,>=1.6.0; extra == 'docs'
Description-Content-Type: text/markdown

# COWFS - Copy-on-Write Filesystem

[![PyPI](https://img.shields.io/pypi/v/cowfs)](https://pypi.org/project/cowfs/)

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

```bash
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

```bash
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

```bash
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

```bash
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](RELEASE.md).
- Expected tag format: `vX.Y.Z` (example: `v0.2.0`).

### Release Checklist

```bash
# 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
