Repository navigation
Rename Workflow
Renaming is intentionally separate from auditing. MiSTer_Audit.sh only proposes changes; MiSTer_Audit.sh v1.4 is the mutation path.
Before Preview or Apply, the updater reads [AUDIT_METADATA] from /media/fat/GameLibraryAudit/MiSTer_Library_Audit.txt and validates that the proposals came from a compatible, trustworthy audit.
The updater requires the expected v1.4 audit contract, including:
- audit schema version
4; - exporter version
1.4; -
self_check=PASS; -
metadata_layer=MiSTer-aware; - a recognized integrity verdict and Apply recommendation; and
- the audit's exporter and hash-database SHA-1 fingerprints.
It compares the recorded exporter fingerprint with the currently installed MiSTer_Audit.sh and the recorded database fingerprint with the currently installed mister_hash_database.tsv. If either changed after the audit was generated, the old proposals are considered stale and a fresh audit is required.
Preview may still be useful when the audit reports warnings, but Apply is blocked unless the audit has integrity_verdict=PASS and an Apply recommendation that permits proceeding. DO NOT APPLY is enforced by the updater rather than being only a manual warning.
Preview validates the audit handshake and rebuilds a plan from proposed_renames.csv and, when present, proposed_save_renames.csv. It writes:
/media/fat/GameLibraryAudit/apply_preview.tsv/media/fat/GameLibraryAudit/apply_skipped.tsv
Candidates are skipped when the source is outside the expected games/saves root, the proposed filename is unsafe, the source is missing, the target already exists, or multiple proposals resolve to the same target. CUE game renames are disabled.
Apply runs Preview again, requires a fully passing audit, and revalidates the audit handshake immediately before file mutation. If safe candidates exist, the user must type APPLY exactly.
Only after those checks does the updater rename files with mv. Each result is recorded in a timestamped manifest under:
/media/fat/GameLibraryAudit/RenameHistory/
The latest manifest is copied to last_manifest.tsv for rollback.
This second validation means a script or database change between Preview and Apply cannot silently authorize stale proposals.
Rollback remains intentionally independent of the current audit handshake so recovery stays available even if the auditor or database has changed since Apply.
Rollback requires typing ROLLBACK exactly. Successful entries from the last manifest are processed in reverse order. A file is restored only when the renamed source exists and the original target path is free.
The auditor and updater are both v1.4. The previous v1.1/v1.2 mismatch has been resolved: Apply now consumes and enforces the auditor's v1.4 integrity metadata instead of relying on it only as a manual review gate.
After Apply or Rollback, rerun the auditor to verify the library state.
Authoritative DAT-identified special releases use curated_destination during Preview/Apply. Retail/Standard games remain in their current system parent folder. Homebrew, Unlicensed, Aftermarket, Prototype, Beta, Demo/Sample, Translation, and Hack/Modified games move into the matching category subfolder. Paired saves mirror that category beneath their existing save-system folder. Missing category directories are created only during Apply after the normal audit handshake and explicit APPLY confirmation. Existing targets, duplicate targets, collision-blocked rows, unsafe paths, and CUE/BIN restrictions are still skipped.
For DAT-identified USA Retail/Standard ROMs, Apply keeps the ROM in the parent system folder and removes the redundant (USA), (US), or (U) region marker from the filename. Meaningful canonical qualifiers such as (Rev 1) remain so distinct retail variants do not collapse together. Non-retail ROM types remain in their shared category subfolders and retain canonical identifying markers such as (Unl), (Proto), and other release-specific qualifiers.
Apply accepts PASS WITH WARNINGS + SAFE TO PREVIEW (COLLISIONS SKIPPED) only when the integrity notes are collision-only. The blocking collision rows remain excluded from the mutation plan; non-collision warnings still block Apply.
Rows whose resolved region is Unknown are routed to <System>/!Unknown Region. Apply creates the directory when necessary. This keeps uncertain-region ROMs out of the clean system parent while preserving the rule that USA Retail/Standard stays in the parent folder.
Curated subfolders use a leading ! (for example !Prototype, !Unlicensed, and !Unknown Region) so they sort ahead of normal ROM entries in MiSTer file lists.
Authoritative DAT region metadata controls ordinary Retail/Standard placement. USA retail remains in the clean system parent. Japan, Europe, World, Canada, Australia, Korea, and Brazil retail releases move to matching !<Region> folders; other known regions use !Other Regions. ROMs without an authoritative DAT match remain in !Unknown Region until identification improves. Special release categories take precedence, so a Japanese prototype remains in !Prototype rather than !Japan.
Only hash/DAT-eligible ROMs participate in !Unknown Region routing. Unsupported inventory, documentation, disc media, and machine/support files stay in place without a regional rename. Unmatched eligible ROMs keep their exact current filename until a DAT match provides authoritative identity.
Support/documentation rows collected during classification are retained in support_files.csv; report setup does not overwrite them.
No-Intro-identified Virtual Console variants are not treated as original-system Retail/Standard copies. They retain the canonical Virtual Console qualifier and use <System>/!Virtual Console/. Because release type takes precedence over geography, a USA Virtual Console build is kept out of the clean USA retail parent directory.