Skip to content

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 (see the guiding principles). 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 ROM writing commands. Only one ROM writing command can be specified at a time, and all require at least one --input <path|glob> and a --output <path>.

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 filenames change in DATs.

Note

The igir move command will only delete the source file in the input directory if it's safe to do so. This includes:

  • igir move newly writes a file in the output directory.
  • igir move test newly writes a file in the output directory, and the file is validated successfully.
  • igir move --overwrite overwrites an existing file in the output directory.
  • igir move --overwrite-invalid successfully validates an existing file; or it overwrites an existing file in the output directory.

Note

Input files that need to be moved to multiple locations in the output directory (because of multiple DATs, output tokens, or any other reason) will be duplicated as needed.

Create a link in the output directory to a ROM in the input directory.

Three different types of links can be created:

Link mode Description What happens when the source file is deleted
Hard link

--link-mode hardlink (default)		 The link file and source file are the exact same file on disk. If either file is changed, then all other hard linked files will also reflect those changes.

Supported by most filesystems other than FAT, FAT16, FAT32, and exFAT.		 ✅ The linked file isn't changed in any way.
Symbolic link ("symlink")

--link-mode symlink		 The link file is a shortcut to the source file. Symlinks generally require administrator privileges on Windows.

Supported by most filesystems other than FAT, FAT16, FAT32, and exFAT.		 ❌ The linked file's shortcut is broken, which will cause issues with reading or writing.
Reflink (copy-on-write)

--link-mode reflink		 The link file and source file will be the same file on disk, until any data is changed in the linked file, at which point the source file is copied to the link location.

Supported by APFS (macOS) and some Linux filesystems.		 ✅ The linked file isn't changed in any way.

ROM extracting & zipping

Igir has two ROM archive commands. Archive commands require either the copy or move write command (above). Only one archive command can be specified at a time.

If no archive command is specified, then 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 in their original format.

See the archives page for more information on supported archive types.

extract

ROMs will be extracted from archives when they are being copied or moved. ROMs from the same game will be placed into a subdirectory together by default (see the --dir-game-subdir <mode> option).

Input ROMs that are not already archived will be copied as-is, as they have no need to be extracted.

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.

Note

Igir will make its best effort to find any already-valid .zip files in an input path and copy those as-is without re-zipping.

Any invalid .zip files (ones that would fail igir test), and any non-.zip files, will be re-zipped into a valid .zip file.

ROM verification

test

When provided with a ROM writing command (above), verify that each file was written correctly:

  • igir extract test tests that each ROM file written has the correct size and checksum.
  • igir zip test tests that the .zip file is a valid TorrentZip/RVZSTD archive, has all the correct archive entry sizes & checksums, and contains no excess entries.

When a ROM writing command is not provided, verify that each input file is valid.

DAT writing

dir2dat

Creates a DAT from scanned ROM files. See the dir2dat page for more information.

fixdat

Creates a DAT from missing ROM files. See the fixdat page for more information.

File manipulation

clean

Files in the output directory that do not match any ROM in any DAT will be deleted.

See the output cleaning page for more information.

Other files

report

A report will be generated of what input files were matched by what DAT, and what games in what DATs have missing ROMs.

See the reporting page for more information.

playlist

Create .m3u playlist files for multi-disc games. See the playlists page for more information.