Skip to content

README.md

Latest commit

 

History

History
executable file
·
95 lines (72 loc) · 3.27 KB

README.md

File metadata and controls

executable file
·
95 lines (72 loc) · 3.27 KB

GameSave-VCS

GameSave-VCS provides automated version control for PC game saves, supporting both delta-based Git backups (via Dulwich), simple full-copy strategies, and an optimized chunked storage backend for massive save files.

Prerequisites

  • Python 3.13+
  • Bazel (7.4.1 recommended) - for hermetic builds
  • pip-tools (optional, for regenerating dependency locks)

Installation

Via pip (standard)

pip install -e .

Via Bazel (hermetic)

Bazel ensures all dependencies (including Python 3.13 itself) are managed hermetically.

# Build the project
bazel build //...

# Run CLI
bazel run //:gamesave -- <command>

Features

1. Retro TUI (Terminal User Interface)

A visually rich, 8-bit inspired interface for managing your saves.

bazel run //:gamesave -- tui

Requires textual and rich (included in Bazel build).

2. Multi-Strategy Backends

  • Git (Default): Efficient delta-based backups using dulwich.
  • Full-Copy: Simple timestamped directory mirrors with hard-link deduplication.
  • Chunked: optimized for files >100MB; splits files into chunks to deduplicate internal changes.

3. Smart Monitoring

  • Inotify (Linux): Zero-polling, kernel-level event monitoring.
  • Polling (Cross-platform): High-frequency hashing fallback for Windows/macOS.

Developer Guide

Automated Testing

We use pytest integrated with Bazel.

Run all tests

bazel run //:pytest -- tests/

Run tests with Coverage

Because Bazel runs tests in a sandbox, pytest-cov requires the absolute path to the source tree to map coverage data correctly.

bazel run //:pytest -- tests/ --cov=$(pwd)/gamesave_vcs --cov-report=term-missing

Dependency Management

Dependencies are locked in requirements_lock.txt. If you modify pyproject.toml, you must regenerate the lockfile.

Regenerating the Lockfile

We use pip-compile with specific flags to avoid circular dependencies in the Bazel graph (specifically stripping extras from transitive dependencies like markdown-it-py).

pip install pip-tools
pip-compile --extra test --strip-extras --generate-hashes --output-file=requirements_lock.txt pyproject.toml

Troubleshooting Bazel

  • Read-only Filesystem Errors: Tests must use the tmp_path fixture. Writing to absolute paths like /dst will fail in the Bazel sandbox.
  • ModuleNotFoundError: Ensure the dependency is added to the deps attribute in BUILD.bazel AND included in requirements_lock.txt.
  • Async Test Failures: Ensure pytest-asyncio is installed and the asyncio_default_fixture_loop_scope is considered if using older pytest versions.

CLI Reference

Command Description Example
add <name> [path] Register a game gamesave add EldenRing ~/saves/er
backup <name> Manual backup gamesave backup EldenRing
watch <name> Start background monitor gamesave watch EldenRing --interval 5
list Show backup history gamesave list --game EldenRing
restore [spec] Restore to state gamesave restore repo@commit_hash
tui Launch Retro Manager gamesave tui

File Locations

  • Config: ~/.gamesave-vcs/config.json
  • Backups: ~/.gamesave-vcs/backups/