# 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.