================================================================================
  Wit - Version Control System for Windows
  Developer: ExEintel
  Version: 1.0
================================================================================

1. OVERVIEW
--------------------------------------------------------------------------------
  Wit is a lightweight version control system for Windows, written entirely in
  Batch script. It provides Git-like functionality using native Windows tools
  such as tar.exe (built-in on Windows 10+) and PowerShell.

  Wit allows you to:
    - Initialize projects and track changes
    - Create and manage version archives
    - Create and manage release archives (ZIP)
    - Compare versions, rollback changes, export snapshots
    - Tag versions with meaningful labels
    - Create full backups
    - Verify project integrity


2. SYSTEM REQUIREMENTS
--------------------------------------------------------------------------------
  - Operating System: Windows 7 or later (Windows 10+ recommended)
  - tar.exe (included in Windows 10 build 17063+)
  - PowerShell 3.0+ (for fallback compression and ZIP support)
  - Administrator rights (only required for system-wide installation)


3. INSTALLATION
--------------------------------------------------------------------------------
  Option A: Manual (Add to PATH manually)
    1. Copy the Wit folder to a permanent location (e.g., C:\Tools\Wit)
    2. Add the Wit folder path to your system PATH environment variable
    3. Restart your terminal

  Option B: Automatic Installer
    1. Open a command prompt as Administrator
    2. Navigate to the Wit folder
    3. Run: .\data\install_patch.cmd
    4. Follow the on-screen instructions
    5. Restart your terminal

  After installation, you can use 'Wit' from any directory.


4. PROJECT STRUCTURE
--------------------------------------------------------------------------------
  Wit/
  ├── wit.cmd                  Main entry point (user interface)
  ├── logo.png                 Application icon
  ├── Readme.txt               This documentation
  ├── data/
  │   ├── Witshell.cmd         Command parser and dispatcher
  │   ├── Wit_servers.cmd      Core business logic (version control engine)
  │   └── install_patch.cmd    PATH installer script
  └── .Wit/
      ├── versions/            Version archives storage (.tar.gz)
      └── release/             Release archives storage (.zip)


5. INTERNAL DATA FORMATS
--------------------------------------------------------------------------------

  5.1. .witconfig (Project Configuration)
    File located in the project root directory.
    Format: KEY=VALUE (one per line)
    Example:
      project=MyProject
      path=C:\Users\Me\Projects\MyProject
      created=Mon 05/11/2026 12:30:00.45

  5.2. projects.txt (Central Registry)
    File located at %USERPROFILE%\.wit\projects.txt
    Format: Name|Path|Created
    Example:
      MyProject|C:\Projects\MyProject|Mon 05/11/2026 12:30:00.45

  5.3. versions\metadata.txt (Version Metadata)
    File located at .Wit\versions\metadata.txt
    Format: VersionName|Date|Tag|Comment
    Example:
      v1|Mon 05/11/2026 12:30:00.45|stable|Initial release
      v2|Mon 05/11/2026 14:00:00.12||Bug fixes

  5.4. release\metadata.txt (Release Metadata)
    File located at .Wit\release\metadata.txt
    Format: ReleaseName|Date
    Example:
      v1.0|Mon 05/11/2026 12:30:00.45


6. COMMAND REFERENCE
--------------------------------------------------------------------------------

  6.1. INITIALIZATION

    Wit init
      Initializes the current directory as a Wit project.
      Creates .witconfig and .Wit\ directory structure.
      Automatically creates version "v1".

    Wit list
      Displays all Wit-tracked projects from the central registry.

    Wit info "project_name"
      Shows detailed information about a project:
      - Path, version count, release count, latest version, creation date

    Wit rename "old_name" "new_name"
      Renames a project in the central registry and updates .witconfig.

  6.2. VERSION CONTROL (vr)

    Wit vr list "project_name"
      Lists all versions of a project with dates, tags, and comments.

    Wit vr diff "version1" "version2" ["project_name"]
      Compares two versions and displays added, removed files.
      Third argument (project name) is optional; uses first project if omitted.

    Wit vr rollback "project_name" "version"
      Reverts the project to a specified version.
      Automatically saves the current state before rolling back.

    Wit vr export "version" "export_path" ["project_name"]
      Extracts a version archive to a specified folder (without compression).

    Wit vr comment "version" "text" ["project_name"]
      Adds a descriptive comment to a version's metadata.

  6.3. RELEASES (rl)

    Wit rl list "project_name"
      Lists all releases for a project.

    Wit rl extract "release_name" "extract_path"
      Extracts a release archive (ZIP) to a specified folder.

    Wit rl rm "project_name" "release_name"
      Deletes a release archive and its metadata entry.

    Wit rl latest "project_name"
      Displays the most recently created release.

  6.4. HISTORY AND LOGGING

    Wit log "project_name"
      Shows the complete project history including versions, releases,
      tags, comments, and creation dates.

    Wit history "version_name"
      Searches all projects for a specific version and displays
      its project, path, date, and tag information.

  6.5. UTILITIES

    Wit clean "project_name"
      Removes all version archives except the latest one.
      Updates metadata accordingly. Cannot be undone.

    Wit backup "project_name"
      Creates a compressed backup archive (.tar.gz) of the entire
      .Wit directory, including all versions and releases.

    Wit verify "project_name"
      Checks project integrity:
      - Verifies .witconfig and .Wit directory structure
      - Confirms all version and release archives exist
      - Reports any missing files or inconsistencies

    Wit status "project_name"
      Compares the current project files against the latest version.
      Displays new and deleted files (Git status analog).

    Wit tag "version" "tag_name"
      Assigns a human-readable tag (e.g., "stable", "beta") to a version.

    Wit find "tag_name"
      Searches all projects for versions with the specified tag.


7. EXAMPLES
--------------------------------------------------------------------------------

    --- Initialize a new project ---
    C:\MyProject> Wit init
    C:\MyProject> Wit init MyCustomName

    --- Work with versions ---
    Wit vr list "MyProject"
    Wit vr diff "v1" "v2"
    Wit vr rollback "MyProject" "v1"
    Wit vr export "v1" "C:\Backup\snapshot"
    Wit vr comment "v1" "Initial working version"

    --- Manage releases ---
    Wit rl list "MyProject"
    Wit rl extract "v1.0" "C:\Deploy"
    Wit rl rm "MyProject" "v1.0"
    Wit rl latest "MyProject"

    --- Tag and find ---
    Wit tag "v2.0" "stable"
    Wit tag "v1.0" "beta"
    Wit find "stable"

    --- Maintenance ---
    Wit status "MyProject"
    Wit verify "MyProject"
    Wit backup "MyProject"
    Wit clean "MyProject"
    Wit log "MyProject"
    Wit history "v1"


8. ARCHITECTURE
--------------------------------------------------------------------------------

  wit.cmd
    Entry point. Validates the environment and delegates to data\Witshell.cmd.
    Passes all command-line arguments to the dispatcher.

  data\Witshell.cmd
    Command parser. Reads the first argument to determine the command,
    handles sub-commands (vr, rl), sets environment paths, and calls
    the appropriate function in Wit_servers.cmd.

  data\Wit_servers.cmd
    Core engine. Contains all business logic:
    - Project management (init, list, info, rename)
    - Version management (create, list, diff, rollback, export, comment)
    - Release management (list, extract, remove, latest)
    - Utilities (clean, backup, verify, status, tag, find)
    - Archive operations (tar.gz, zip creation/extraction)
    - Registry management (project registration, lookup)

  Storage locations:
    - Central registry: %USERPROFILE%\.wit\projects.txt
    - Local project data: .Wit\versions\ and .Wit\release\


9. TROUBLESHOOTING
--------------------------------------------------------------------------------

  "Command not recognized"
    Ensure the Wit directory is in your PATH. Run install_patch.cmd
    or add the path manually. Restart your terminal.

  "tar.exe not found"
    Wit requires Windows 10 build 17063+ for native tar support.
    On older systems, the PowerShell fallback will handle compression.

  "Access denied"
    Run your terminal as Administrator for system-wide installation.

  "Project not found"
    Use 'Wit list' to see all registered projects.
    Check that .witconfig exists in the project directory.

  "Version not found"
    Use 'Wit vr list "project"' to see available versions.
    Version names are case-sensitive in the metadata file.

  "Error creating archive"
    Check disk space and file permissions.
    Ensure no files in the project are locked by other processes.


10. CHANGELOG
--------------------------------------------------------------------------------
  v1.0 (2026-05-11)
    - Initial release
    - Core version control functionality
    - 22+ commands implemented
    - Project registry and metadata management
    - Built-in compression using tar.exe and PowerShell
    - Central project registry at %USERPROFILE%\.wit\