# `organise-isos.ps1`

Parses ISO filenames, infers `os`, `version`, and `arch`, and moves each file
into `<DestDir>\<os>\<version>\<arch>\`. Pure filename parsing — the ISO
itself is never opened.

## Parameters

| Parameter | Default | Description |
| --- | --- | --- |
| `-SourceDir` | `.` | Directory to scan for `*.iso` files (non-recursive). |
| `-DestDir` | `.\iso-library` | Target root. Subdirectories are created as needed. |
| `-DryRun` | `false` | Print the moves it would make; touch nothing. |

## What it does

1. Enumerates `*.iso` directly under `-SourceDir` (does not recurse).
2. For each file, calls `Get-IsoMeta` to derive `os`, `version`, `arch`.
3. Creates `<DestDir>\<os>\<version>\<arch>\` if missing.
4. Moves the ISO in.
5. Prints a table of the results.

## Parsing rules

### Architecture

Checked in priority order against the **raw** filename. First match wins:

| Pattern | Canonical |
| --- | --- |
| `aarch64`, `arm64` | `aarch64` |
| `arm` (not followed by `64`) | `arm` |
| `x86[_-]64`, `amd64`, `_x64`, `64bit` | `x86_64` |
| `x86` (not followed by `_64`), `i[3-6]86`, `32bit` | `x86` |
| `riscv64`, `riscv32` | `riscv64` / `riscv32` |
| `ppc64le`, `ppc64`, `ppc` | matching |
| `s390x`, `mips64`, `mips`, `loong64`, `ia64`, `sparc64`, `alpha` | matching |

If nothing matches, arch is `noarch`.

### Edition noise stripping

Tokens like `live`, `server`, `desktop`, `dvd`, `netinstall`, `workstation`,
`kde`, `gnome`, `xfce`, language codes (`en_us`, `en_gb`, `international`),
release tags (`lts`, `beta`, `rc1`, `sp2`, `u3`), and similar are stripped
**after** the arch check so they don't pollute the OS-name match. See the
`$noisePattern` regex in the script for the full list.

### OS detection

The cleaned filename is split on `-_.` and the first token (lowercased) is
matched against `$osNormMap`. First regex match wins. If no first-token match
hits, the first **two** tokens joined with `-` are tried (catches `linux-mint`,
`pop-os`, `ms-dos`).

If still no match, the first token is sanitised (`[^a-z0-9-]` removed) and
used as-is, producing a slug like `myweirdspin`.

The map covers Windows, RHEL family, Fedora family, SUSE, Debian/Ubuntu and
derivatives, Arch family, Gentoo family, Slackware, independent Linux (Void,
NixOS, Alpine, etc.), hypervisors (Proxmox, ESXi, XCP-ng), BSD family,
Solaris/illumos, exotic OSes (Haiku, FreeDOS, ReactOS, Plan9), and rescue
tools (Clonezilla, SystemRescue, GParted, Memtest, Hiren's, DBAN, vendor
rescue disks). Full list is in `$osNormMap` in
[`organise-isos.ps1`](../organise-isos.ps1).

### Version detection

Checked in this order, first match wins:

1. **Windows H-series** — `25H2`, `24H2`, etc. on the raw filename.
2. **Full date stamp** — `YYYYMMDD` → year only (so `20240315` → `2024`).
3. **Semver / partial semver** — `\d+\.\d+(\.\d+)?` on the cleaned name.
   Three-part versions are truncated to `major.minor` (so `9.3.1` → `9.3`).
4. **Bare integer** — final fallback, captures things like `debian-12-...`.

If nothing matches, version is `unknown`.

## Examples

| Input filename | OS | Version | Arch |
| --- | --- | --- | --- |
| `ubuntu-24.04.1-desktop-amd64.iso` | `ubuntu` | `24.04` | `x86_64` |
| `Win11_24H2_English_x64.iso` | `windows` | `24H2` | `x86_64` |
| `debian-12.5.0-amd64-netinst.iso` | `debian` | `12.5` | `x86_64` |
| `Rocky-9.3-aarch64-minimal.iso` | `rocky` | `9.3` | `aarch64` |
| `archlinux-2024.03.01-x86_64.iso` | `arch` | `2024.03` | `x86_64` |
| `clonezilla-live-3.1.2-22-amd64.iso` | `clonezilla` | `3.1` | `x86_64` |
| `proxmox-ve_8.2-1.iso` | `proxmox-ve` | `8.2` | `noarch` |
| `systemrescue-11.00-amd64.iso` | `systemrescue` | `11` | `x86_64` |

## Adding support for a new OS

Edit [`organise-isos.ps1`](../organise-isos.ps1):

```powershell
$osNormMap = [ordered]@{
    # ...existing entries...
    '^mycoolos|^my.cool.os' = 'mycoolos'
}
```

Then add a display name and category in
[`generate-ventoy-json.ps1`](../generate-ventoy-json.ps1):

```powershell
$displayNames = @{
    'mycoolos' = 'My Cool OS'
}

$categoryMap = [ordered]@{
    'mycoolos' = 'Independent Linux'   # or any existing/new category
}
```

The `$osNormMap` is **ordered** — earlier patterns win, so put more specific
patterns above more general ones (e.g. `^centos.stream` must come before
`^centos`).

## Exit codes

- `0` — success (including dry-run).
- `1` — no ISO files found in `-SourceDir`.

## Idempotency and re-runs

Safe to re-run. The first time moves all ISOs out of `-SourceDir`; subsequent
runs find nothing to move (because the source directory is empty) and exit
with code 1. If you want to add ISOs later, drop them into the same source
directory and run again.

The script does **not** detect duplicates. If you move the same ISO twice
from different sources and they parse to the same target slot, the second
move fails with a `Move-Item` error — by design, since silently
overwriting an ISO would be a footgun.