diff --git a/README.md b/README.md index 67fa5cdaf..0b8cdb042 100644 --- a/README.md +++ b/README.md @@ -27,19 +27,19 @@ A video of an example use case: -[![asciicast](https://asciinema.org/a/bZHvtbqyQlRfkHIuZXxmtDbiU.svg)](https://asciinema.org/a/bZHvtbqyQlRfkHIuZXxmtDbiU) + With Igir you can manage a ROM collection of any size: -- 🔍 Scan for DATs, ROMs, and ROM patches - including those in archives (see [scanning](https://igir.io/input/file-scanning) & [archive docs](https://igir.io/input/reading-archives)) +- 🔍 Scan for DATs, ROMs, and ROM patches—including those in archives (see [scanning](https://igir.io/input/file-scanning) & [archive docs](https://igir.io/input/reading-archives)) - 📂 Organize ROM files by console (see [DAT docs](https://igir.io/dats/overview)) - 🪄 Name ROM files consistently, including the right extension (see [DAT docs](https://igir.io/dats/overview)) - ✂️ Filter out duplicate ROMs, or ROMs in languages you don't understand (see [filtering docs](https://igir.io/roms/filtering-preferences)) - 🗜️ Extract or archive ROMs in mass (see [archive docs](https://igir.io/output/writing-archives)) - 🩹 Patch ROMs automatically in mass (see [scanning](https://igir.io/input/file-scanning) & [patching docs](https://igir.io/roms/patching)) -- 🎩 Parse ROMs with headers, and optionally remove them (see [header docs](https://igir.io/roms/headers)) +- 🎩 Parse ROMs with headers and optionally remove them (see [header docs](https://igir.io/roms/headers)) - ↔️ Build & re-build (un-merge, split, or merge) MAME ROM sets (see [arcade docs](https://igir.io/usage/arcade)) -- 🔮 Report on what ROMs are present or missing for each console, and create fixdats for missing ROMs (see [reporting](https://igir.io/output/reporting) & [DAT docs](https://igir.io/dats/overview)) +- 🔮 Report on what ROMs are present or missing for each console and create fixdats for missing ROMs (see [reporting](https://igir.io/output/reporting) & [DAT docs](https://igir.io/dats/overview)) ## How do I run Igir? diff --git a/docs/advanced/logging.md b/docs/advanced/logging.md index 68c8a1e44..9eae7272e 100644 --- a/docs/advanced/logging.md +++ b/docs/advanced/logging.md @@ -40,7 +40,7 @@ There are additional levels of verbosity that can be enabled with the `-v` flag: igir [commands..] [options] -vv ``` - This level is helpful to turn on if you want debug why an action didn't take place. + This level is helpful to turn on if you want to debug why an action didn't take place. - **`TRACE` (`-vvv`): print information about actions taken, skipped, and additional information that can be helpful to debug issues.** diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 000000000..8ea595c26 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,40 @@ +# CLI Overview + +Igir uses a series of live-updating progress bars to indicate what it is currently working on and how much processing is left to do. + + + +See the [internal operations](advanced/internals.md#order-of-operations) page for more information on every processing that Igir might do. + +## Progress bar icons + +ASCII symbols are used to indicate what processing is happening. Here is a table of those symbols, in order: + +| Symbol (magenta) | Scanning operation | +|------------------------------------------------------------|-------------------------------------------------------------------------------------------| +| ↻ (circle arrow) | Files (DATs, ROMs, patches, etc.) are being found/enumerated | +| ↓ (down arrow) | [DATs](dats/introduction.md) are being [downloaded](dats/processing.md#scanning-for-dats) | +| Σ (sigma) | [DATs](dats/introduction.md) are being parsed | +| # (hash) | ROMs are having checksums calculated for [matching](roms/matching.md) | +| ^ (hat) | ROMs are being checked for [headers](roms/headers.md) | + +| Symbol (cyan) | Per-DAT processing operation | +|--------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| ∩ (intersection) | DATs are having parent/clone information [inferred](dats/processing.md#parentclone-inference) | +| ↔ (split arrow) | DATs are having [merge/split rules](usage/arcade.md#rom-set-merge-types) applied | +| Σ (sigma) | ROMs are being [matched](roms/matching.md) to the DAT | +| ∆ (delta) | DAT is being [filtered](roms/filtering-preferences.md#filters), ROM [1G1R rules](roms/filtering-preferences.md#preferences-for-1g1r) are being applied | +| . (period) | ROM matches hare having their [extension corrected](output/options.md#fixing-rom-extensions) | +| ≟ (question equal) | ROM matches are being checked for issues | +| ∪ (union) | ROM matches are being combined into one zip | + +| Symbol (yellow) | Per-DAT writing operation | +|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| # (hash) | Archives are having checksums calculated to [test](commands.md#test) after [writing](commands.md#rom-writing) | +| ≟ (question equal) | Output files are being checked before being [overwritten](output/options.md#overwriting-files), no writing has started yet | +| ✎ (pencil) | Output files are or have been written | + +| Symbol | Deleting operation | +|-------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| +| ♻ (recycle) | Output directory [cleaned files](output/cleaning.md) are being recycled | +| ✕ (x) | Moved ROM matches are being deleted, output directory [cleaned files](output/cleaning.md) are being deleted | diff --git a/docs/dats/dir2dat.md b/docs/dats/dir2dat.md index cb825db9d..de6e5cb0e 100644 --- a/docs/dats/dir2dat.md +++ b/docs/dats/dir2dat.md @@ -2,7 +2,7 @@ "dir2dat" refers to DATs that have been automatically created based on files in an input directory. [DATs](./introduction.md) generated this way are not typically useful as-is, they usually require some hand editing after creation. -Igir has the ability to create these DATs with the `igir dir2dat` command. Example: +Igir can create these DATs with the `igir dir2dat` command. Example: ```shell igir dir2dat --input [--input ..] diff --git a/docs/dats/introduction.md b/docs/dats/introduction.md index 4f4357df1..bc1513c43 100644 --- a/docs/dats/introduction.md +++ b/docs/dats/introduction.md @@ -46,7 +46,7 @@ And some less popular release groups are: ## Parent/clone (P/C) DATs -DATs that include "parent" and "clone" information help Igir understand what game releases are actually the same game (are "clones" of each other). Frequently a game will be released in many regions or with different revisions, usually with only language translations and minor bug fixes. For example, No-Intro has 6+ "clones" of Pokémon Blue cataloged. +DATs that include "parent" and "clone" information help Igir understand what game releases are actually the same game (are "clones" of each other). Frequently, a game will be released in many regions or with different revisions, usually with only language translations and minor bug fixes. For example, No-Intro has 6+ "clones" of Pokémon Blue cataloged. Being able to know that many releases are actually the same game gives Igir the ability to produce "one game, one ROM" (1G1R) sets with the [`--single` option](../roms/filtering-preferences.md#preferences-for-1g1r). 1G1R sets include only one of these "clone" releases, usually filtered to a language and region, because many people don't care about ROMs they can't understand. diff --git a/docs/dats/processing.md b/docs/dats/processing.md index 8d8f2edd0..f1894427e 100644 --- a/docs/dats/processing.md +++ b/docs/dats/processing.md @@ -4,7 +4,7 @@ Igir has a number of ways it can process [DATs](./introduction.md), and it proce ## Just tell me what to do -[DATs](./introduction.md) can get fairly complicated, and there are many release groups each with their own focus areas and naming patterns. If all you want to do is organize your ROMs with Igir in some sane way, follow these instructions: +[DATs](./introduction.md) can get fairly complicated, and there are many release groups, each with their own focus areas and naming patterns. If all you want to do is organize your ROMs with Igir in some consistent way, follow these instructions: 1. Go to the No-Intro DAT-o-MATIC [daily download page](https://datomatic.no-intro.org/index.php?page=download&s=64&op=daily) 2. Select the "P/C XML" radio option (as opposed to "standard DAT") and download the `.zip` to wherever you store your ROMs diff --git a/docs/input/reading-archives.md b/docs/input/reading-archives.md index c70a1f84e..fb4379612 100644 --- a/docs/input/reading-archives.md +++ b/docs/input/reading-archives.md @@ -51,6 +51,6 @@ If for some reason Igir isn't identifying an input file correctly as an archive, ## Checksum cache -It can be expensive to calculate checksums of files within archives, especially MD5, SHA1, and SHA256. If Igir needs to calculate a checksum that is not easily read from the archive (see above), it will cache the result in a file named `igir.cache`. This cached result will then be used as long as the input file's size and modified timestamp remain the same. +It can be expensive to calculate checksums of files within archives, especially MD5, SHA1, and SHA256. If Igir needs to calculate a checksum not easily read from the archive (see above), it will cache the result in a file named `igir.cache`. This cached result will then be used as long as the input file's size and modified timestamp remain the same. The location of this cache file can be controlled with the `--cache-path ` option, or caching can be disabled entirely with the `--disable-cache` option. You can safely delete `igir.cache` when Igir isn't running if the file becomes too large for you. diff --git a/docs/installation.md b/docs/installation.md index 9ba1e3d0a..cc6475a71 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -21,7 +21,7 @@ for example: npx igir@latest copy extract --dat *.dat --input ROMs/ --output ROMs-Sorted/ --dir-dat-name ``` -[![asciicast](https://asciinema.org/a/IFU8rU8k800TMVWb9xXv4Jbsv.svg)](https://asciinema.org/a/IFU8rU8k800TMVWb9xXv4Jbsv) + !!! tip @@ -49,7 +49,7 @@ npx igir@latest copy extract --dat *.dat --input ROMs/ --output ROMs-Sorted/ --d ## Via Homebrew (macOS) -[Homebrew](https://brew.sh/) is third-party package manager for macOS. You can install Igir with these simple commands: +[Homebrew](https://brew.sh/) is a third-party package manager for macOS. You can install Igir with these simple commands: ```shell brew tap emmercm/igir diff --git a/docs/overview.md b/docs/introduction.md similarity index 82% rename from docs/overview.md rename to docs/introduction.md index 69d600dd7..0b0cd41aa 100644 --- a/docs/overview.md +++ b/docs/introduction.md @@ -1,4 +1,4 @@ -# Overview +# Introduction ## What is a ROM? @@ -8,7 +8,7 @@ From [Wikipedia](https://en.wikipedia.org/wiki/ROM_image): ROMs are complete copies of game data stored in cartridges or on discs. -A game may consist of multiple ROMs. For example, arcade cabinets that contain multiple chips, or disc-based games that have multiple tracks on the disc. +A game may consist of multiple ROMs. For example, arcade cabinets, which contain multiple chips, or disc-based games that have multiple tracks on the disc. ## What is a ROM manager? @@ -19,9 +19,9 @@ ROM managers are applications that serve two main purposes: all additional features help serve these two purposes. -Most ROM managers can automatically read & write many different ROM types including those in [archives](input/reading-archives.md) and those with [headers](roms/headers.md) so that you don't have to do much pre-work. +Most ROM managers can automatically read & write many different ROM types, including those in [archives](input/reading-archives.md) and those with [headers](roms/headers.md) so that you don't have to do much pre-work. -Most ROM managers rely on [DATs](dats/introduction.md), files that catalog every known ROM that exists per game system. DATs are published by release groups dedicated to keeping these catalogs accurate and up-to-date. DATs help ROM collectors name their ROMs in a consistent way as well as understand what ROMs may be missing from their collection. +Most ROM managers rely on [DATs](dats/introduction.md), files that catalog every known ROM that exists per game system. DATs are published by release groups dedicated to keeping these catalogs accurate and up to date. DATs help ROM collectors name their ROMs consistently as well as understand what ROMs may be missing from their collection. ## What is Igir? diff --git a/docs/output/cleaning.md b/docs/output/cleaning.md index 98d5f747f..7b8dafc3b 100644 --- a/docs/output/cleaning.md +++ b/docs/output/cleaning.md @@ -47,7 +47,7 @@ See the [Analogue Pocket](../usage/hardware/analogue-pocket.md) page for a pract ## Backing up cleaned files -By default, Igir will recycle cleaned files, and if recycle fails then it will delete them. This is potentially destructive, so a `--clean-backup ` option is provided to instead move files to a backup directory. +By default, Igir will recycle cleaned files, and if recycle fails, then it will delete them. This is potentially destructive, so a `--clean-backup ` option is provided to instead move files to a backup directory. The input directory structure is not maintained, no subdirectories will be created in the backup directory. Files of conflicting names will have a number appended to their name, e.g. `File (1).rom`. diff --git a/docs/output/reporting.md b/docs/output/reporting.md index 30562f1be..dbc5d68f5 100644 --- a/docs/output/reporting.md +++ b/docs/output/reporting.md @@ -13,7 +13,7 @@ When using DATs (the [`--dat ` option](../dats/processing.md#scanning-for- 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/introduction.md) for more information about DATs. -The `igir report` command can be specified on its own without any [writing command](../commands.md) (i.e. `igir copy`, `igir move`, etc.) in order to report on an existing collection. This causes Igir to operate in a _read-only_ mode, no files will be copied, moved, or deleted. For example: +The `igir report` command can be specified on its own without any [writing command](../commands.md) (i.e. `igir copy`, `igir move`, etc.) to report on an existing collection. This causes Igir to operate in a _read-only_ mode, no files will be copied, moved, or deleted. For example: === ":simple-windowsxp: Windows" @@ -48,7 +48,7 @@ See the `igir --help` message for the report's default location. The output report format is a standard CSV that can be opened in Microsoft Excel, Apple Numbers, Google Sheets, LibreOffice Calc, and other similar spreadsheet applications. -Unlike the report formats of [other ROM managers](../alternatives.md), CSVs allow you to filter rows by column values. For example, you can filter the "Status" column to only "MISSING" to understand what ROMs are missing from your collection, or to "UNUSED" to understand what input files weren't used as the source of any output file. The ability to filter CSVs in spreadsheet applications means that Igir should not need use-case-specific report options to achieve your goal. +Unlike the report formats of [other ROM managers](../alternatives.md), CSVs allow you to filter rows by column values. For example, you can filter the "Status" column to only "MISSING" to understand what ROMs are missing from your collection, or to "UNUSED" to understand what input files weren't used as the source of any output file. The ability to filter CSVs in spreadsheet applications means that Igir shouldn’t need use-case-specific report options to achieve your goal. To perform this filtering, most spreadsheet applications have a button or menu item to "create a filter" or "auto filter." diff --git a/docs/rom-dumping.md b/docs/rom-dumping.md index e73bd4b1c..14ed87166 100644 --- a/docs/rom-dumping.md +++ b/docs/rom-dumping.md @@ -10,7 +10,7 @@ [Dumping.Guide](https://dumping.guide/start) and [Emulation General Wiki](https://emulation.gametechwiki.com/index.php/Ripping_games) are some of the best resources for legally creating ROM files from games you own. -Here is a condensed version that isn't guaranteed to be up-to-date. +Here is a condensed version that isn't guaranteed to be up to date. ## Generation 1-5 cartridge-based consoles diff --git a/docs/roms/filtering-preferences.md b/docs/roms/filtering-preferences.md index 891c00531..2d8c0a62f 100644 --- a/docs/roms/filtering-preferences.md +++ b/docs/roms/filtering-preferences.md @@ -14,7 +14,7 @@ Multiple filter options can be specified at once. --filter-regex , --filter-regex-exclude ``` -Only include, or exclude games based if their DAT name (or filename if not using DATs) matches a regular expression. +Only include or exclude games based if their DAT name (or filename if not using DATs) matches a regular expression. Regex flags can be optionally provided in the form `//`, for example: @@ -50,7 +50,7 @@ Wario Land II (USA, Europe) (SGB Enhanced) Languages are two-letter codes, and multiple languages can be specified with commas between them. See the `--help` message for the full list of understood languages. -If a game does not have language information specified, it will be inferred from the region. +If a game doesn’t have language information specified, it will be inferred from the region. Here are some example game names that Igir can parse languages from, including ones with multiple languages: @@ -129,7 +129,7 @@ Filter out, or only include games that are marked `bios="yes"` in the DAT, or co --no-device, --only-device ``` -Filter out, or only include [MAME devices](https://wiki.mamedev.org/index.php/MAME_Device_Basics). MAME devices typically represent physical devices, such as microcontrollers, video display controllers, sounds boards, and more. Many MAME devices don't have any associated ROM files. +Filter out or only include [MAME devices](https://wiki.mamedev.org/index.php/MAME_Device_Basics). MAME devices typically represent physical devices, such as microcontrollers, video display controllers, sounds boards, and more. Many MAME devices don't have any associated ROM files. ### Unlicensed @@ -245,7 +245,7 @@ Perfect Dark (USA) (2000-03-22) (Debug) --no-demo, --only-demo ``` -Filter out, or only include games that contain one of the following in their name: +Filter out or only include games that contain one of the following in their name: - `(Demo[a-z0-9. -]*)` (regex) - `@barai` @@ -310,7 +310,7 @@ Sword of Hope, The (Europe) (Proto) --no-program, --only-program ``` -Filter out, or only include games that contain one of the following in their name +Filter out or only include games that contain one of the following in their name - `([a-z0-9. ]*Program)` (regex) - `Check Program` @@ -450,7 +450,7 @@ See the [bad dumps](#bad-dumps) section for more information about "good" and "b Prefer games of certain languages over those in other languages. Multiple languages can be specified, in priority order, with commas between them. See the `--help` message for the full list of understood languages. -If a game does not have language information specified, it will be inferred from the region. +If a game doesn’t have language information specified, it will be inferred from the region. For example, to prefer games in English and _then_ Japanese, the command would be: diff --git a/docs/roms/headers.md b/docs/roms/headers.md index c378fa4ca..b5dc7b5a9 100644 --- a/docs/roms/headers.md +++ b/docs/roms/headers.md @@ -16,7 +16,7 @@ Igir can detect headers for the following consoles and file extensions: | Nintendo - Famicom Disk System | fsNES/FDS | `.fds` | | Nintendo - SNES | SMC | `.smc` | -Those file extensions above are the commonly accepted "correct" extensions and Igir will attempt to detect if a header is present in those ROM files automatically. If for some reason your files don't have the right extension (e.g. `.rom`) you can force header detection with the `--header` glob option: +Those file extensions above are the commonly accepted "correct" extensions, and Igir will attempt to detect if a header is present in those ROM files automatically. If for some reason your files don't have the right extension (e.g. `.rom`) you can force header detection with the `--header` glob option: ```shell igir [commands..] --dat --input --header "*.rom" @@ -30,7 +30,7 @@ Igir will use this detected header information to compute both "headered" and "h ## Manual header removal -Some emulators cannot parse ROMs with headers and instead need a "headerless" version. This seems to be most common with SNES. Sometimes "headerless" files will have a different file extension: +Some emulators cannot parse ROMs with headers and instead need a "headerless" version. This seems most common with SNES. Sometimes "headerless" files will have a different file extension: | Console | Header | Headered
Extension | Headerless
Extension | |--------------------------------|---------------|------------------------|--------------------------| diff --git a/docs/roms/matching.md b/docs/roms/matching.md index 700453c10..6a8445d91 100644 --- a/docs/roms/matching.md +++ b/docs/roms/matching.md @@ -62,7 +62,7 @@ igir [commands..] [options] --input-checksum-min SHA256 This option defines the _minimum_ checksum that will be used based on digest size (below). If not every ROM in every DAT provides the checksum you specify, Igir may automatically calculate and match files based on a higher checksum (see above), but never lower. -The reason you might want to do this is to have a higher confidence that found files _exactly_ match ROMs in DATs. Just keep in mind that explicitly enabling non-CRC32 checksums will _greatly_ slow down scanning of files within archives (see "quick scanning" above). +The reason you might want to do this is to have a higher confidence that found files _exactly_ match ROMs in DATs. Keep in mind that explicitly enabling non-CRC32 checksums will _greatly_ slow down scanning of files within archives (see "quick scanning" above). Here is a table that shows the keyspace for each checksum algorithm, where the higher number of bits reduces the chances of collisions: diff --git a/docs/roms/patching.md b/docs/roms/patching.md index 8d8d178b0..7f9f6376a 100644 --- a/docs/roms/patching.md +++ b/docs/roms/patching.md @@ -2,7 +2,7 @@ Patches contain a set of changes that can be applied to a file, turning that file into something different. Common examples for patching ROMs are: translating text to a different language but keeping game logic the same, and fan-made creations such as new levels for an existing game. -Games and their ROMs are protected under copyrights, so patches are used in order to not share copyrighted code online. A person needs the original ROM file plus a patch file in order to get the resulting patched ROM that will be played with an emulator. +Games and their ROMs are protected under copyrights, so patches are used to not share copyrighted code online. A person needs the original ROM file plus a patch file to get the resulting patched ROM that will be played with an emulator. ## Specifying patch files diff --git a/docs/usage/arcade.md b/docs/usage/arcade.md index 40f0f3202..d5f4f76b9 100644 --- a/docs/usage/arcade.md +++ b/docs/usage/arcade.md @@ -86,7 +86,7 @@ The ROM merge type can be specified with the `--merge-roms ` option: As arcade machines got more complicated, their storage requirements grew beyond what ROM chips can handle cost effectively. Cabinets started embedding hard drives, optical drives, laser disc drives, and more. Because backup images of these media types can get large, the MAME developers created a new compression format called "compressed hunks of data" (CHD). -MAME DATs catalog these "disks" separately from "ROMs", which lets users choose whether to care about them or not. Typically, games that require disks will not run without them, so Igir requires them for a game to be considered present/complete. You can use the `--exclude-disks` option to exclude disks and only process ROMs to save some space. +MAME DATs catalog these "disks" separately from "ROMs," which lets users choose whether to care about them or not. Typically, games that require disks will not run without them, so Igir requires them for a game to be considered present/complete. You can use the `--exclude-disks` option to exclude disks and only process ROMs to save some space. ## Example: building a new ROM set @@ -168,9 +168,9 @@ Most other ROM managers use the terms "re-build" & "fix" when talking about taki A game's required ROM files may change between emulator versions. This usually occurs when bad ROM dumps are replaced with better dumps. Igir cannot magically deal with these ROM differences, and Igir will only write complete ROM sets, so you may see games disappear when re-building. You will need to source the differing ROM files in order to keep your full game set. -A major reason Igir was created was to help disambiguate what it means to build & re-build ROM sets. Igir explicitly requires users to choose whether ROM files are copied or moved, so that users know what decision they are making. To "re-build" a ROM set, a user just needs to `igir move` ROMs from an input directory to the same directory specified again as the output. +A major reason Igir was created was to help disambiguate what it means to build & re-build ROM sets. Igir explicitly requires users to choose whether ROM files are copied or moved, so that users know what decision they’re making. To "re-build" a ROM set, a user just needs to `igir move` ROMs from an input directory to the same directory specified again as the output. -Taking the MAME v0.258 set we created above, let's say we want to "downgrade" it to MAME 2003 (v0.78) because an under-powered device requires it. The steps would look like this: +Taking the MAME v0.258 set we created above, let's say we want to "downgrade" it to MAME 2003 (v0.78) because an underpowered device requires it. The steps would look like this: 1. **Locate or download the emulator version's DAT.** diff --git a/docs/usage/collection-sorting.md b/docs/usage/basic.md similarity index 54% rename from docs/usage/collection-sorting.md rename to docs/usage/basic.md index e25ce7d1e..e0593648d 100644 --- a/docs/usage/collection-sorting.md +++ b/docs/usage/basic.md @@ -1,4 +1,4 @@ -# Collection Sorting Example +# Basic Usage Examples A walkthrough of an example way to sort your ROM collection. @@ -6,11 +6,15 @@ A walkthrough of an example way to sort your ROM collection. See the `igir --help` message for a few common examples. -## First time collection sort +## With DATs + +Even though Igir can work without [DATs](../dats/introduction.md), using DATs to sort your collection is the [best practice](best-practices.md) to end up with the most accurate and organized set of ROMs. + +### First time collection sort First, you need to download a set of [DATs](../dats/introduction.md). For these examples I'll assume you downloaded a No-Intro daily P/C XML `.zip`. -Let's say that you have a directory named `ROMs/` that contains ROMs for many different systems, and it needs some organization. To make sure we're alright with the output, we'll have Igir copy these files rather than move them. We'll also zip them to reduce disk space & speed up future scans. +Let's say that you have a directory named `ROMs/` that contains ROMs for many different systems, and it needs some organization. To make sure we're alright with the output, we'll have Igir copy these files to a different directory rather than move them. We'll also [zip](../output/writing-archives.md) them to reduce disk space & speed up future scans. === ":simple-windowsxp: Windows" @@ -42,12 +46,12 @@ Let's say that you have a directory named `ROMs/` that contains ROMs for many di --dir-dat-name ``` -This will organize your ROMs into system-specific subdirectories within `ROMs-Sorted/` and name all of your ROMs accurately. Because we copied and didn't move, no files were deleted from the `ROMs/` input directory. +This will organize your ROMs into system-specific subdirectories within `ROMs-Sorted/` and name all of your ROMs according to the No-Intro DATs. Because we copied and didn't move the files, no files were deleted from the `ROMs/` input directory. `ROMs-Sorted/` then might look something like this: ```text -ROMs-Sorted +ROMs-Sorted/ ├── Nintendo - Game Boy │ ├── Pokemon - Blue Version (USA, Europe) (SGB Enhanced).zip │ └── Pokemon - Yellow Version - Special Pikachu Edition (USA, Europe) (CGB+SGB Enhanced).zip @@ -59,13 +63,17 @@ ROMs-Sorted └── Pokemon Pinball (USA, Australia) (Rumble Version) (SGB Enhanced) (GB Compatible).zip ``` -[![asciicast](https://asciinema.org/a/J6RnpFif6QJrkageFvKH39btk.svg)](https://asciinema.org/a/J6RnpFif6QJrkageFvKH39btk) + + +!!! info + + See the [output path options](../output/path-options.md) and [output path tokens](../output/tokens.md) pages for other ways that you can organize your collection. -## Subsequent collection sorts +### Subsequent collection sorts -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. +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 "golden" or "primary" collection, as 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](../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. +We now have new ROMs that we want to newly merge into our collection, and we want to generate a [report](../output/reporting.md) of what ROMs are still missing. We also want to "[clean](../output/cleaning.md)" or delete any unknown files that may have made their way into our collection. === ":simple-windowsxp: Windows" @@ -102,10 +110,16 @@ Now we have new ROMs that we want to merge into our collection, and we want to g Any new ROMs in `ROMs-New/` that we didn't already have in `ROMs-Sorted/` will be moved, and a report will be generated for us. +!!! note + + Note that we're using `ROMs-Sorted/` as both an input directory _and_ as the output directory. This is required to ensure the [`clean` command](../output/cleaning.md) doesn't delete "good" files already in the output directory! + + You can always use the [`--clean-dry-run` option](../output/cleaning.md#dry-run) to see what files would be deleted without actually deleting them. + `ROMs-Sorted/` then might look something like this, with new ROMs added: ```text -ROMs-Sorted +ROMs-Sorted/ ├── Nintendo - Game Boy │ ├── Pokemon - Blue Version (USA, Europe) (SGB Enhanced).zip │ ├── Pokemon - Red Version (USA, Europe) (SGB Enhanced).zip @@ -119,13 +133,13 @@ ROMs-Sorted └── Pokemon Pinball (USA, Australia) (Rumble Version) (SGB Enhanced) (GB Compatible).zip ``` -[![asciicast](https://asciinema.org/a/WAip4pJrNIKk0IGamov7Js4ba.svg)](https://asciinema.org/a/WAip4pJrNIKk0IGamov7Js4ba) + -## Flash cart 1G1R +### Flash cart 1G1R Let's say we've done the above sorting we want to copy some ROMs from `ROMs-Sorted/` to a flash cart. -We would prefer having only one copy of every game (1G1R), so there is less to scroll through to find what we want, and because we have a preferred language. Our flash cart can't read `.zip` files, so we'll need to extract our ROMs during copying. +We would prefer having only one copy of every game ([1G1R](../roms/filtering-preferences.md#preferences-for-1g1r)), because we have a preferred language, and so there is less to scroll through to find what game we want. Our flash cart can't read `.zip` files, so we'll need to extract our ROMs during copying. === ":simple-windowsxp: Windows" @@ -185,8 +199,85 @@ Your flash cart might then look something like this: └── Pokemon - Yellow Version - Special Pikachu Edition (USA, Europe) (CGB+SGB Enhanced).gb ``` -[![asciicast](https://asciinema.org/a/GxXyngUlZ5Xg8pCh6GhJdDc4t.svg)](https://asciinema.org/a/GxXyngUlZ5Xg8pCh6GhJdDc4t) + !!! info See the [ROM filtering & preference](../roms/filtering-preferences.md) page for other ways that you can filter your collection. + +## Without DATs + +ROM organization is very opinion-based, and your opinion may not match that of DAT groups. To preserve your custom ROM sorting, you can skip providing any DATs by omitting the `--dat ` option. + +!!! note + + If your custom ROM sorting includes directories, you will want to provide the [`--dir-mirror` option](../output/path-options.md#mirror-the-input-subdirectory) to preserve the structure. + +### Extracting or zipping all ROMs + +It is possible to extract or zip your ROM files en masse without complicated Bash or Batch scripts, and you can do this without DATs because the root of the filename won't change. + +=== ":simple-windowsxp: Windows" + + ```batch + igir move extract test ^ + --input "ROMs\" ^ + --output "ROMs\" ^ + --dir-mirror + ``` + +=== ":simple-apple: macOS" + + ```shell + igir move extract test \ + --input "ROMs/" \ + --output "ROMs/" \ + --dir-mirror + ``` + +=== ":simple-linux: Linux" + + ```shell + igir move extract test \ + --input "ROMs/" \ + --output "ROMs/" \ + --dir-mirror + ``` + + + +### Fixing file extensions + +Igir is able to detect more than 50 ROM and archive file types and automatically correct file extensions when needed during writing. See the [writing options](../output/options.md#fixing-rom-extensions) page for more information. + +=== ":simple-windowsxp: Windows" + + ```batch + igir move extract test ^ + --input "ROMs\" ^ + --output "ROMs\" ^ + --dir-mirror ^ + --fix-extension always + ``` + +=== ":simple-apple: macOS" + + ```shell + igir move extract test \ + --input "ROMs/" \ + --output "ROMs/" \ + --dir-mirror \ + --fix-extension always + ``` + +=== ":simple-linux: Linux" + + ```shell + igir move extract test \ + --input "ROMs/" \ + --output "ROMs/" \ + --dir-mirror \ + --fix-extension always + ``` + + diff --git a/docs/usage/personal.md b/docs/usage/personal.md index 60d70fce6..2ba9eda4b 100644 --- a/docs/usage/personal.md +++ b/docs/usage/personal.md @@ -1,6 +1,6 @@ -# Creator's Usage Example +# Maintainer's Usage Example -Igir has many options available to fit almost any use case, but the number of options can be overwhelming. So that begs a question: _how do I, the creator of Igir, use Igir in the real world?_ +Igir has many options available to fit almost any use case, but the number of options can be overwhelming. So that begs a question: _how do I, the maintainer of Igir, use Igir in the real world?_ ## Primary ROM library @@ -58,22 +58,60 @@ for INPUT in "$@"; do INPUTS+=(--input "${INPUT}") done +# Cartridge-based consoles, 1st-5th generations npx --yes igir@latest move zip test clean report \ --dat "./No-Intro*.zip" \ - --dat-name-regex-exclude "/encrypted/i" \ + --dat-name-regex-exclude "/encrypted|source code/i" \ --input "./No-Intro/" \ - "${INPUTS[@]}" \ + "${INPUTS[@]:-}" \ + `# Trust checksums in archive headers, don't checksum archives (we only care about the contents)` \ + --input-checksum-max CRC32 \ + --input-checksum-archives never \ --patch "./Patches/" \ --output "./No-Intro/" \ --dir-dat-name \ - --overwrite-invalid + --overwrite-invalid \ + --zip-exclude "*.{chd,iso}" \ + --reader-threads 4 \ + -v -npx --yes igir@latest move zip test \ +# Disc-based consoles, 4th+ generations +npx --yes igir@latest move test clean report \ --dat "./Redump*.zip" \ + --dat-name-regex-exclude "/Dreamcast/i" \ --input "./Redump/" \ "${INPUTS[@]}" \ + `# Let maxcso calculate CSO CRC32s, don't checksum compressed discs (we only care about the contents)` \ + --input-checksum-max CRC32 \ + --input-checksum-archives never \ + --patch "./Patches/" \ --output "./Redump/" \ - --dir-dat-name + --dir-dat-name \ + --overwrite-invalid \ + --only-retail \ + --single \ + --prefer-language EN \ + --prefer-region USA,WORLD,EUR,JPN \ + --prefer-revision newer \ + -v + +# Dreamcast (because TOSEC catalogs chdman-compatible .gdi files and Redump catalogs .bin/.cue) +npx --yes igir@latest move test clean report \ + --dat "./TOSEC*.zip" \ + --dat-name-regex "/Dreamcast/i" \ + --dat-combine \ + --input "./TOSEC/" \ + "${INPUTS[@]}" \ + --input-checksum-archives never \ + --patch "./Patches/" \ + --output "./TOSEC/Sega Dreamcast" \ + --overwrite-invalid \ + --only-retail \ + --single \ + --prefer-language EN \ + --prefer-region USA,WORLD,EUR,JPN \ + --prefer-revision newer \ + -v npx --yes igir@latest move zip test clean \ `# Official MAME XML extracted from the progetto-SNAPS archive` \ @@ -82,10 +120,13 @@ npx --yes igir@latest move zip test clean \ --dat "./MAME*Rollback*.zip" \ --input "./MAME/" \ "${INPUTS[@]}" \ + --input-checksum-quick \ + --input-checksum-archives never \ --output "./MAME/" \ --dir-dat-name \ --overwrite-invalid \ - --merge-roms split + --merge-roms merged \ + -v ``` I then copy ROMs to other devices from this source of truth. @@ -117,6 +158,7 @@ npx igir@latest copy extract test clean \ --input-exclude "${SOURCE}/No-Intro/Commodore - Amiga*/**" \ --input-exclude "${SOURCE}/No-Intro/Nintendo - Nintendo - Family Computer Disk System (QD)/" \ --input-exclude "${SOURCE}/No-Intro/Nintendo - Game Boy Advance (e-Reader)/" \ + --input-checksum-quick \ --patch "${SOURCE}/Patches/" \ --output "./Assets/{pocket}/common/" \ --dir-letter \ @@ -130,7 +172,7 @@ npx igir@latest copy extract test clean \ --single \ --prefer-language EN \ --prefer-region USA,WORLD,EUR,JPN \ - --prefer-revision-newer \ + --prefer-revision newer \ --prefer-retail \ -v ``` @@ -158,8 +200,10 @@ SOURCE=/Volumes/WDPassport4 npx --yes igir@latest copy test clean report \ --dat "${SOURCE}/Redump*.zip" \ - --dat-name-regex "/gamecube/i" \ + --dat-name-regex "/GameCube/i" \ --input "${SOURCE}/Redump/Nintendo - GameCube" \ + --input-checksum-quick \ + --input-checksum-archives never \ --patch "${SOURCE}/Patches" \ --output "./Games/" \ --dir-letter \ @@ -170,7 +214,7 @@ npx --yes igir@latest copy test clean report \ --single \ --prefer-language EN \ --prefer-region USA,WORLD,EUR,JPN \ - --prefer-revision-newer \ + --prefer-revision newer \ --writer-threads 1 \ -v ``` diff --git a/mkdocs.yml b/mkdocs.yml index 23635a888..f67d59b3e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,81 +41,82 @@ theme: nav: - Documentation: - - index.md - - Getting Started: - - overview.md - - installation.md - - commands.md - - alternatives.md - - Standard Usage: - - usage/collection-sorting.md - - usage/personal.md - - usage/best-practices.md - - Hardware-Specific Usage: - - Emulator Frontends: - - usage/handheld/adam.md - - usage/desktop/batocera.md - - usage/desktop/emuelec.md - - usage/desktop/emulationstation.md - - usage/handheld/funkeyos.md - - usage/handheld/jelos.md - - usage/desktop/lakka.md - - usage/desktop/launchbox.md - - usage/handheld/minui.md - - usage/handheld/miyoocfw.md - - usage/handheld/onionos.md - - usage/desktop/openemu.md - - usage/desktop/recalbox.md - - usage/desktop/retroarch.md - - usage/desktop/retrodeck.md - - usage/desktop/retropie.md - - usage/desktop/romm.md - - usage/handheld/twmenu.md - - FPGA: - - usage/hardware/mister.md - - usage/hardware/analogue-pocket.md - - Flash Carts: - - usage/hardware/everdrive.md - - usage/hardware/ezflash.md - - Game Consoles: - - usage/console/gamecube.md - - usage/console/ps2.md - - usage/arcade.md - - DATs: - - dats/introduction.md - - dats/processing.md - - dats/dir2dat.md - - dats/fixdats.md - - File Inputs: - - input/file-scanning.md - - input/reading-archives.md - - ROM Processing: - - roms/matching.md - - roms/filtering-preferences.md - - roms/headers.md - - roms/patching.md - - File Outputs: - - output/path-options.md - - output/tokens.md - - output/options.md - - output/writing-archives.md - - output/reporting.md - - output/cleaning.md - - Advanced: - - advanced/logging.md - - advanced/temp-dir.md - - advanced/troubleshooting.md - - advanced/internals.md - - Misc: - - rom-dumping.md - - Terms and Conditions: - - contributing.md - - license.md + - index.md + - Getting Started: + - introduction.md + - installation.md + - commands.md + - cli.md + - alternatives.md + - General Usage: + - usage/basic.md + - usage/personal.md + - usage/best-practices.md + - Hardware-Specific Usage: + - Emulator Frontends: + - usage/handheld/adam.md + - usage/desktop/batocera.md + - usage/desktop/emuelec.md + - usage/desktop/emulationstation.md + - usage/handheld/funkeyos.md + - usage/handheld/jelos.md + - usage/desktop/lakka.md + - usage/desktop/launchbox.md + - usage/handheld/minui.md + - usage/handheld/miyoocfw.md + - usage/handheld/onionos.md + - usage/desktop/openemu.md + - usage/desktop/recalbox.md + - usage/desktop/retroarch.md + - usage/desktop/retrodeck.md + - usage/desktop/retropie.md + - usage/desktop/romm.md + - usage/handheld/twmenu.md + - FPGA: + - usage/hardware/mister.md + - usage/hardware/analogue-pocket.md + - Flash Carts: + - usage/hardware/everdrive.md + - usage/hardware/ezflash.md + - Game Consoles: + - usage/console/gamecube.md + - usage/console/ps2.md + - usage/arcade.md + - DATs: + - dats/introduction.md + - dats/processing.md + - dats/dir2dat.md + - dats/fixdats.md + - File Inputs: + - input/file-scanning.md + - input/reading-archives.md + - ROM Processing: + - roms/matching.md + - roms/filtering-preferences.md + - roms/headers.md + - roms/patching.md + - File Outputs: + - output/path-options.md + - output/tokens.md + - output/options.md + - output/writing-archives.md + - output/reporting.md + - output/cleaning.md + - Advanced: + - advanced/logging.md + - advanced/temp-dir.md + - advanced/troubleshooting.md + - advanced/internals.md + - Misc: + - rom-dumping.md + - Terms and Conditions: + - contributing.md + - license.md # https://github.com/squidfunk/mkdocs-material/issues/889#issuecomment-582297142: how-to open nav links in new tabs - Download ↗: https://github.com/emmercm/igir/releases/latest" target="_blank - - Donate ↗: https://github.com/sponsors/emmercm" target="_blank - - Issues ↗: https://github.com/emmercm/igir/issues?q=is%3Aopen+is%3Aissue+label%3Abug" target="_blank - Discuss ↗: https://github.com/emmercm/igir/discussions" target="_blank + - Issues ↗: https://github.com/emmercm/igir/issues?q=is%3Aopen+is%3Aissue+label%3Abug" target="_blank + - Donate ↗: https://github.com/sponsors/emmercm" target="_blank plugins: - unused_files: @@ -136,15 +137,17 @@ plugins: 'archives.md': 'input/reading-archives.md' 'dats.md': 'dats/introduction.md' 'dats/overview.md': 'dats/introduction.md' - 'examples.md': 'usage/collection-sorting.md' + 'examples.md': 'usage/basic.md' 'input/archives.md': 'input/reading-archives.md' 'input/dats.md': 'dats/introduction.md' 'internals.md': 'advanced/internals.md' 'output/arcade.md': 'usage/arcade.md' + 'overview.md': 'introduction.md' 'reporting.md': 'output/reporting.md' 'rom-filtering.md': 'roms/filtering-preferences.md' 'rom-headers.md': 'roms/headers.md' 'rom-patching.md': 'roms/patching.md' + 'usage/collection-sorting.md': 'usage/basic.md' #- htmlproofer: # raise_error_excludes: # '-1': [ 'http://www.logiqx.com' ] diff --git a/scripts/asciinema-rec.sh b/scripts/asciinema-rec.sh index fb9e69887..de46443c4 100755 --- a/scripts/asciinema-rec.sh +++ b/scripts/asciinema-rec.sh @@ -22,7 +22,7 @@ if [[ "${1:-}" == "play" ]]; then # shellcheck disable=SC2317 npx() { shift # discard "igir@latest" - node ../dist/index.js "$@" --dat-name-regex-exclude "/encrypted|headerless|3ds/i" + node ../dist/index.js "$@" --dat-name-regex-exclude "/encrypted|headerless|3ds/i" --disable-cache } # shellcheck disable=SC2317 tree() { @@ -31,11 +31,11 @@ if [[ "${1:-}" == "play" ]]; then # BEGIN PLAYBACK # ts-node ./index.ts copy zip clean -d demo/No-Intro*.zip -i GB/ -i NES/ -o demo/roms/ -D - pei "tree -L 1 ." + pei 'tree -L 1 .' echo "" && sleep 2 - pei "npx igir@latest copy zip report --dat 'No-Intro*.zip' --input ROMs/ --output ROMs-Sorted/ --dir-dat-name --only-retail" + pei 'npx igir@latest copy zip report --dat "No-Intro*.zip" --input ROMs/ --output ROMs-Sorted/ --dir-dat-name --only-retail' echo "" && sleep 2 - pei "tree -L 1 ROMs-Sorted/" + pei 'tree -L 1 ROMs-Sorted/' # END PLAYBACK exit 0