Skip to content

Writing ROM Reports

Overview

When using DATs (the --dat <path> option), the igir report command can report on:

  • FOUND: what ROMs were found, and where their files are on disk
  • IGNORED: what ROMs were ignored (due to --single 1G1R rules)
  • MISSING: what ROMs were wanted, but weren't found
  • DUPLICATE: what input files did match to a ROM but weren't used when writing
  • UNUSED: what input files didn't match to any ROM
  • DELETED: 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 for more information about DATs.

The igir report command can be specified on its own without any writing command (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:

> igir.exe report --dat *.dat --input ROMs\

> dir /b *.csv
igir_2023-03-29T18;26;00-04;00.csv

$ igir report --dat *.dat --input ROMs/

$ ls *.csv
igir_2023-03-29T18;26;00-04;00.csv

$ igir report --dat *.dat --input ROMs/

$ ls *.csv
igir_2023-03-29T18;26;00-04;00.csv

See the igir --help message for the report's default location.

Format & filtering

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, 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."

Output location

The --report-output <path> option is provided to configure where the igir report CSV is written. See the igir --help message for the report's default location.

The report output filename supports a version of Moment.js symbols for date and time. To make it clearer what is a replaceable symbol, % is prepended to symbols. This is non-standard for Moment.js, but the % format should feel more familiar to more people as it resembles Python's date.strftime(), PHP's strftime(), C++'s strftime(), and more.

Info

See the Moment.js docs for a complete list of tokens you can use.

Warning

The % character is used to denote replaceable variable names (such as %USERPROFILE% and %TEMP%) in Windows Batch scripting. You may need to "escape" % characters with a ^ if you experience problems. Example:

--report-output ^%X.csv

Here are some example usages:

> igir.exe report --dat *.dat --input ROMs\ --report-output ".\report.csv"

> igir.exe report --dat *.dat --input ROMs\ --report-output ".\report %dddd, %MMMM %Do %YYYY, %h:%mm:%ss %a.csv"
REM ./report Friday, April 14th 2023, 4:28:26 pm.csv

> igir.exe report --dat *.dat --input ROMs\ --report-output "igir\%X.csv"
REM /igir/1681515048.csv

$ igir report --dat *.dat --input ROMs/ --report-output "./report.csv"

$ igir report --dat *.dat --input ROMs/ --report-output "./report %dddd, %MMMM %Do %YYYY, %h:%mm:%ss %a.csv"
# ./report Friday, April 14th 2023, 4:28:26 pm.csv

$ igir report --dat *.dat --input ROMs/ --report-output "igir\%X.csv"
# /igir/1681515048.csv

$ igir report --dat *.dat --input ROMs/ --report-output "./report.csv"

$ igir report --dat *.dat --input ROMs/ --report-output "./report %dddd, %MMMM %Do %YYYY, %h:%mm:%ss %a.csv"
# ./report Friday, April 14th 2023, 4:28:26 pm.csv

$ igir report --dat *.dat --input ROMs/ --report-output "igir/%X.csv"
# /igir/1681515048.csv