Laurence Horrocks-Barlow 74b210a702 Add README, runbook, per-script docs, CHANGELOG and LICENSE.

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.

2026-05-21 10:33:10 +01:00

3.3 KiB

Raw Permalink Blame History

Directory layout

A description of the on-disk shape these scripts work with — both the local working copy and what ends up on the Ventoy USB.

Local working copy

ventoy-extras/                       # this repo
├─ organise-isos.ps1
├─ generate-ventoy-json.ps1
├─ ventoy.json                       # generated, gitignored — your menu
├─ iso-library/                      # generated, gitignored — your ISOs
│  ├─ ubuntu/
│  │  └─ 24.04/
│  │     └─ x86_64/
│  │        └─ ubuntu-24.04.1-desktop-amd64.iso
│  ├─ debian/
│  │  └─ 12/
│  │     └─ x86_64/
│  │        └─ debian-12.5.0-amd64-netinst.iso
│  ├─ rocky/
│  │  └─ 9.3/
│  │     ├─ x86_64/
│  │     │  └─ Rocky-9.3-x86_64-minimal.iso
│  │     └─ aarch64/
│  │        └─ Rocky-9.3-aarch64-minimal.iso
│  ├─ proxmox-ve/
│  │  └─ 8.2/
│  │     └─ noarch/
│  │        └─ proxmox-ve_8.2-1.iso
│  └─ ...
└─ docs/

You can keep iso-library/ and ventoy.json anywhere — pass -IsoRoot and -OutFile to point at them. Keeping them outside the repo is the sensible default for non-trivial ISO collections.

On the Ventoy USB

E:\                                  # Ventoy data partition root
├─ ventoy\
│  ├─ ventoy.json                    # copied from the generated file
│  ├─ theme\                         # optional, not managed by these scripts
│  └─ ...                            # other Ventoy config
├─ iso-library\
│  ├─ ubuntu\
│  │  └─ 24.04\
│  │     └─ x86_64\
│  │        └─ ubuntu-24.04.1-desktop-amd64.iso
│  └─ ...
└─ (anything else you want on the stick)

Ventoy treats the data partition as a regular FAT/exFAT/NTFS filesystem. The bootloader lives on a separate hidden ESP partition that these scripts do not touch.

Why three levels (`os/version/arch`)

os/ — keeps the same OS together regardless of version churn. Easier to clean up when retiring an EOL distro.
version/ — lets you have multiple versions of the same OS without filename collisions, and gives Ventoy a clean per-version label.
arch/ — multi-arch ISOs (typically x86_64 + aarch64 for RHEL family, Debian, Ubuntu) sort cleanly side by side.

When arch isn't applicable (hypervisor appliances, BSD distros that ship multi-arch in one image), the slot becomes noarch\ and the generator omits the [<arch>] suffix from menu labels.

Path constraints

Forward vs backslash: the local Windows paths use \. ventoy.json paths use / (Ventoy is essentially Linux-bootstrapped and expects POSIX paths). The generator handles the translation.
Leading slash: ventoy.json paths start with / and are rooted at the Ventoy data partition root, not the filesystem root.
Long paths: deeply-nested distros (opensuse-tumbleweed/...) plus long ISO filenames can exceed 260 chars on Windows. PowerShell 7+ handles this transparently; on 5.1 you may need \\?\ prefixes if you hit it. Robocopy handles long paths regardless of PS version.

Gitignore recommendation

A .gitignore for this repo (not yet committed):

iso-library/
ventoy.json
*.iso

ISOs are large and frequently rotated. Don't commit them.

3.3 KiB Raw Permalink Blame History