ZipXP / Documentation

Getting started

Everything you need to run, use, verify and package ZipXP. It's a Windows 11 app built with C#, WPF and .NET 10, using ordinary NTFS compression.

Pre-release 0.2. This is an unsigned build under active development. The development checks pass, but that doesn't make it production-ready or guarantee any amount of savings. Use disposable copies of your data for now.

Quickstart

ZipXP needs Windows 11 and a local NTFS drive. Install the latest release for your user from Windows PowerShell. It needs no administrator rights:

PS> curl.exe -fsSL https://kiranscript.github.io/zipxp/install.ps1 -o "$env:TEMP\zipxp-get.ps1"
PS> powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\zipxp-get.ps1"

The script downloads the release ZIP, verifies its SHA-256, runs the per-user installer and cleans up. Add -StartAtLogin, -Launch or -Version 0.2.0 after -File … if you want them. The checksum catches a damaged download. The release also carries a GitHub build attestation, which the script verifies if the GitHub CLI is installed and signed in (-RequireAttestation makes that mandatory). The build is not code-signed. Until the first release is published, or if you'd rather build it yourself, use the .NET 10 SDK:

PS> git clone https://github.com/kiranscript/zipxp.git
PS> cd zipxp
PS> dotnet run --project src/ZipXP.App/ZipXP.App.csproj

Then choose Managed folders → Add folder…, pick a test folder that holds copies of some documents, and read the estimate.

From WSL

From the repository root:

$ ./scripts/dev.sh

This launches the native Windows app using Windows dotnet.exe. It looks on PATH, in C:\Program Files\dotnet, and in a local C:\Temp\zipxp-dotnet SDK. Set WINDOWS_DOTNET_EXE to another executable's WSL path if needed. A Linux SDK can't run WPF.

Launcher options

FlagWhat it does
--freshEmpty throwaway data. Your real data is untouched.
--rebuildDeletes bin/ and obj/ first, so nothing stale is reused.
--resetErases your real saved data (asks for confirmation), then starts empty.
--data-dir 'C:\…'Runs an isolated instance against a Windows path.

Erasing data doesn't undo compression: files that are already compressed stay compressed. Press Ctrl+C to stop a dev run. The launcher asks the app to quit cleanly, and force-ends it after about 10 seconds if it doesn't.

Using ZipXP

  1. Add a folder. Select Managed folders → Add folder… and choose a local fixed NTFS folder, such as C:\zipxp-test. This starts a read-only analysis. WSL and UNC folders aren't supported.
  2. Inspect. Folder rows show policy, known logical and allocated totals, candidate bytes, status, scan time, and how many directories have Windows' own compression flag set. Double-click a folder in Insights to drill down, or choose Largest files.
  3. Turn on automation. Open Folder settings. Subfolder inclusion and battery behavior are on the first screen. Exclusions, size and benefit thresholds, quiet period, cooldown, schedule and free-space reserve are under Advanced options.
  4. Let it run. Eligible files are queued. New, copied-in, replaced and changed files are found through notifications and periodic scans. The recommended quiet period is 60 seconds, and reconciliation runs every two minutes. Busy files retry with backoff.
  5. Close the window. The tray worker keeps running. Start when I sign in registers the current launch command. Pause all or Pause folder stops new operations after the current one. Quit ZipXP finishes the current file, then exits and keeps pending work saved.
  6. Review activity. Search and filter outcomes, copy diagnostics, and retry selected failures. Retrying doesn't turn disabled automatic policies back on.
Explicit by design. Adding a folder never compresses it. Compress now is a one-off job that doesn't turn on future automation. Every recursive action shows a scope preview first.

Undo & stopping

  • Restore original size… (Overview, Managed folders, or Storage insights) decompresses files so they take their full space again. Nothing is deleted. It first turns off automatic compression for that folder and cancels pending compression.
  • Turn off Windows' own folder compression (More menu) is a separate job that clears the per-folder flags that make Windows compress new files automatically. It only touches directories within the policy scope. Files already compressed stay compressed.
  • Stop managing this folder (More menu) removes the folder, its observations and its future jobs. Your files and their folders' compression flags stay as they are. Past measurements are kept.

Decompression doesn't clear those folder flags. Its preview reports which folders still have them, any incomplete coverage, entries it left out, and the free space the largest single operation needs. Pausing or resuming the worker doesn't change the flags either. Windows applies them to new files even while ZipXP is closed, and in doing so it ignores ZipXP's exclusions and size limits.

Storage accounting

All file measurements cover the primary data stream. Directory metadata and named streams are excluded. Unknown sizes display a dash. The UI keeps four quantities separate:

  1. Volume usage and free space: current drive statistics, including activity from every other application.
  2. Managed allocation: known primary-stream allocations from each folder's latest scan, with scan timestamps and how much coverage is unknown. This isn't a single point-in-time snapshot of the volume.
  3. Estimated opportunity: three 32 KiB Deflate samples per eligible file, scaled up as a heuristic. NTFS uses a different algorithm, so this isn't a promise.
  4. Net measured reduction: signed before − after allocation for successful operations where the file's identity, length and last-write time stayed the same. Decompression growth is negative. A signed daily ledger keeps this total. It records each job once, survives restarts, and isn't affected when detailed history is pruned.

The history chart plots scan allocations at actual scan times. Amber bars mean coverage was incomplete or unknown.

Boundaries

  • Local fixed NTFS only. ZipXP won't manage drive roots, Windows or Program Files locations, UNC or device paths, WSL filesystem roots, or paths that pass through reparse points.
  • Hidden, system, encrypted, sparse, offline, read-only and multi-hard-link files are never changed.
  • Manual and automatic compression works on files from 64 KiB to 256 MiB, the tested range. Files outside that range aren't compressed yet, and policies can't raise the maximum.
  • Compression keeps a reserve of at least 256 MiB free. Decompression needs the file's full logical size plus that reserve. When space is short, the queue waits.
  • One file changes at a time, with a 500 ms worker interval. Each folder's scan stops at 100,000 observations and says so. Split very large folders into smaller ones that don't overlap.
  • No deletion, deduplication, cloud or network support, WOF, archive replacement, automatic elevation, or telemetry.
Native operations, identity checks and sharing restrictions make races less likely. They don't guarantee data integrity against every possible concurrent filesystem change.

State & recovery

State lives in %LOCALAPPDATA%\ZipXP\StorageManager\storage.sqlite3, plus its SQLite WAL/SHM files. SQLite is supplied by Windows' own winsqlite3.dll. There are no external NuGet or UI packages.

After a crash, jobs that were running become retry records, and each file's actual state and identity are checked again. Files changed while ZipXP was closed are found on startup. To back up, exit the tray worker normally and copy the state directory. Newer schema versions are rejected by older builds.

Known issues

After a restore, the app can measure a file's allocation before its handle is closed. That overstates growth for some file sizes and can show a small negative savings total. The files themselves aren't affected. Tracked in #2. A fix (#4) is merged on a branch but hasn't reached main yet.

Build & verify

# From the repository root on Windows
PS> .\scripts\check.ps1
PS> .\scripts\check.ps1 -Dotnet C:\Temp\zipxp-dotnet\dotnet.exe

The check harness uses the real core library on a fresh, disposable NTFS directory. It tests real compression, hashes, locks, hard links, folder compression flags, file replacements and the automatic worker. It also launches the actual WPF window and navigates it through native UI Automation. See the validation record for what has been tested and what's still missing.

Publish & install

PS> .\scripts\publish.ps1
PS> .\scripts\package-check.ps1
# From the extracted ZIP
PS> .\install.ps1 -StartAtLogin -Launch

Publishing produces a self-contained Windows x64 app and a ZIP under artifacts\. It doesn't need a separate .NET runtime. Without a signing certificate, the package is labeled unsigned. The installer works per user, under %LOCALAPPDATA%\Programs\ZipXP Storage Manager, and never force-kills a running process. uninstall.ps1 removes the app but leaves your managed files and database intact.

Source layout

src/ZipXP.Core/          Models, native handles/identities, SQLite store, analysis, rules, worker
src/ZipXP.App/           WPF dashboard, controls, tray/single-instance/startup
tests/ZipXP.Checks/      Real-service policy, native, persistence and automation checks
tests/ZipXP.FolderTest/  Helper used by scripts/test-existing-folder.ps1
scripts/                 dev.sh (WSL launcher), check, publish, install, uninstall
docs/                    Usage, how it works, safety, install, development, validation
website/                 This site

A few internal identifiers still say StorageManager on purpose, so existing installs keep their data and startup entries: the data folder, the executable, the sign-in registry value, the single-instance name, and the install folder. The full reference lives in docs/ in the repository.