Virtual Filesystem (VFS)

Mount Dits repositories as virtual drives, accessing files on-demand without downloading the entire repository.

Overview

The Virtual Filesystem feature lets you browse and work with repositories as if they were local drives, while only downloading the data you actually access. This is transformative for large video projects:

On-Demand Access

Only download chunks when files are actually read. Browse a 500GB repository using just megabytes of storage.

Instant Mount

Mount any branch or commit instantly. No waiting for downloads - files appear immediately and load as needed.

Smart Caching

Frequently accessed data is cached locally. Subsequent accesses are as fast as local disk.

Requirements

VFS requires a FUSE implementation on your system:

Platform	FUSE Implementation	Install Command
macOS	macFUSE	brew install macfuse
Linux	FUSE3	apt install fuse3
Windows	Dokany	Download from GitHub

macOS System Extension

macFUSE requires enabling a system extension. After installing, go to System Preferences → Security & Privacy → General and allow the extension, then restart.

Basic Usage

Mount a Repository

# Mount to default location (/Volumes/dits-<repo> on macOS)
$ dits mount

Mounting repository at /Volumes/dits-my-project
Repository mounted. Press Ctrl+C to unmount.

# Mount to specific path
$ dits mount /path/to/mountpoint

# Mount in background
$ dits mount --background

# Mount specific branch
$ dits mount --ref feature/audio

# Mount specific commit
$ dits mount --ref a1b2c3d

Use the Mounted Repository

# Browse files
$ ls /Volumes/dits-my-project/footage/
scene1.mov  scene2.mov  scene3.mov

# Open in Finder/Explorer
$ open /Volumes/dits-my-project/

# Open in NLE
# Just navigate to the mounted path in your video editor

# Copy files (triggers download)
$ cp /Volumes/dits-my-project/footage/scene1.mov ./local/

Unmount

# If running in foreground, press Ctrl+C

# If running in background
$ dits unmount
Unmounted /Volumes/dits-my-project

# Force unmount
$ dits unmount --force

# On macOS, also works with:
$ umount /Volumes/dits-my-project

Configuration

Mount Options

[mount]
    # Default mount point pattern
    defaultPath = /Volumes/dits-<repo>

    # Cache size for mounted files
    cacheSize = 10GB

    # Read-ahead buffer size
    readAhead = 16MB

    # Connection pool size
    connectionPool = 8

    # Timeout for remote requests (seconds)
    timeout = 30

Command-Line Options

$ dits mount --help

Usage: dits mount [OPTIONS] [PATH]

Arguments:
  [PATH]  Mount point path

Options:
      --ref <REF>           Branch or commit to mount
      --read-only           Mount as read-only
      --background          Run in background
      --cache-size <SIZE>   Cache size (e.g., "10GB")
      --read-ahead <SIZE>   Read-ahead buffer
      --no-cache            Disable local caching
  -v, --verbose             Verbose output

Access Patterns

On-Demand Hydration

When you access a file through VFS, Dits fetches only the chunks needed:

# Opening a 10GB file in video editor
# 1. Editor reads file header → Dits fetches first few chunks
# 2. Editor seeks to timecode → Dits fetches chunks at that position
# 3. Playback → Dits streams chunks in sequence

# Result: Only fetched what was needed (maybe 500MB)
# instead of downloading entire 10GB file

Prefetching

Dits intelligently prefetches data based on access patterns:

# Sequential read detected
# → Prefetch next chunks in background

# Video scrubbing detected
# → Prefetch keyframes around current position

# Directory listing
# → Prefetch metadata for visible files

Working with Video Editors

Premiere Pro

# Mount the repository
$ dits mount --background

# In Premiere:
# 1. File → Import
# 2. Navigate to /Volumes/dits-my-project/
# 3. Import footage as normal

# Premiere will read files through VFS
# Only accessed frames are downloaded

DaVinci Resolve

# Mount with read-ahead optimized for Resolve
$ dits mount --read-ahead 32MB --background

# Resolve prefers larger read buffers
# This improves playback performance

Performance Tips

Use proxy files: Mount and work with proxy resolution, then switch to full-res for final render
Cache commonly used footage: Pin frequently accessed files to local cache
Render locally: Copy files needed for render to local disk first

Cache Management

View Cache Status

$ dits mount-cache status

VFS Cache Status:
  Location: ~/.cache/dits/vfs
  Size: 8.2 GB / 10 GB
  Entries: 1,234 chunks

Most accessed files:
  footage/scene1.mov      2.3 GB (85% cached)
  footage/scene2.mov      1.8 GB (62% cached)
  project.prproj          45 MB  (100% cached)

Manage Cache

# Pre-cache specific files
$ dits mount-cache fetch footage/scene1.mov
Caching footage/scene1.mov... 100% (10.2 GB)

# Clear cache
$ dits mount-cache clear
Cleared 8.2 GB from VFS cache

# Set cache size
$ dits config mount.cacheSize 50GB

Read-Only vs Read-Write

Read-Only Mount (Default)

Safe for browsing and importing into applications:

$ dits mount --read-only

# Files can be read but not modified
# Best for collaborative workflows

Read-Write Mount

Allows modifications that sync back to the repository:

$ dits mount --read-write

# Changes are staged automatically
# Use 'dits commit' to save changes

# Note: Large file writes may be slow
# Consider working locally for heavy edits

Troubleshooting

Mount Fails with Permission Error

# macOS: Enable FUSE extension
System Preferences → Security & Privacy → General
Allow "osxfuse" or "macfuse"
Restart your Mac

# Linux: Add user to fuse group
$ sudo usermod -a -G fuse $USER
# Log out and back in

Slow Performance

# Check network connection
$ dits mount-cache ping
Remote: 45ms latency

# Increase cache size
$ dits config mount.cacheSize 50GB

# Pre-cache needed files
$ dits mount-cache fetch footage/

Files Not Appearing

# Ensure FUSE is properly installed
$ which fusermount  # Linux
$ kextstat | grep fuse  # macOS

# Check mount status
$ mount | grep dits

# Try with verbose output
$ dits mount -v