Laurence Horrocks-Barlow
74b210a702
Documents the organise-isos and generate-ventoy-json workflow end-to-end: quick start in the README, full procedure with troubleshooting and recovery in docs/RUNBOOK.md, and reference docs for each script covering parameters, parsing rules, category groupings, and extensibility. Ships a YOLO licence (no warranty) and seeds CHANGELOG.md for the v0.1.0 release.
135 lines
4.9 KiB
Markdown
135 lines
4.9 KiB
Markdown
# `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.
|