OhMyGOG

OhMyGOG is a local maintenance dashboard for a personal GOG archive. It imports an OhMyGOG/RomVault DAT, scans the local archive read-only, compares expected files to observed files, and serves a localhost dashboard.

The archive path R:\RomRoot\Non-DatVault\gog-games.com is treated as read-only. Generated databases, caches, reports, and DAT exports live under this workspace.

First Commands

python -m unittest discover -v
python -m ohmygog.cli init-db --db data/gog_catalog.sqlite3
python -m ohmygog.cli import-dat --dat OhMyGOG.dat --db data/gog_catalog.sqlite3

Local Workflow

Import the current DAT as the trusted expected-file catalog:

python -m ohmygog.cli import-dat --dat OhMyGOG.dat --db data/gog_catalog.sqlite3

Scan the archive without hashing:

python -m ohmygog.cli scan --archive "R:\RomRoot\Non-DatVault\gog-games.com" --db data/gog_catalog.sqlite3

This records file names, sizes, mtimes, and nanosecond mtimes. Rows from this scan are reported as present_unverified when expected files are present by name and size but have not been checked against DAT CRC/MD5/SHA1 values.

To verify DAT hashes, run a hash scan:

python -m ohmygog.cli scan --archive "R:\RomRoot\Non-DatVault\gog-games.com" --db data/gog_catalog.sqlite3 --hash

Only rows whose expected files are present and whose CRC/MD5/SHA1 values match are reported as complete. Hashing the whole archive can take a long time on the first pass. Later hash scans reuse prior CRC/MD5/SHA1 values when folder, relative path, size, and nanosecond mtime are unchanged.

Hash scans use two workers by default. For the CLI, set --hash-workers N. For the dashboard, set OHMYGOG_HASH_WORKERS=N before starting the server. Use a small value such as 2 for HDD/network storage and a larger value only when the backing storage can keep up.

Scan only the first few folders while testing:

python -m ohmygog.cli scan --archive "R:\RomRoot\Non-DatVault\gog-games.com" --db data/gog_catalog.sqlite3 --limit 25

Export a generated DAT:

python -m ohmygog.cli export-dat --db data/gog_catalog.sqlite3 --out data/exports/OhMyGOG.generated.dat

Start the local dashboard:

python -m ohmygog.cli serve --db data/gog_catalog.sqlite3 --host 127.0.0.1 --port 8765

Then open http://127.0.0.1:8765/.

The dashboard is public/read-only until you log in as the single admin. Admin login is required for maintenance tasks, product links/merges, version equivalence approvals, and review decisions. Override the built-in local admin with OHMYGOG_ADMIN_USER, OHMYGOG_ADMIN_PASSWORD, and OHMYGOG_ADMIN_SESSION_SECRET before starting the server if you host it beyond your own machine.

The dashboard has actions for the normal maintenance loop:

• Refresh GOGDB caches the latest GOGDB product backup under data/cache/, imports the full GOGDB product list, matches DAT slugs to GOGDB product IDs, imports GOGDB download file parts where GOGDB exposes them, and marks games Outdated when the latest public Windows build version is newer than the version parsed from scanned local files. The DAT is not used as a fallback for update status.
• Scan File List rereads the archive folder/file names and sizes without hashing.
• Verify Hashes rereads the archive, reuses unchanged hashes, skips unchanged unverified files already seen by Scan File List, and computes CRC/MD5/SHA1 only for changed/new files in parallel.
• Verify Current Filter hashes only the local folders in the current dashboard search/status filter. Use it from an Outdated or Needs Hash Check view to avoid rescanning unrelated folders.
• Resolve GOG Metadata uses authenticated GOG downlink metadata to resolve final installer/bonus filenames and GOG checksum XML for GOGDB download parts. It records filename, MD5, total size, timestamp, and chunk MD5 ranges without downloading game files.
• Export DAT writes data/exports/OhMyGOG.generated.dat.
• Export Missing/Outdated List refreshes GOGDB first, then writes data/exports/OhMyGOG.missing-outdated.csv and a formatted data/exports/OhMyGOG.missing-outdated.xlsx workbook with the files needed for missing folders/products, missing installer parts/extras, and outdated local versions. It uses the current local scan data and does not hash or rescan the archive.

Use the Show Outdated button or the status filter to see every game currently flagged as outdated.

Use Show GOGDB Missing Locally to see likely standalone GOGDB products that do not match any scanned local folder, even when they were never in the seed DAT. Obvious demos, collections, packs, special editions, DLCs, soundtracks, artbooks, and digital goodies are kept out of that list and appear under Supplemental Review instead.

DLCs, soundtracks, and other goodies that GOGDB links to a base game through requires or dlcs are treated as merged into the base game's local folder. Their expected GOG files count on the base game detail page, and those child products are not listed as missing locally when the base product is matched. For pack-style products such as deluxe editions where GOGDB does not expose a hard parent link, the Review page shows Product Merge Suggestions; approving one stores a manual product merge and then checks that product's files inside the base game folder too.

Large result sets are paginated in the dashboard. Use Export Current CSV to download the current search/status filter as a worklist.

Use Export Missing/Outdated List when you want a shareable request list for other people. Its CSV columns are reason, title, dat_game_name, gogdb_product_id, local_version, gogdb_latest_version, gogdb_build_id, file_name, size_bytes, file_type, expected_source, and notes. The workbook has a summary sheet and a filterable Files sheet so spreadsheet apps do not need to guess the CSV delimiter.

Long-running dashboard actions show progress and auto-refresh while running. Other maintenance actions are locked until the current action finishes.

The Review page is the admin workbench. It groups product match suggestions, unknown local folders, unresolved GOG metadata, missing GOGDB products, version equivalence candidates, supplemental product review, and same-size GOG/local filename differences. From there you can link an unknown local folder to a GOGDB product or approve product merge suggestions.

Needs Hash Check / DAT Hash Check are DAT-driven integrity signals. They are separate from the GOGDB update comparison.

Missing-file checks prefer GOGDB download file parts when a matched GOGDB product exposes current downloads. When GOGDB does not expose download parts for a product, the dashboard falls back to the imported maintained DAT/hash-list rows. GOGDB download rows include part IDs, sizes, language, OS, and version, but not final installer filenames or CRC/MD5/SHA1 hashes.

To resolve final GOG metadata, set GOG_COOKIE / OHMYGOG_GOG_COOKIE to an authenticated GOG cookie header, or put that header in data/cache/gog_cookie.txt. Netscape-format cookie exports are also accepted. Use Resolve GOG Metadata on a game detail page to resolve just that game's matched GOGDB product rows, including merged DLC/goodie products. The global dashboard/review action resolves rows for products visible in the signed-in GOG account and processes 250 GOG download rows per run by default; set OHMYGOG_FILENAME_RESOLVE_LIMIT=0 before starting the server to resolve every owned unresolved row in one run. The same resolver is available from the CLI as python -m ohmygog.cli resolve-gog-metadata --db data/gog_catalog.sqlite3.

Safety

The scanner reads folder names, file names, sizes, mtimes, and optional CRC/MD5/SHA1 hashes. It does not write sidecar files, markers, reports, or any other state into the archive path. SQLite databases, caches, and exports are written under data/ in this workspace.

data/ is ignored by git. The seed OhMyGOG.dat remains a local input file unless you explicitly decide to version it.