Virtual Filesystem Commands

dits mount [OPTIONS] [MOUNTPOINT]

--read-only           Mount as read-only (no modifications)
--allow-other         Allow other users to access mount
--commit <REF>        Mount a specific commit or tag
--branch <NAME>       Mount a specific branch
--background, -b      Run mount in background
--cache-size <SIZE>   Set local cache size (default: 10GB)
--cache-dir <PATH>    Override cache directory
--prefetch            Enable aggressive prefetching
--prefetch-size <N>   Prefetch next N chunks
--no-sparse           Disable sparse file support
-v, --verbose         Show detailed mount information

# Mount to default location
$ dits mount

Mounting repository at /Volumes/dits-project...
Virtual filesystem ready.

  Repository: my-project
  Branch: main (abc1234)
  Files: 1,234 available
  Mode: read-write
  Cache: 10 GB (0 bytes used)

Press Ctrl+C to unmount (or use 'dits unmount')

# Mount to specific location
$ dits mount /mnt/project

# Mount in background
$ dits mount -b /mnt/project
Mounted at /mnt/project (pid: 12345)

# Mount as read-only
$ dits mount --read-only /mnt/project

# Mount specific commit (great for reviewing old versions)
$ dits mount --commit v1.0 /mnt/v1-release

# Mount specific branch
$ dits mount --branch feature/color-grade /mnt/color-grade

# Mount with large cache for heavy editing
$ dits mount --cache-size 100GB /mnt/project

# Mount with prefetching for smoother playback
$ dits mount --prefetch --prefetch-size 10 /mnt/project

Mount Architecture:

┌─────────────────────────────────────────────────────┐
│                   Your Application                   │
│              (NLE, Media Player, etc.)               │
└────────────────────────┬────────────────────────────┘
                         │ Standard file I/O
                         ▼
┌─────────────────────────────────────────────────────┐
│                 FUSE Mount Point                     │
│                 /Volumes/dits-project                │
└────────────────────────┬────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│                   Dits VFS Layer                     │
│  • File → Chunk mapping                              │
│  • Prefetching logic                                 │
│  • Cache management                                  │
└────────────────────────┬────────────────────────────┘
                         │
           ┌─────────────┴─────────────┐
           ▼                           ▼
   ┌──────────────┐           ┌──────────────┐
   │ Local Cache  │           │    Remote    │
   │ .dits/cache/ │           │   Storage    │
   └──────────────┘           └──────────────┘

dits unmount [OPTIONS] [MOUNTPOINT]

-f, --force         Force unmount (may lose unsaved data)
--all               Unmount all Dits mounts
--wait              Wait for operations to complete

# Unmount default location
$ dits unmount
Unmounting /Volumes/dits-project...
Syncing pending changes... done
Unmounted successfully.

# Unmount specific path
$ dits unmount /mnt/project

# Force unmount (when mount is stuck)
$ dits unmount -f /mnt/project
Warning: Force unmounting. Unsaved changes may be lost.
Unmounted.

# Unmount all mounts
$ dits unmount --all
Unmounting 3 mounts...
  /Volumes/dits-project... done
  /mnt/v1-release... done
  /mnt/color-grade... done

dits cache-stats [OPTIONS]

--json              Output in JSON format
--clear             Clear the cache
--top <N>           Show top N cached files
-v, --verbose       Show detailed statistics

$ dits cache-stats

VFS Cache Statistics:

  Cache Location: ~/.cache/dits/vfs
  Cache Limit: 10 GB
  Current Size: 4.2 GB (42%)

  Cached Chunks: 4,567
  Hit Rate: 94.2% (last hour)
  Miss Rate: 5.8%

  Bytes Read: 12.5 GB
  Bytes from Cache: 11.8 GB (94.4%)
  Bytes from Remote: 700 MB (5.6%)

Recent Activity:
  Chunks fetched: 234 (last hour)
  Chunks evicted: 45 (LRU)
  Prefetch hits: 189 (80.8%)

# Show top cached files
$ dits cache-stats --top 10

Top Cached Files:
  File                              Chunks    Size
  ─────────────────────────────────────────────────
  footage/scene01.mov               456       456 MB
  footage/scene02.mov               389       389 MB
  project.prproj                    12        48 MB
  ...

# Clear the cache
$ dits cache-stats --clear
Clear VFS cache (4.2 GB)? [y/N] y
Cache cleared.

# Verbose stats
$ dits cache-stats -v

Cache Configuration:
  Path: ~/.cache/dits/vfs
  Max Size: 10 GB
  Eviction Policy: LRU
  Prefetch: enabled (5 chunks ahead)
  ...

# [PLANNED] Clone metadata only (fast!)
$ dits clone --filter blob:none https://dits.example.com/huge-project
Cloning into 'huge-project'...
Metadata fetched: 15 MB
Repository ready (large repositories available on demand)

# Mount and start working immediately
$ cd huge-project && dits mount /mnt/huge
Files available at /mnt/huge

# Open files - they stream on demand from the remote
$ vlc /mnt/huge/footage/scene01.mov
# Video plays immediately, chunks stream as needed

# Mount multiple versions simultaneously
$ dits mount --commit v1.0 /mnt/v1 &
$ dits mount --commit v2.0 /mnt/v2 &
$ dits mount --branch main /mnt/current &

# Compare files across versions
$ diff /mnt/v1/config.json /mnt/v2/config.json

# Reference old footage while working on new cut
$ ls /mnt/v1/footage/
$ ls /mnt/current/footage/

# On a remote machine with limited storage
$ dits mount --cache-size 5GB /mnt/project

# Edit uses local cache intelligently
# - Recently accessed chunks stay in cache
# - Rarely used chunks evicted automatically
# - Prefetching loads chunks before you need them

# Check cache efficiency
$ dits cache-stats
Hit Rate: 96.5%  # Most reads from local cache