Merge branch 'main' into emmercm/1.6.5

emmercm · Jun 23, 2023 · 75e0ed2 · 75e0ed2
2 parents 4032fab + 90cc2be
commit 75e0ed2
Show file tree

Hide file tree

Showing 13 changed files with 359 additions and 46 deletions.
diff --git a/docs/commands.md b/docs/commands.md
@@ -0,0 +1,74 @@
+# Commands
+
+`igir` takes actions based on commands you specify. Each command has a clear input and output, and `igir` will never take surprise actions you did not specify. Multiple commands can (and will likely) be specified at once.
+
+!!! tip
+
+    See the `igir --help` message for the list of all commands and options, as well as some examples.
+
+## ROM writing
+
+`igir` has three writing commands. Only one writing command can be specified at a time, and all require the `--output` option.
+
+### `copy`
+
+Copy ROMs from an input directory to the output directory.
+
+Files in the input directories will be left alone, they will _not_ be modified or deleted.
+
+### `move`
+
+Move ROMs from an input directory to the output directory. The same directory can be specified for both input & output, resulting in ROMs being renamed as their names change in [DATs](dats.md).
+
+ROMs will be deleted from their input directory after _all_ ROMs for _every_ [DAT](dats.md) have been written.
+
+### `symlink`
+
+Create a symbolic link in the output directory to a ROM in the input directory.
+
+By default, absolute file paths will be used. You can specify the `--symlink-relative` option to use relative file paths.
+
+## ROM archiving
+
+`igir` has two ROM archive commands. Archive commands require either the `copy` or `move` write command. Only one archive command can be specified at a time.
+
+If no archive command is specified, files will be left as-is. If they are already extracted, then they will stay extracted. If they are already archived (including non-`.zip` archives), then they will stay archived.
+
+!!! note
+
+    See the [archives page](archives.md) for more information on supported archive types.
+
+### `extract`
+
+ROMs will be extracted from archives as they are being copied or moved. ROMs from the same game will be placed into a subdirectory together.
+
+Input ROMs that are _not_ archived will be copied as-is.
+
+### `zip`
+
+ROMs will be archived into a `.zip` file as they are being copied or moved. ROMs from the same game will be put into the same `.zip` file.
+
+ROMs that are already in an archive will be re-archived.
+
+## ROM verification
+
+### `test`
+
+After performing one of the ROM writing commands, verify that the file was written correctly.
+
+- `extract test` tests that each ROM file written has the correct size & checksum
+- `zip test` tests that the `.zip` file has all the correct archive entry sizes & checksums, and contains no excess entries
+
+## File manipulation
+
+### `clean`
+
+Files in the output directory that do not match any ROM in any [DAT](dats.md) will be deleted.
+
+## ROM reporting
+
+### `report`
+
+A report will be generated of what input files were matched by what DAT, and what games in what [DATs](dats.md) have missing ROMs.
+
+See the [reporting page](output/reporting.md) for more information.
diff --git a/docs/installation.md b/docs/installation.md
@@ -21,6 +21,14 @@ npx igir@latest copy extract --dat *.dat --input ROMs/ --output ROMs-Sorted/ --d
 
 [![asciicast](https://asciinema.org/a/hjMOlN3DwSgo9NGHzPtncOoq9.svg)](https://asciinema.org/a/hjMOlN3DwSgo9NGHzPtncOoq9)
 
+!!! tip
+
+    You can alias the `npx` command in your macOS or Linux [dotfiles](https://missing.csail.mit.edu/2019/dotfiles/) like this:
+
+    ```bash
+    alias igir="npx igir@latest"
+    ```
+
 ## Via downloaded executable
 
 [![GitHub: release](https://img.shields.io/github/v/release/emmercm/igir?color=%236e5494&logo=github&logoColor=white)](https://github.com/emmercm/igir/releases/latest)

diff --git a/docs/reporting.md → docs/output/reporting.md b/docs/reporting.md → docs/output/reporting.md
@@ -9,9 +9,9 @@ When using DATs (the `--dat` option), the `igir report` command can report on:
 - What input files didn't match to any ROM
 - What output files were cleaned (`igir clean` command)
 
-At least one DAT is required for the `igir report` command to work, otherwise `igir` has no way to understand what input files are known ROMs and which aren't. See the [DAT docs](dats.md) for more information about DATs.
+At least one DAT is required for the `igir report` command to work, otherwise `igir` has no way to understand what input files are known ROMs and which aren't. See the [DAT docs](../dats.md) for more information about DATs.
 
-The `igir report` can be specified on its own without any writing command in order to report on an existing collection, e.g.:
+The `igir report` can be specified on its own without any [writing command](../commands.md) in order to report on an existing collection, e.g.:
 
 ```shell
 $ igir report --dat *.dat --input ROMs/

diff --git a/docs/output/tokens.md b/docs/output/tokens.md
@@ -0,0 +1,67 @@
+# Output Tokens
+
+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.
+
+For example, if you want to group all ROMs based on their region, you would specify:
+
+=== "Windows"
+
+    ```batch
+    igir.exe copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{datReleaseRegion}/"
+    ```
+
+=== "macOS"
+
+    ```shell
+    igir copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{datReleaseRegion}/"
+    ```
+
+This might result in an output structure such as:
+
+```text
+ROMs-Sorted/
+├── AUS
+│   └── Pokemon Pinball (USA, Australia) (Rumble Version) (SGB Enhanced) (GB Compatible).gbc
+├── EUR
+│   ├── 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
+└── USA
+    ├── 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
+    └── Pokemon Pinball (USA, Australia) (Rumble Version) (SGB Enhanced) (GB Compatible).gbc
+```
+
+!!! note
+
+    Tokens can resolve to multiple values for each ROM. For example, a ROM may have multiple regions or languages. This will result in the same ROM being written to multiple locations.
+
+## DAT information
+
+When using [DATs](../dats.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
+- `{datReleaseLanguage}` each of the ROM's language(s) (e.g. `EN`, `ES`, `JA`)
+- `{datReleaseRegion}` each of the ROM's region(s) (e.g. `USA`, `EUR`, `JPN`, `WORLD`)
+
+## File information
+
+You can use some information about the input and output file's name & location:
+
+- `{inputDirname}` the input file's dirname (full path minus file basename)
+- `{outputBasename}` the output file's basename, equivalent to `{outputName}.{outputExt}`
+- `{outputName}` the output file's filename without its extension
+- `{outputExt}` the output file's extension
+
+## Specific hardware
+
+To help sort ROMs into unique file structures for popular frontends & hardware, `igir` offers a few specific tokens:
+
+- `{pocket}` the [Analogue Pocket](../usage/hardware/analogue-pocket.md) core's directory for the ROM
+- `{mister}` the [MiSTer FPGA](../usage/hardware/mister.md) core's directory for the ROM
+- `{onion}` the [OnionOS / GarlicOS](../usage/handheld/onionos.md) emulator's directory for the ROM
+
+!!! tip
+
+    See the `igir --help` message for the list of all replaceable tokens.
diff --git a/docs/usage/collection-sorting.md b/docs/usage/collection-sorting.md
@@ -55,7 +55,7 @@ ROMs-Sorted
 
 Let's say that we've done the above first time sort and were happy with the results. We can now consider the `ROMs-Sorted/` directory to be our primary collection, every file in there has been matched to a DAT.
 
-Now we have new ROMs that we want to merge into our collection, and we want to generate a [report](../reporting.md) of what ROMs are still missing. We also want to delete any unknown files that may have made their way into our collection.
+Now we have new ROMs that we want to merge into our collection, and we want to generate a [report](../output/reporting.md) of what ROMs are still missing. We also want to delete any unknown files that may have made their way into our collection.
 
 === "Windows"
 

diff --git a/docs/usage/desktop/retroarch.md b/docs/usage/desktop/retroarch.md
@@ -1,18 +1,16 @@
 # RetroArch
 
-!!! info
-
-    [RetroArch](https://www.retroarch.com/) is a frontend UI for the [Libretro API](https://www.libretro.com/).
+[RetroArch](https://www.retroarch.com/) is a frontend UI for the [Libretro API](https://www.libretro.com/).
 
 !!! note
 
     RetroArch is available for a number of devices, including smartphones and consoles. These instructions will only work on desktop OSes, but once your files are organized you can copy them over to your other device.
 
-<!--include-markdown-start-->
+## BIOS
 
 First, RetroArch needs a number of [BIOS files](https://docs.libretro.com/library/bios/). Thankfully, the libretro team maintains a DAT of these "system" files, so we don't have to guess at the correct filenames.
 
-With `igir`'s support for [DAT URLs](../../dats.md) we don't even have to download the DAT! Locate your "System/BIOS" directory as configured in RetroArch and use it as your output directory:
+With `igir`'s support for [DAT URLs](../../dats.md) we don't even have to download the DAT! Locate your "System/BIOS" directory as configured in the RetroArch UI and use it as your output directory:
 
 === "Windows (64-bit)"
 
@@ -45,47 +43,47 @@ With `igir`'s support for [DAT URLs](../../dats.md) we don't even have to downlo
       --output ~/Documents/RetroArch/system/
     ```
 
-RetroArch is less opinionated about where your ROMs can live, you have to specify "content" directories during setup.
+## ROMs
 
-!!! note
+RetroArch is less opinionated about where your ROMs can live, you have to specify "content" directories during setup in the RetroArch UI.
 
-    If you want store your ROMs in the RetroArch folder, you could co-locate them near your BIOS files:
+If you want to store your ROMs in the RetroArch folder, you could co-locate them near your BIOS files:
 
-    === "Windows (64-bit)"
+=== "Windows (64-bit)"
 
-        The root directory is based on where you installed RetroArch, but by default it is:
+    The root directory is based on where you installed RetroArch, but by default it is:
 
-        ```batch
-        igir.exe copy zip test ^
-          --dat "No-Intro*.zip" ^
-          --input ROMs/ ^
-          --output C:\RetroArch-Win64\roms ^
-          --dir-dat-name ^
-          --no-bios
-        ```
+    ```batch
+    igir.exe copy zip test ^
+      --dat "No-Intro*.zip" ^
+      --input ROMs/ ^
+      --output C:\RetroArch-Win64\roms ^
+      --dir-dat-name ^
+      --no-bios
+    ```
 
-    === "Windows (32-bit)"
+=== "Windows (32-bit)"
 
-        The root directory is based on where you installed RetroArch, but by default it is:
+    The root directory is based on where you installed RetroArch, but by default it is:
 
-        ```batch
-        igir.exe copy zip test ^
-          --dat "No-Intro*.zip" ^
-          --input ROMs/ ^
-          --output C:\RetroArch-Win32\roms ^
-          --dir-dat-name \
-          --no-bios
-        ```
+    ```batch
+    igir.exe copy zip test ^
+      --dat "No-Intro*.zip" ^
+      --input ROMs/ ^
+      --output C:\RetroArch-Win32\roms ^
+      --dir-dat-name ^
+      --no-bios
+    ```
 
-    === "macOS"
+=== "macOS"
 
-        ```shell
-        igir copy zip test \
-          --dat "No-Intro*.zip" \
-          --input ROMs/ \
-          --output ~/Documents/RetroArch/roms \
-          --dir-dat-name \
-          --no-bios
-        ```
+    ```shell
+    igir copy zip test \
+      --dat "No-Intro*.zip" \
+      --input ROMs/ \
+      --output ~/Documents/RetroArch/roms \
+      --dir-dat-name \
+      --no-bios
+    ```
 
-From there, all you should have to do is "[import content](https://docs.libretro.com/guides/import-content/)."
+From there, all you should have to do is "[import content](https://docs.libretro.com/guides/import-content/)" in the RetroArch UI.
diff --git a/docs/usage/desktop/retropie.md b/docs/usage/desktop/retropie.md
@@ -1,8 +1,8 @@
 # RetroPie
 
-!!! info
+[RetroPie](https://retropie.org.uk/) is an installer for [EmulationStation](https://emulationstation.org/) & [RetroArch](https://www.retroarch.com/) on single-board computers (SBCs).
 
-    [RetroPie](https://retropie.org.uk/) is an installer for [EmulationStation](https://emulationstation.org/) & [RetroArch](https://www.retroarch.com/) on single-board computers (SBCs).
+## BIOS
 
 Because RetroPie uses RetroArch under the hood, the instructions are generally the [same as RetroArch](retroarch.md). By default, the RetroPie BIOS directory is `/home/pi/RetroPie/BIOS`:
 
@@ -14,3 +14,35 @@ Because RetroPie uses RetroArch under the hood, the instructions are generally t
       --input BIOS/ \
       --output /home/pi/RetroPie/BIOS
     ```
+
+## ROMs
+
+The [RetroPie docs](https://retropie.org.uk/docs/Transferring-Roms/) recommend creating a `retropie/roms` directory at the root of a USB drive. You can then load up this USB drive with your ROMs from a different computer:
+
+=== "Windows"
+
+    Replace the `E:\` drive letter with wherever your SD card is:
+
+    ```batch
+    igir copy zip test clean ^
+      --dat "No-Intro*.zip" ^
+      --input "ROMs" ^
+      --output "E:\retropie\roms" ^
+      --dir-dat-name ^
+      --dir-letter ^
+      --no-bios
+    ```
+
+=== "macOS"
+
+    Replace the `/Volumes/RETROPIE` drive name with whatever your SD card is named:
+
+    ```shell
+    igir copy zip test clean \
+      --dat "No-Intro*.zip" \
+      --input "ROMs/" \
+      --output "/Volumes/RETROPIE/retropie/roms/" \
+      --dir-dat-name \
+      --dir-letter \
+      --no-bios
+    ```
diff --git a/docs/usage/handheld/onionos.md b/docs/usage/handheld/onionos.md
@@ -6,6 +6,8 @@
 
 [OnionOS](https://github.com/OnionUI/Onion) is a popular "OS overhaul" for the Miyoo Mini, and [GarlicOS](https://www.patreon.com/posts/76561333) is a similar overhaul for the Anbernic RG35XX.
 
+## BIOS
+
 OnionOS has its BIOS folder at the root of the SD card at `/BIOS`, and it uses the [RetroArch filenames](https://github.com/OnionUI/Onion/wiki/Installation#step-3-copy-over-your-bios-and-rom-files):
 
 === "Windows"
@@ -30,7 +32,9 @@ OnionOS has its BIOS folder at the root of the SD card at `/BIOS`, and it uses t
       --output /Volumes/OnionOS/BIOS
     ```
 
-OnionOS uses its own proprietary [ROM folder structure](https://github.com/OnionUI/Onion/wiki/Emulators#rom-folders---quick-reference), so `igir` has a replaceable `{onion}` token to sort ROMs into the right place.
+## ROMs
+
+OnionOS uses its own proprietary [ROM folder structure](https://github.com/OnionUI/Onion/wiki/Emulators#rom-folders---quick-reference), so `igir` has a replaceable `{onion}` token to sort ROMs into the right place. See the [replaceable tokens page](../../output/tokens.md) for more information.
 
 === "Windows"