Pronounced "eager," igir is a video game ROM collection manager to help filter, sort, patch, archive, and report on collections on any OS.
See the project website for complete documentation, installation & usage instructions, and examples!
A video of an example use case:
With igir you can manage a ROM collection of any size:
- 🔍 Scan for DATs, ROMs, and ROM patches - including those in archives (see scanning & archive docs)
- 📂 Organize ROM files by console (see DAT docs)
- 🪄 Name ROM files consistently, including the right extension (see DAT docs)
- ✂️ Filter out duplicate ROMs, or ROMs in languages you don't understand (see filtering docs)
- 🗜️ Extract or archive ROMs in mass (see archive docs)
- 🩹 Patch ROMs automatically in mass (see scanning & patching docs)
- 🎩 Parse ROMs with headers, and optionally remove them (see header docs)
- 🔮 Report on what ROMs are present or missing for each console, and create fixdats for missing ROMs (see reporting & DAT docs)
Either download the latest version for your OS from the releases page, or if you have Node.js installed you can use npx to always run the latest version from the command line:
npx igir@latest [commands..] [options]Here is the full help message which shows all available options and a number of common use case examples:
$ igir --help
______ ______ ______ _______
| \ / \ | \| \
\$$$$$$| $$$$$$\ \$$$$$$| $$$$$$$\
| $$ | $$ __\$$ | $$ | $$__| $$
| $$ | $$| \ | $$ | $$ $$ ROM collection manager
| $$ | $$ \$$$$ | $$ | $$$$$$$\
_| $$_ | $$__| $$ _| $$_ | $$ | $$ v1.6.4
| $$ \ \$$ $$| $$ \| $$ | $$
\$$$$$$ \$$$$$$ \$$$$$$ \$$ \$$
Usage: igir [commands..] [options]
Commands (can specify multiple):
igir copy Copy ROM files from the input to output directory
igir move Move ROM files from the input to output directory
igir symlink Create symlinks in the output directory to ROM files in the input directory
igir extract Extract ROM files in archives when copying or moving
igir zip Create zip archives of ROMs when copying or moving
igir test Test ROMs for accuracy after writing them to the output directory
igir clean Recycle unknown files in the output directory
igir report Generate a CSV report on the known & unknown ROM files found in the input directo
ries (requires --dat)
Input options (supports globbing):
-i, --input Path(s) to ROM files or archives [array] [required]
-I, --input-exclude Path(s) to ROM files or archives to exclude from processing [array]
-p, --patch Path(s) to ROM patch files or archives (supported: .aps, .bps, .dps, .ebp,
.ips, .ips32, .ppf, .rup, .ups, .vcdiff, .xdelta) [array]
-P, --patch-exclude Path(s) to ROM patch files or archives to exclude from processing [array]
DAT input options:
-d, --dat Path(s) to DAT files or archives (supports globbing) [array]
--dat-exclude Path(s) to DAT files or archives to exclude from processing (supports
globbing) [array]
--dat-regex Regular expression of DAT names to process [string]
--dat-regex-exclude Regular expression of DAT names to exclude from processing [string]
DAT output options:
--fixdat Generate a fixdat of any missing games for every DAT processed (requires --dat)
[boolean]
ROM output options:
-o, --output Path to the ROM output directory (supports replaceable symbols, see be
low) [string]
--dir-mirror Use the input subdirectory structure for the output directory[boolean]
-D, --dir-dat-name Use the DAT name as the output subdirectory [boolean]
--dir-letter Append the first letter of the ROM name as an output subdirectory
[boolean]
-O, --overwrite Overwrite any files in the output directory [boolean]
--overwrite-invalid Overwrite files in the output directory that are the wrong filesize, c
hecksum, or zip contents [boolean]
-C, --clean-exclude Path(s) to files to exclude from cleaning (supports globbing) [array]
ROM zip command options:
-Z, --zip-exclude Glob pattern of files to exclude from zipping [string]
--zip-dat-name Group all ROMs from the same DAT into the same zip archive, if not excluded
from zipping (enforces --dat-threads 1) [boolean]
ROM symlink command options:
--symlink-relative Create symlinks as relative to the target path, as opposed to absolute
[boolean]
ROM header options:
--header Glob pattern of files to force header processing for [string]
-H, --remove-headers Remove known headers from ROMs, optionally limited to a list of comma-sep
arated file extensions (supported: .a78, .fds, .lnx, .nes, .smc) [string]
ROM filtering options:
-x, --filter-regex Regular expression of game names to filter to [string]
-X, --filter-regex-exclude Regular expression of game names to exclude [string]
-L, --language-filter List of comma-separated languages to filter to (supported: DA, DE,
EL, EN, ES, FI, FR, IT, JA, KO, NL, NO, PT, RU, SV, ZH) [string]
-R, --region-filter List of comma-separated regions to filter to (supported: ARG, ASI,
AUS, BRA, CAN, CHN, DAN, EUR, FRA, FYN, GER, GRE, HK, HOL, ITA, JPN
, KOR, MEX, NOR, NZ, POR, RUS, SPA, SWE, TAI, UK, UNK, USA, WORLD)
[string]
--only-bios Filter to only BIOS files [boolean]
--no-bios Filter out BIOS files [boolean]
--no-unlicensed Filter out unlicensed ROMs [boolean]
--only-retail Filter to only retail releases, enabling all the following options
[boolean]
--no-demo Filter out demo ROMs [boolean]
--no-beta Filter out beta ROMs [boolean]
--no-sample Filter out sample ROMs [boolean]
--no-prototype Filter out prototype ROMs [boolean]
--no-test-roms Filter out test ROMs [boolean]
--no-aftermarket Filter out aftermarket ROMs [boolean]
--no-homebrew Filter out homebrew ROMs [boolean]
--no-unverified Filter out un-verified ROMs [boolean]
--no-bad Filter out bad ROM dumps [boolean]
One game, one ROM (1G1R) options:
-s, --single Output only a single game per parent (1G1R) (required for all opti
ons below, requires --dat with parent/clone information) [boolean]
--prefer-verified Prefer verified ROM dumps over unverified [boolean]
--prefer-good Prefer good ROM dumps over bad [boolean]
-l, --prefer-language List of comma-separated languages in priority order (supported: DA
, DE, EL, EN, ES, FI, FR, IT, JA, KO, NL, NO, PT, RU, SV, ZH)
[string]
-r, --prefer-region List of comma-separated regions in priority order (supported: ARG,
ASI, AUS, BRA, CAN, CHN, DAN, EUR, FRA, FYN, GER, GRE, HK, HOL, I
TA, JPN, KOR, MEX, NOR, NZ, POR, RUS, SPA, SWE, TAI, UK, UNK, USA,
WORLD) [string]
--prefer-revision-newer Prefer newer ROM revisions over older [boolean]
--prefer-revision-older Prefer older ROM revisions over newer [boolean]
--prefer-retail Prefer retail releases (see --only-retail) [boolean]
--prefer-parent Prefer parent ROMs over clones [boolean]
Report options:
--report-output Report output location (formatted with moment.js)
[string] [default: "./igir_%YYYY-%MM-%DDT%HH:%mm:%ss.csv"]
Help & debug options:
--dat-threads Number of DATs to process in parallel [number] [default: 3]
-v, --verbose Enable verbose logging, can specify up to three times (-vvv) [count]
-h, --help Show help [boolean]
-------------------------------------------------------------------------------------------------
Advanced usage:
Tokens that are replaced when generating the output (--output) path of a ROM:
{datName} The name of the DAT that contains the ROM (e.g. "Nintendo - Game Boy")
{datReleaseRegion} The region of the ROM release (e.g. "USA"), each ROM can have multiple
{datReleaseLanguage} The language of the ROM release (e.g. "En"), each ROM can have multiple
{inputDirname} The input ROM's dirname
{outputBasename} Equivalent to "{outputName}.{outputExt}"
{outputName} The output ROM's filename without extension
{outputExt} The output ROM's extension
{pocket} The ROM's core-specific /Assets/* directory for the Analogue Pocket (e.g. "gb")
{mister} The ROM's core-specific /games/* directory for the MiSTer FPGA (e.g. "Gameboy")
{onion} The ROM's emulator-specific /Roms/* directory for OnionOS/GarlicOS (e.g. "GB")
Example use cases:
Merge new ROMs into an existing ROM collection and generate a report:
igir copy report --dat *.dat --input **/*.zip --input ROMs/ --output ROMs/
Generate a report on an existing ROM collection, without copying or moving ROMs (read only):
igir report --dat *.dat --input ROMs/
Organize and zip an existing ROM collection:
igir move zip --dat *.dat --input ROMs/ --output ROMs/
Produce a 1G1R set per console, preferring English ROMs from USA>WORLD>EUR>JPN:
igir copy --dat *.dat --input **/*.zip --output 1G1R/ --dir-dat-name --single --prefer-langua
ge EN --prefer-region USA,WORLD,EUR,JPN
Copy all Mario, Metroid, and Zelda games to one directory:
igir copy --input ROMs/ --output Nintendo/ --filter-regex "/(Mario|Metroid|Zelda)/i"
Copy all BIOS files into one directory, extracting if necessary:
igir copy extract --dat *.dat --input **/*.zip --output BIOS/ --only-bios
Create patched copies of ROMs in an existing collection, not overwriting existing files:
igir copy extract --input ROMs/ --patch Patches/ --output ROMs/
Copy ROMs to an Analogue Pocket and test they were written correctly:
igir copy extract test --dat *.dat --input ROMs/ --output /Assets/{pocket}/common/ --dir-lett
erFeedback is a gift! Your feature requests and bug reports help improve the project for everyone. Feel free to submit an issue on GitHub using one of the templates.
Even better, if you feel comfortable writing code, please feel free to submit a pull request against the project!
