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)
↔️ Build & re-build (un-merge, split, or merge) MAME ROM sets (see arcade 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
| $$ | $$| \ | $$ | $$ $$ https://igir.io/
| $$ | $$ \$$$$ | $$ | $$$$$$$\
_| $$_ | $$__| $$ _| $$_ | $$ | $$ v2.6.3
| $$ \ \$$ $$| $$ \| $$ | $$
\$$$$$$ \$$$$$$ \$$$$$$ \$$ \$$
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 link Create links 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 dir2dat Generate a DAT from all input files
igir fixdat Generate a fixdat of any missing games for every DAT pro
cessed (requires --dat)
igir clean Recycle unknown files in the output directory
igir report Generate a CSV report on the known & unknown ROM files f
ound in the input directories (requires --dat)
ROM input options:
-i, --input Path(s) to ROM files or archives (supports g
lobbing) [array] [required]
-I, --input-exclude Path(s) to ROM files or archives to exclude
from processing (supports globbing) [array]
--input-min-checksum The minimum checksum level to calculate and
use for matching
[choices: "CRC32", "MD5", "SHA1", "SHA256"] [default: "CRC32"]
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 (suppo
rts globbing) [array]
--dat-name-regex Regular expression of DAT names t
o process [string]
--dat-name-regex-exclude Regular expression of DAT names t
o exclude from processing[string]
--dat-description-regex Regular expression of DAT descrip
tions to process [string]
--dat-description-regex-exclude Regular expression of DAT descrip
tions to exclude from processing
[string]
--dat-combine Combine every game from every fou
nd & filtered DAT into one DAT
[boolean]
--dat-ignore-parent-clone Ignore any parent/clone informati
on found in DATs [boolean]
Patch input options:
-p, --patch Path(s) to ROM patch files or archives (supports
globbing) (supported: .aps, .bps, .dps, .ebp, .ip
s, .ips32, .ppf, .rup, .ups, .vcdiff, .xdelta)
[array]
-P, --patch-exclude Path(s) to ROM patch files or archives to exclude
from processing (supports globbing) [array]
ROM output options (processed in order):
-o, --output Path to the ROM output directory (supports
replaceable symbols, see below) [string]
--dir-mirror Use the input subdirectory structure for th
e output directory [boolean]
-D, --dir-dat-name Use the DAT name as the output subdirectory
[boolean]
--dir-dat-description Use the DAT description as the output subdi
rectory [boolean]
--dir-letter Group games in an output subdirectory by th
e first --dir-letter-count letters in their
name [boolean]
--dir-letter-count How many game name letters to use for the s
ubdirectory name [number] [default: 1]
--dir-letter-limit Limit the number of games in letter subdire
ctories, splitting into multiple subdirecto
ries if necessary [number]
--dir-letter-group Group letter subdirectories into ranges, co
mbining multiple letters together (requires
--dir-letter-limit) [boolean]
--dir-game-subdir Append the name of the game as an output su
bdirectory depending on its ROMs
[choices: "never", "multiple", "always"] [default: "multiple"]
-O, --overwrite Overwrite any files in the output directory
[boolean]
--overwrite-invalid Overwrite files in the output directory tha
t are the wrong filesize, checksum, or zip
contents [boolean]
-C, --clean-exclude Path(s) to files to exclude from cleaning (
supports globbing) [array]
--clean-dry-run Don't clean any files and instead only prin
t what files would be cleaned [boolean]
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 link command options:
--symlink Creates symbolic links instead of hard links
[boolean]
--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 limit
ed to a list of comma-separated file extensions
(supported: .a78, .fds, .lnx, .nes, .smc)
[string]
ROM set options:
--merge-roms ROM merge/split mode (requires DATs with
parent/clone information)
[choices: "fullnonmerged", "nonmerged", "split", "merged"] [default: "
fullnonmerged"]
--allow-incomplete-sets Allow writing games that don't have all o
f their ROMs [boolean]
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 exclud
e [string]
-L, --filter-language List of comma-separated languages to filte
r to (supported: DA, DE, EL, EN, ES, FI, F
R, IT, JA, KO, NL, NO, PT, RU, SV, ZH)
[string]
-R, --filter-region List of comma-separated regions to filter
to (supported: ARG, ASI, AUS, BEL, BRA, CA
N, 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]
--no-bios Filter out BIOS files, opposite of --only-
bios [boolean]
--no-device Filter out MAME devies, opposite of --only
-device [boolean]
--no-unlicensed Filter out unlicensed ROMs, opposite of --
only-unlicensed [boolean]
--only-retail Filter to only retail releases, enabling a
ll the following "no" options [boolean]
--no-debug Filter out debug ROMs, opposite of --only-
debug [boolean]
--no-demo Filter out demo ROMs, opposite of --only-d
emo [boolean]
--no-beta Filter out beta ROMs, opposite of --only-b
eta [boolean]
--no-sample Filter out sample ROMs, opposite of --only
-sample [boolean]
--no-prototype Filter out prototype ROMs, opposite of --o
nly-prototype [boolean]
--no-program Filter out program application ROMs, oppos
ite of --only-program [boolean]
--no-aftermarket Filter out aftermarket ROMs, opposite of -
-only-aftermarket [boolean]
--no-homebrew Filter out homebrew ROMs, opposite of --on
ly-homebrew [boolean]
--no-unverified Filter out unverified ROMs, opposite of --
only-unverified [boolean]
--no-bad Filter out bad ROM dumps, opposite of --on
ly-bad [boolean]
One game, one ROM (1G1R) options:
-s, --single Output only a single game per parent (1G1
R) (required for all options below, requi
res DATs with parent/clone information)
[boolean]
--prefer-game-regex Regular expression of game names to prefe
r [string]
--prefer-rom-regex Regular expression of ROM filenames to pr
efer [string]
--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 prio
rity 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 priori
ty order (supported: ARG, ASI, AUS, BEL,
BRA, CAN, CHN, DAN, EUR, FRA, FYN, GER, G
RE, HK, HOL, ITA, JPN, KOR, MEX, NOR, NZ,
POR, RUS, SPA, SWE, TAI, UK, UNK, USA, W
ORLD) [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-ntsc Prefer NTSC ROMs over others [boolean]
--prefer-pal Prefer PAL ROMs over others [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]
--reader-threads Maximum number of ROMs to read in parallel per d
isk [number] [default: 8]
--writer-threads Maximum number of ROMs to write in parallel
[number] [default: 4]
--write-retry Number of additional retries to attempt when wri
ting a file has failed (0 disables retries)
[number] [default: 2]
--disable-cache Disable the file and archive entry checksum cach
e [boolean]
-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. "N
intendo - Game Boy")
{datDescription} The description of the DAT that contains the ROM
{gameRegion} The region of the ROM release (e.g. "USA"), each R
OM can have multiple
{gameLanguage} The language of the ROM release (e.g. "En"), each
ROM can have multiple
{gameType} The type of the game (e.g. "Retail", "Demo", "Prot
otype")
{inputDirname} The input file's dirname
{outputBasename} Equivalent to "{outputName}.{outputExt}"
{outputName} The output file's filename without extension
{outputExt} The output file's extension
{adam} The ROM's emulator-specific /ROMS/* directory for the 'A
dam' image (e.g. "GB")
{batocera} The ROM's emulator-specific /roms/* directory for Batoce
ra (e.g. "gb")
{es} The ROM's emulator-specific /roms/* directory for the 'E
mulationStation' image (e.g. "gb")
{funkeyos} The ROM's emulator-specific /* directory for FunKey OS (
e.g. "Game Boy")
{jelos} The ROM's emulator-specific /roms/* directory for JELOS
(e.g. "gb")
{minui} The ROM's emulator-specific /Roms/* directory for MinUI
(e.g. "Game Boy (GB)")
{mister} The ROM's core-specific /games/* directory for the MiSTe
r FPGA (e.g. "Gameboy")
{miyoocfw} The ROM's emulator-specific /roms/* directory for MiyooC
FW (e.g. "GB")
{onion} The ROM's emulator-specific /Roms/* directory for OnionO
S/GarlicOS (e.g. "GB")
{pocket} The ROM's core-specific /Assets/* directory for the Anal
ogue Pocket (e.g. "gb")
{retrodeck} The ROM's emulator-specific /roms/* directory for the 'R
etroDECK' image (e.g. "gb")
{romm} The ROM's manager-specific /roms/* directory for 'RomM'
(e.g. "gb")
{twmenu} The ROM's emulator-specific /roms/* directory for TWiLig
htMenu++ on the DSi/3DS (e.g. "gb")
Example use cases:
Merge new ROMs into an existing ROM collection and delete any unrecogn
ized files:
igir copy clean --dat "*.dat" --input New-ROMs/ --input ROMs/ --outp
ut ROMs/
Organize and zip an existing ROM collection:
igir move zip --dat "*.dat" --input ROMs/ --output ROMs/
Generate a report on an existing ROM collection, without copying or mo
ving ROMs (read only):
igir report --dat "*.dat" --input 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-language 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|M
etroid|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 overwriti
ng existing files:
igir copy extract --input ROMs/ --patch Patches/ --output ROMs/
Re-build a MAME ROM set for a specific version of MAME:
igir copy zip --dat "MAME 0.258.dat" --input MAME/ --output MAME-0.2
58/ --merge-roms split
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-letterFeedback 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! Please see the full contribution guidelines for rules to follow.
