From ef93dac13f5d740bf3744a43f6fed5c90b9090d9 Mon Sep 17 00:00:00 2001 From: Christian Emmer <10749361+emmercm@users.noreply.github.com> Date: Wed, 31 Jan 2024 17:20:11 -0800 Subject: [PATCH] Docs: output path options (#904) --- docs/output/path-options.md | 487 +++++++++++++++++++++++++ docs/output/tokens.md | 21 +- docs/usage/handheld/minui.md | 2 +- docs/usage/hardware/analogue-pocket.md | 8 +- docs/usage/hardware/everdrive.md | 2 +- docs/usage/hardware/ezflash.md | 2 +- docs/usage/personal.md | 2 +- mkdocs.yml | 3 +- 8 files changed, 515 insertions(+), 12 deletions(-) create mode 100644 docs/output/path-options.md diff --git a/docs/output/path-options.md b/docs/output/path-options.md new file mode 100644 index 000000000..f274c4801 --- /dev/null +++ b/docs/output/path-options.md @@ -0,0 +1,487 @@ +# Output Path Options + +`igir` offer many options to control how ROMs are sorted in the specified output directory. + +All `--dir-*` options append subdirectories to whatever is specified in the `--output ` option. Many `--dir-*` options have an [output path token](./tokens.md) equivalent, which also controls how ROMs are sorted. + +Multiple options can be combined, and they will be appended to the output directory in the following order: + +## Mirror the input subdirectory + +```text +--dir-mirror +``` + +This option mirrors the subdirectory structure of where ROMs were found in the input directory. + +For example, if this is the input directory structure: + +```text +ROMs-Input/ +└── gb + ├── mario + │ ├── mario land 2.gb + │ └── mario land.gb + └── pokemon + ├── pokemon blue.gb + ├── pokemon red.gb + └── pokemon yellow.gb +``` + +When combined with a [DAT](../dats/overview.md), the ROMs will be written with a standardized name, but the output subdirectory structure will match the input: + +=== ":simple-windowsxp: Windows" + + ```batch + igir copy ^ + --dat "No-Intro*.zip" ^ + --input "ROMs-Input" ^ + --output "ROMs-Output" ^ + --dir-mirror + ``` + +=== ":simple-apple: macOS" + + ```shell + igir copy \ + --dat "No-Intro*.zip" \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-mirror + ``` + +=== ":simple-linux: Linux" + + ```shell + igir copy \ + --dat "No-Intro*.zip" \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-mirror + ``` + +```text +ROMs-Output/ +└── gb + ├── mario + │ ├── Super Mario Land (World) (Rev 1).gb + │ └── Super Mario Land 2 - 6 Golden Coins (USA, Europe) (Rev 2).gb + └── pokemon + ├── Pokemon - Blue Version (USA, Europe) (SGB Enhanced).gb + ├── Pokemon - Red Version (USA, Europe) (SGB Enhanced).gb + └── Pokemon - Yellow Version - Special Pikachu Edition (USA, Europe) (CGB+SGB Enhanced).gb +``` + +!!! tip + + This option is best used to preserve some sort of manual sorting, otherwise you will probably want to combine some of the below options instead. + +## Append DAT name + +```text +--dir-dat-name +``` + +This option appends the matching [DAT](../dats/overview.md)'s name (not its filename) to each file, causing ROMs to be grouped by their console. + +For example, here are some ROMs from multiple consoles combined in one input directory: + +```text +ROMs-Input/ +├── Pokemon - Blue Version (USA, Europe) (SGB Enhanced).gb +├── Pokemon - Crystal Version (USA, Europe) (Rev 1).gbc +├── Pokemon - Emerald Version (USA, Europe).gba +├── Pokemon - Gold Version (USA, Europe) (SGB Enhanced) (GB Compatible).gbc +├── Pokemon - Red Version (USA, Europe) (SGB Enhanced).gb +├── Pokemon - Ruby Version (USA, Europe) (Rev 2).gba +├── Pokemon - Sapphire Version (USA, Europe) (Rev 2).gba +├── Pokemon - Silver Version (USA, Europe) (SGB Enhanced) (GB Compatible).gbc +└── Pokemon - Yellow Version - Special Pikachu Edition (USA, Europe) (CGB+SGB Enhanced).gb +``` + +The ROMs will be grouped by their DAT name in the output directory: + +=== ":simple-windowsxp: Windows" + + ```batch + igir copy ^ + --dat "No-Intro*.zip" ^ + --input "ROMs-Input" ^ + --output "ROMs-Output" ^ + --dir-dat-name + ``` + +=== ":simple-apple: macOS" + + ```shell + igir copy \ + --dat "No-Intro*.zip" \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-dat-name + ``` + +=== ":simple-linux: Linux" + + ```shell + igir copy \ + --dat "No-Intro*.zip" \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-dat-name + ``` + +```text +ROMs-Output/ +├── Game Boy +│ ├── Pokemon - Blue Version (USA, Europe) (SGB Enhanced).gb +│ ├── Pokemon - Red Version (USA, Europe) (SGB Enhanced).gb +│ └── Pokemon - Yellow Version - Special Pikachu Edition (USA, Europe) (CGB+SGB Enhanced).gb +├── Game Boy Advance +│ ├── Pokemon - Emerald Version (USA, Europe).gba +│ ├── Pokemon - Ruby Version (USA, Europe) (Rev 2).gba +│ └── Pokemon - Sapphire Version (USA, Europe) (Rev 2).gba +└── Game Boy Color + ├── Pokemon - Crystal Version (USA, Europe) (Rev 1).gbc + ├── Pokemon - Gold Version (USA, Europe) (SGB Enhanced) (GB Compatible).gbc + └── Pokemon - Silver Version (USA, Europe) (SGB Enhanced) (GB Compatible).gbc +``` + +!!! tip + + You will probably want to use this option or `--dir-dat-description` any time you're processing multiple DAT files. + +## Append DAT description + +```text +--dir-dat-description +``` + +Similar to `--dir-dat-name`, this option will append the matching [DAT](../dats/overview.md)'s description to each file. + +=== ":simple-windowsxp: Windows" + + ```batch + igir copy ^ + --dat "No-Intro*.zip" ^ + --input "ROMs-Input" ^ + --output "ROMs-Output" ^ + --dir-dat-description + ``` + +=== ":simple-apple: macOS" + + ```shell + igir copy \ + --dat "No-Intro*.zip" \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-dat-description + ``` + +=== ":simple-linux: Linux" + + ```shell + igir copy \ + --dat "No-Intro*.zip" \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-dat-description + ``` + +!!! note + + Most DAT groups fill out the "description" field with the DAT's "name" plus verbose information such as game count or DAT generation date. Most of the time you will want to prefer using `--dir-dat-name` instead of this option. + +## Append game letter(s) + +```text +--dir-letter +``` + +This option appends one or more letters as a subdirectory. This option is further controlled by the other `--dir-letter-*` options below. + +For devices such as flash carts that are slow to scroll, it can be helpful to limit the number of files in one subdirectory. One way to do that is to group games by their first letter. + +For example, here are some ROMs that have don't all share the same first letter: + +```text +ROMs-Input/ +├── Kirby's Dream Land (USA, Europe).gb +├── Kirby's Dream Land 2 (USA, Europe) (SGB Enhanced).gb +├── Pokemon - Blue Version (USA, Europe) (SGB Enhanced).gb +├── Pokemon - Red Version (USA, Europe) (SGB Enhanced).gb +├── Pokemon - Yellow Version - Special Pikachu Edition (USA, Europe) (CGB+SGB Enhanced).gb +├── Super Mario Land (World) (Rev 1).gb +└── Super Mario Land 2 - 6 Golden Coins (USA, Europe) (Rev 2).gb +``` + +The ROMs will be grouped together by their first letter in the output directory: + +=== ":simple-windowsxp: Windows" + + ```batch + igir copy ^ + --input "ROMs-Input" ^ + --output "ROMs-Output" ^ + --dir-letter + ``` + +=== ":simple-apple: macOS" + + ```shell + igir copy \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-letter + ``` + +=== ":simple-linux: Linux" + + ```shell + igir copy \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-letter + ``` + +```text +ROMs-Output/ +├── K +│ ├── Kirby's Dream Land (USA, Europe).gb +│ └── Kirby's Dream Land 2 (USA, Europe) (SGB Enhanced).gb +├── P +│ ├── Pokemon - Blue Version (USA, Europe) (SGB Enhanced).gb +│ ├── Pokemon - Red Version (USA, Europe) (SGB Enhanced).gb +│ └── Pokemon - Yellow Version - Special Pikachu Edition (USA, Europe) (CGB+SGB Enhanced).gb +└── S + ├── Super Mario Land (World) (Rev 1).gb + └── Super Mario Land 2 - 6 Golden Coins (USA, Europe) (Rev 2).gb +``` + +!!! tip + + You will probably want to use `--dir-dat-name` or `--dir-dat-description` any time you're processing multiple DAT files, otherwise ROMs from different consoles will be mixed into the same letter subdirectories. + +### Change the number of letters + +```text +--dir-letter-count +``` + +This option controls the number of leading letters to use for the `--dir-letter` option, with a default of one letter. + +For example, if we increase the number of letters used for subdirectory names from the above example, then the output would be: + +=== ":simple-windowsxp: Windows" + + ```batch + igir copy ^ + --input "ROMs-Input" ^ + --output "ROMs-Output" ^ + --dir-letter ^ + --dir-letter-count 3 + ``` + +=== ":simple-apple: macOS" + + ```shell + igir copy \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-letter \ + --dir-letter-count 3 + ``` + +=== ":simple-linux: Linux" + + ```shell + igir copy \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-letter \ + --dir-letter-count 3 + ``` + +```text +ROMs-Output/ +├── KIR +│ ├── Kirby's Dream Land (USA, Europe) +│ └── Kirby's Dream Land 2 (USA, Europe) (SGB Enhanced) +├── POK +│ ├── Pokemon - Blue Version (USA, Europe) (SGB Enhanced).gb +│ ├── Pokemon - Red Version (USA, Europe) (SGB Enhanced).gb +│ └── Pokemon - Yellow Version - Special Pikachu Edition (USA, Europe) (CGB+SGB Enhanced).gb +└── SUP + ├── Super Mario Land (World) (Rev 1).gb + └── Super Mario Land 2 - 6 Golden Coins (USA, Europe) (Rev 2).gb +``` + +!!! tip + + This option is best used when combined with `--dir-letter-group` (below), otherwise you may find the subdirectory structure harder to navigate than leaving this option as the default of one letter. + +### Limit the number of games in a subdirectory + +```text +--dir-letter-limit +``` + +This option limits the number of games that can exist in a letter subdirectory, splitting into multiple subdirectories if necessary. + +This helps when navigating on devices that are slow to scroll, such as flash carts. Additionally, some devices may have a limit on the number of files they will display in a folder, so you may be required to split them. + +For example, here are some ROMs that all start with the same first letter: + +```text +ROMs-Input/ +├── Shaq Fu (USA) (SGB Enhanced).gb +├── Space Invaders (USA) (SGB Enhanced).gb +├── Star Wars (USA, Europe) (Rev 1).gb +├── Star Wars - The Empire Strikes Back (USA, Europe).gb +├── Street Fighter II (USA, Europe) (Rev 1) (SGB Enhanced).gb +├── Super Mario Land (World) (Rev 1).gb +└── Super Mario Land 2 - 6 Golden Coins (USA, Europe) (Rev 2).gb +``` + +If we limit the number of files per letter folder, then the output would be: + +=== ":simple-windowsxp: Windows" + + ```batch + igir copy ^ + --input "ROMs-Input" ^ + --output "ROMs-Output" ^ + --dir-letter ^ + --dir-letter-limit 5 + ``` + +=== ":simple-apple: macOS" + + ```shell + igir copy \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-letter \ + --dir-letter-limit 5 + ``` + +=== ":simple-linux: Linux" + + ```shell + igir copy \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-letter \ + --dir-letter-limit 5 + ``` + +```text +ROMs-Output/ +├── S1 +│ ├── Shaq Fu (USA) (SGB Enhanced).gb +│ ├── Space Invaders (USA) (SGB Enhanced).gb +│ ├── Star Wars (USA, Europe) (Rev 1).gb +│ ├── Star Wars - The Empire Strikes Back (USA, Europe).gb +│ └── Street Fighter II (USA, Europe) (Rev 1) (SGB Enhanced).gb +└── S2 + ├── Super Mario Land (World) (Rev 1).gb + └── Super Mario Land 2 - 6 Golden Coins (USA, Europe) (Rev 2).gb +``` + +### Group multiple letters together + +```text +--dir-letter-group +``` + +This option will combine multiple letter subdirectories, creating letter ranges. This requires the `--dir-letter-limit ` option, as that will help determine what the letter ranges should be. + +For example, here are some ROMs that all start with different letters: + +```text +ROMs-Input/ +├── Alleyway (World).gb +├── Battletoads (USA, Europe).gb +├── Centipede (USA) (Majesco).gb +├── Donkey Kong (World) (Rev 1) (SGB Enhanced).gb +├── Earthworm Jim (USA).gb +├── Final Fantasy Adventure (USA).gb +├── Game Boy Wars Turbo (Japan) (SGB Enhanced).gb +├── Harvest Moon GB (USA) (SGB Enhanced).gb +├── James Bond 007 (USA, Europe) (SGB Enhanced).gb +├── Kirby's Dream Land (USA, Europe).gb +├── Legend of Zelda, The - Link's Awakening (USA, Europe) (Rev 2).gb +├── Mario's Picross (USA, Europe) (SGB Enhanced).gb +└── Pocket Bomberman (Europe) (SGB Enhanced).gb +``` + +We can group the games into letter ranges, with a max of 10 games in each subdirectory like this: + +=== ":simple-windowsxp: Windows" + + ```batch + igir copy ^ + --input "ROMs-Input" ^ + --output "ROMs-Output" ^ + --dir-letter ^ + --dir-letter-limit 5 ^ + --dir-letter-group + ``` + +=== ":simple-apple: macOS" + + ```shell + igir copy \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-letter \ + --dir-letter-limit 5 \ + --dir-letter-group + ``` + +=== ":simple-linux: Linux" + + ```shell + igir copy \ + --input "ROMs-Input/" \ + --output "ROMs-Output/" \ + --dir-letter \ + --dir-letter-limit 5 \ + --dir-letter-group + ``` + +```text +ROMs-Output/ +├── A-K +│ ├── Alleyway (World).gb +│ ├── Battletoads (USA, Europe).gb +│ ├── Centipede (USA) (Majesco).gb +│ ├── Donkey Kong (World) (Rev 1) (SGB Enhanced).gb +│ ├── Earthworm Jim (USA).gb +│ ├── Final Fantasy Adventure (USA).gb +│ ├── Game Boy Wars Turbo (Japan) (SGB Enhanced).gb +│ ├── Harvest Moon GB (USA) (SGB Enhanced).gb +│ ├── James Bond 007 (USA, Europe) (SGB Enhanced).gb +│ ├── Kirby's Dream Land (USA, Europe).gb +└── L-P + ├── Legend of Zelda, The - Link's Awakening (USA, Europe) (Rev 2).gb + ├── Mario's Picross (USA, Europe) (SGB Enhanced).gb + └── Pocket Bomberman (Europe) (SGB Enhanced).gb +``` + +You can also combine this option with `--dir-letter-count ` for ranges with more letters. + +!!! tip + + This option is helpful with smaller ROM collections because `--dir-letter` may leave some letter subdirectories with few ROMs in them. + +!!! note + + This is how the [Hardware Target Game Database](https://github.com/frederic-mahe/Hardware-Target-Game-Database) organizes most of their SMDBs, grouping ROMs into subdirectories of ~200 ROMs each. + +## Append the game name + +```text +--dir-game-subdir +``` diff --git a/docs/output/tokens.md b/docs/output/tokens.md index e611f9b4d..1aa55aec6 100644 --- a/docs/output/tokens.md +++ b/docs/output/tokens.md @@ -2,24 +2,35 @@ When specifying a ROM [writing command](../commands.md) you have to specify an `--output ` directory. `igir` has a few replaceable "tokens" that can be referenced in the `--output ` directory value. This can aid in sorting ROMs into a more complicated directory structure. +See [output path tokens](./path-options.md) for other options that will further sort your ROMs into subdirectories. + For example, if you want to group all ROMs based on their region, you would specify: === ":simple-windowsxp: Windows" ```batch - igir copy extract --dat *.dat --input ROMs\ --output "ROMs-Sorted\{gameRegion}\" + igir copy extract ^ + --dat *.dat ^ + --input ROMs\ ^ + --output "ROMs-Sorted\{gameRegion}\" ``` === ":simple-apple: macOS" ```shell - igir copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{gameRegion}/" + igir copy extract \ + --dat *.dat \ + --input ROMs/ \ + --output "ROMs-Sorted/{gameRegion}/" ``` === ":simple-linux: Linux" ```shell - igir copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{gameRegion}/" + igir copy extract \ + --dat *.dat \ + --input ROMs/ \ + --output "ROMs-Sorted/{gameRegion}/" ``` This might result in an output structure such as: @@ -47,8 +58,8 @@ ROMs-Sorted/ When using [DATs](../dats/overview.md), you can make use of console & game information contained in them: -- `{datName}` the matching DAT's name, similar to how the `--dir-dat-name` option works -- `{datDescription}` the matching DAT's description, similar to how the `--dir-dat-description` option works +- `{datName}` the matching DAT's name, similar to how the [`--dir-dat-name` option](./path-options.md) works +- `{datDescription}` the matching DAT's description, similar to how the [`--dir-dat-description` option](./path-options.md) works - `{gameRegion}` each of the ROM's region(s) (e.g. `USA`, `EUR`, `JPN`, `WORLD`) - `{gameLanguage}` each of the ROM's language(s) (e.g. `EN`, `ES`, `JA`) diff --git a/docs/usage/handheld/minui.md b/docs/usage/handheld/minui.md index 1b8ee3370..8145cd75b 100644 --- a/docs/usage/handheld/minui.md +++ b/docs/usage/handheld/minui.md @@ -29,7 +29,7 @@ MinUI supports many many systems and ROM formats. Check the folders [here (base) MinUI uses the names unter /Roms on the SD card in a more creative way than most other frontends. The folder names consist of a *UI name* and a *PAK name*. The *UI name* is used as the name shown in the User interface as a list item name, while the *PAK name* controls which software pack is used to open the files within. Files with the same *UI name* but different *PAK name* are listed in the same list in the UI but are opened with different PAKs. `igir` uses the vendor recommendations for the folder names with some exceptions. -MinUI requires multi-file releases to be grouped into subfolders (bin/cue releases of the PS1 for example). It is recommended to use `--dir-game-subdir=multiple` - which is the default at this time. +MinUI requires multi-file releases to be grouped into subdirectories (bin/cue releases of the PS1 for example). It is recommended to use the [`--dir-game-subdir multiple` option](../../output/path-options.md), which is the default at this time. More details about these features can be found [here](https://github.com/shauninman/MinUI/tree/main/skeleton/BASE) under the sections `Roms` and `Disc-based games`. diff --git a/docs/usage/hardware/analogue-pocket.md b/docs/usage/hardware/analogue-pocket.md index 86aa28731..ffad425f6 100644 --- a/docs/usage/hardware/analogue-pocket.md +++ b/docs/usage/hardware/analogue-pocket.md @@ -68,11 +68,15 @@ This token can be used to reference each core's specific directory in the SD car !!! note - The `--clean-exclude ` option in the above examples is so we don't accidentally "clean" (delete) the BIOS files for each core. + The `--dat-name-regex-exclude "/headerless/i"` option in the above examples is to exclude any "headered" No-Intro DATs. Some consoles such as NES have separate "headered" and "headerless" DATs, and they have duplicated ROM filenames, so we want to avoid writing different input files to the same output location. !!! note - The `--dat-name-regex-exclude "/headerless/i"` option in the above examples is to exclude any "headered" No-Intro DATs. Some consoles such as NES have separate "headered" and "headerless" DATs, and they have duplicated ROM filenames, so we want to avoid writing different input files to the same output location. + The `--dir-letter-limit 1000` option in the above example is because some cores won't read more than a certain number of files in one directory. See [output path options](../../output/path-options.md) for other options available. + +!!! note + + The `--clean-exclude ` option in the above examples is so we don't accidentally "clean" (delete) the BIOS files for each core. Your SD card should look like this, likely with more cores: diff --git a/docs/usage/hardware/everdrive.md b/docs/usage/hardware/everdrive.md index 03f50fa34..0f3b7b692 100644 --- a/docs/usage/hardware/everdrive.md +++ b/docs/usage/hardware/everdrive.md @@ -42,7 +42,7 @@ Because flash carts are specific to a specific console, you can provide specific --no-bios ``` -you can then add some other output options such as `--dir-letter`, if desired. +you can then add some other output options such as the [`--dir-letter` option](../../output/path-options.md), if desired. Alternatively, `igir` supports [Hardware Target Game Database SMDB files](https://github.com/frederic-mahe/Hardware-Target-Game-Database/tree/master/EverDrive%20Pack%20SMDBs) as [DATs](../../dats/overview.md). Unlike typical DATs, Hardware Target Game Database SMDBs typically have an opinionated directory structure to help sort ROMs by language, category, genre, and more. Example usage: diff --git a/docs/usage/hardware/ezflash.md b/docs/usage/hardware/ezflash.md index 51afc7141..e8c71ea70 100644 --- a/docs/usage/hardware/ezflash.md +++ b/docs/usage/hardware/ezflash.md @@ -42,7 +42,7 @@ Because flash carts are specific to a specific console, you can provide specific --no-bios ``` -you can then add some other output options such as `--dir-letter`, if desired. +you can then add some other output options such as the [`--dir-letter` option](../../output/path-options.md), if desired. !!! warning diff --git a/docs/usage/personal.md b/docs/usage/personal.md index 6dbc376d8..9e538a5d6 100644 --- a/docs/usage/personal.md +++ b/docs/usage/personal.md @@ -38,7 +38,7 @@ The file tree in that hard drive looks like this: └── igir_library_sync.sh ``` -The root directory has a DAT zip and subdirectory for each [DAT](../dats/overview.md) release group. This helps separate differing quality of DATs and different DAT group ROM naming schemes. I then have one subdirectory for each game console, using the `--dir-dat-name` option. +The root directory has a DAT zip and subdirectory for each [DAT](../dats/overview.md) release group. This helps separate differing quality of DATs and different DAT group ROM naming schemes. I then have one subdirectory for each game console, using the [`--dir-dat-name` option](../output/path-options.md). The `igir_library_sync.sh` script helps me keep this collection organized and merge new ROMs into it. The complete source is: diff --git a/mkdocs.yml b/mkdocs.yml index 3350a2d82..b0376437e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -89,8 +89,9 @@ nav: - roms/headers.md - roms/patching.md - File Outputs: - - output/writing-archives.md + - output/path-options.md - output/tokens.md + - output/writing-archives.md - output/reporting.md - output/cleaning.md - Advanced: