VSS Copy ⚡️

Effortless, consistent Windows directory backups — powered by Volume Shadow Copy (VSS (Vegeta Super Sayajin)) for point‑in‑time snapshots. Configure once with a tiny profile file, then copy with confidence. 🛡️📦

Table of Contents

• What It Does
• How It Works (Technical Overview)
• Requirements
• Build
• Usage
  • Profile File Format
  • Command-Line
  • Destination Path Mapping
• Why VSSCopy
• Quickstart
• Architecture
• GeoJSON
• FAQ
• Troubleshooting
• Roadmap
• Call to Action
• Limitations & Caveats
• Project Structure
• License

What It Does ✅

• Reads a profile file (include/exclude lines) 📄
• Optionally creates a VSS snapshot for consistent, point‑in‑time copies 🧊
• Recursively copies directories to a destination, preserving structure 📂➡️📁
• Logs progress to console and to copy.log in the app folder 🖥️📝

How It Works (Technical Overview)

• Entry point: Init.Main(string[] args) parses command‑line arguments using FluentCommandLineParser (Fclp).
• CLI flow: CLI.Main(profilePath, destination, useShadow, registry) orchestrates copying.
  • Loads profile lines. + prefix includes a directory; - prefix excludes a directory.
  • If --registry is enabled, sets two VSS‑related registry values:
    • HKLM\Software\Microsoft\Windows NT\CurrentVersion\SPP\CreateTimeout = 1200000 (20 minutes)
    • HKLM\System\CurrentControlSet\Services\VSS\Settings\IdleTimeout = 1200000 (20 minutes)
  • If --shadow is enabled:
    • Creates a VSS snapshot for the drive of the first include path (e.g., C:\). Uses WMI Win32_ShadowCopy (ClientAccessible context) in \\localhost\root\cimv2.
    • Translates include paths to the snapshot device (e.g., \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopyN\...).
    • Copies files and directories to a destination path by replacing the snapshot device prefix with the destination root.
    • Deletes the snapshot after copying.
  • If --shadow is disabled:
    • Copies directly from the live filesystem. The destination path is computed by replacing the source drive designator (e.g., C:) with the destination root.
• Copy engine: FileIO.DirectoryCopyAsync() performs recursive copying with parallel file copies (Parallel.ForEach) and basic excludes.
• Logging: NLog writes Info+ messages to console and copy.log.

Requirements 📎

• OS: Windows only (uses WMI Win32_ShadowCopy and .NET Framework).
• Runtime: .NET Framework 4.8.
• Privileges:
  • Creating/deleting VSS snapshots typically requires administrative privileges.
  • The --registry option writes to HKLM and requires administrative privileges.
  • App manifest is asInvoker (no auto‑elevation) → run in an elevated console when using --shadow or --registry.

Build 🛠️

• Prerequisites: Visual Studio 2019/2022 on Windows with .NET Framework 4.8 SDK.
• Steps:
  1. Open VSSCopy.sln.
  2. Restore NuGet packages.
  3. Build the VSSCopy project (prefer x64 configuration when using VSS).
• Notes:
  • Uses Fody with Costura to embed dependencies into the executable.
  • Output type is Exe; startup object is VSSCopy.Init.

Usage 🚀

Profile File Format

A plain text file with one absolute path per line. Prefix determines behavior:

• +C:\Source\Folder — include this directory for copying.
• -C:\Source\Folder\SubfolderToExclude — exclude this directory from recursion.

Example backup.txt:

+C:\Users\Alice\Documents
+C:\Data\Projects
-C:\Data\Projects\node_modules
-C:\Users\Alice\Documents\Temp

Notes:

• Paths must be absolute. Include lines must start with +; exclude lines start with - (no space after the dash).
• The first include line determines the snapshot drive when --shadow is enabled (e.g., C:\).

Command-Line

VSSCopy.exe -p <absolute\path\to\profile.txt> -d <absolute\destination\root> [-s true|false] [-r true|false]

• -p, --profile (required): Absolute path to the profile file.
• -d, --destination (required): Absolute destination root path.
• -s, --shadow (optional): Create and use a VSS snapshot. Default: true.
• -r, --registry (optional): Write VSS timeout values to the registry. Default: false.
• -?, --help (optional): Show help.

Examples

• Snapshot copy (recommended for consistent backups):

VSSCopy.exe -p C:\profiles\backup.txt -d D:\Backup -s true

• Live copy without snapshot:

VSSCopy.exe -p C:\profiles\backup.txt -d D:\Backup -s false

• Adjust VSS timeouts (requires admin):

VSSCopy.exe -p C:\profiles\backup.txt -d D:\Backup -r true

Destination Path Mapping

• With --shadow: Destination is computed by replacing the snapshot device prefix (e.g., \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopyN) with the destination root.
• Without --shadow: Destination is computed by replacing the source drive designator (e.g., C:) with the destination root.

This preserves the directory structure under the destination root.

Why VSSCopy 💙

• Consistency by design: Point‑in‑time copies with VSS avoid partial reads from open files.
• Simple profiles: Human‑readable + includes and - excludes — no DSL to learn.
• Fast by default: Parallel file copying keeps throughput snappy on modern disks.
• Respectful backups: Existing files aren’t overwritten; repeated runs skip already copied files.
• Clear insights: Console + file logging show exactly what’s created, skipped, or excluded.
• Zero‑config packaging: Fody/Costura bundles dependencies for a single‑file style experience.

Quickstart ⚡

1. Create a profile file, e.g. C:\profiles\backup.txt:

+C:\Users\Alice\Documents
+C:\Data\Projects
-C:\Data\Projects\node_modules
-C:\Users\Alice\Documents\Temp

2. Run a snapshot copy (recommended):

VSSCopy.exe -p C:\profiles\backup.txt -d D:\Backup -s true

3. Check logs:

• Console output for progress
• copy.log in the executable folder for a persistent record

FAQ ❓

• Does VSSCopy overwrite existing files? No. If a destination file already exists, it’s skipped and logged.

• Can I back up from multiple drives in one run? Snapshot creation targets the drive of the first include path. To back up multiple drives with snapshots, run VSSCopy separately per drive.

• Is there a verbose mode? The code doesn’t implement a --verbose toggle; logging is controlled by NLog.config and set to Info+.

• Do excludes support wildcards? No. Excludes are exact, absolute paths (case‑sensitive matching).

Troubleshooting 🧯

• Access denied / snapshot fails: Run an elevated (Administrator) console, especially when using -s true or -r true.
• Registry write errors: --registry writes to HKLM and requires admin privileges.
• Profile load failures: Ensure the profile path is absolute and accessible; errors are logged as Fatal when the file can’t be read.
• Weird source path errors: The copy routine builds source paths internally and logs any issues. If errors appear frequently, verify that the included directories actually exist and are readable.
• Copy looks slow: Enable snapshot mode (-s true) to avoid contention with open files; ensure destination is on a fast disk.

Architecture 🧭

flowchart TD
  A[User Runs VSSCopy.exe] --> B[Init: Parse CLI args]
  B --> C{Use Shadow?}
  C -- Yes --> D[VssWMI: Create VSS snapshot]
  D --> E[Translate include paths to snapshot device]
  C -- No --> F[Use live filesystem paths]
  E --> G[FileIO: Parallel recursive copy]
  F --> G
  G --> H[NLog: Console + copy.log]
  E --> I[VssWMI: Delete snapshot]

Loading

GeoJSON 🗺️

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [13.405, 52.52] },
      "properties": {
        "site": "Berlin",
        "path": "C:\\Users\\Alice\\Documents",
        "kind": "+"
      }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [11.582, 48.135] },
      "properties": {
        "site": "Munich",
        "path": "C:\\Data\\Projects",
        "kind": "+"
      }
    }
  ]
}

Loading

Roadmap 🗺️

These are ideas for future development. They are not implemented.

• Smart exclude suggestions (size/type heuristics; optional ML assist)
• Backup report summarization (generate HTML/Markdown from logs)
• Error anomaly hints (cluster frequent issues to suggest fixes)
• Configurable overwrite policy (prompt/skip/replace)
• Per‑drive runs orchestration for multi‑drive snapshot sequencing

Call to Action ⭐

• Like it? Star the repo and share with your team.
• Have an idea or found an issue? Open an Issue.
• Want to contribute? PRs welcome — especially for robust exclude handling and improved path composition.

Limitations & Caveats ⚠️

• Windows‑only: Uses WMI and .NET Framework 4.8.
• Elevation: Creating VSS snapshots and writing HKLM requires running in an elevated console.
• Profile assumptions: Include/exclude paths must be absolute. Excludes are exact path matches; wildcard/pattern excludes are not supported.
• Case sensitivity of excludes: Exclude matching is case‑sensitive (as implemented with string.Contains on raw paths). Ensure casing matches your source paths.
• Exclude behavior with snapshots: Excludes are compared to the path portion after the drive designator and applied to snapshot paths accordingly.
• No dry‑run: The tool immediately creates directories and copies files.
• Exit codes: Internal exit codes are computed, but the process entry point (void Main) does not return them to the OS.
• Error handling: Errors are logged; copying continues where possible.
• Logging level: Fixed to Info+ via NLog config; there is no command‑line --verbose toggle implemented (the Verbose field is unused).
• Known quirk: Source file path composition uses Path.Combine(file.DirectoryName, file.FullName) in the copy routines, which may produce invalid paths; errors are logged when this occurs.

Project Structure 📁

• VSSCopy/Init.cs — Program entry; command‑line parsing and dispatch.
• VSSCopy/CLI.cs — Main orchestration, profile loading, VSS toggle, registry changes, copy start/finish.
• VSSCopy/lib/FileIO.cs — Recursive copy implementation with parallel file copying and basic exclude handling.
• VSSCopy/lib/VssWMI.cs — VSS snapshot management via WMI Win32_ShadowCopy; path translation helpers.
• VSSCopy/NLog.config — NLog targets and rules for file and console logging.
• VSSCopy/App.config — .NET Framework 4.8 startup configuration.
• VSSCopy/VSSCopy.csproj — Project settings, references, Fody/Costura setup.
• VSSCopy.sln — Solution file.

License 📜

Licensed under the GNU Affero General Public License v3. See LICENSE.