Files and sidecars

Reveal’s rule is that the folder on disk is the truth. Your photos, and everything you decide about them, are files you can see and read without Reveal. What the app keeps for itself is a speed layer, and it can be thrown away.

At a glance

What	Where	Is it yours?
The original	Where it is: a card’s copy in your archive, or the folder you added	Yours. Never rewritten.
IMG.RAF.xmp	Beside the original	Yours: rating, caption, tags, development
IMG.preview.jpg	Beside the original	A developed copy, 2048 pixels. Derived: it can be made again.
IMG.jpg	Beside the original	Made when you publish a story, if there wasn’t one
<folder>.md	In the folder	Yours: the story
reveal.md	At the root of a catalogue	Yours: the catalogue’s notes
The index	In Reveal’s data folder	Reveal’s. Disposable.
Caches	In Reveal’s cache folder	Reveal’s. Disposable.

Originals

Reveal does not change the content of your originals, whether it imported them or you pointed it at a folder. An import copies from the card through a temporary file and leaves the card alone. It goes into a library you already have, and never creates one: if the import folder is not inside a library, Reveal says so and imports nothing; filing follows your date pattern (by default Year/Year-Month-Day, set in Settings), and original names are kept.

It does move files when you ask. Dragging a photo to another folder in the sidebar, or renaming or moving a folder, moves them on disk. A photo travels with its .xmp sidecar and its IMG.jpg, so the frame stays whole. It refuses to overwrite: if the destination already has a file of that name, or a sidecar of that name, the photo stays where it was. If the sidecar cannot follow the photo, the photo goes back, so its decisions are never left behind. Renaming or moving a folder that is, or holds, a library keeps the library: it follows the folder, with its ratings. A library cannot be moved inside another one. The .preview.jpg is not moved with it: it is a derived copy.

Reveal never deletes a photo. Removing a library from the sidebar only makes Reveal forget it.

Sidecars

The sidecar is the small file that holds your decisions: IMG.RAF.xmp for IMG.RAF. It is standard XMP, so other software reads it. It carries:

• the rating (xmp:Rating),
• the caption (dc:description) and the tags (dc:subject),
• Reveal’s own development: the engine and its settings (reveal:DevelopEngine, reveal:EngineSettings), kept as one JSON block.

The format is standard XMP, and the name, IMG.RAF.xmp, is the one darktable, digiKam and Immich use, so those programs see the rating, caption and tags. They do not understand the development block, which is Reveal’s. (Lightroom and Camera Raw name their sidecars IMG.xmp, without the .RAF, so they do not look at this file.)

The sidecar is shared ground, and Reveal treats it that way. It owns exactly five properties in it (the rating, the caption, the tags, and its own two development properties). When it saves, it replaces those and carries everything else through untouched: the develop history another program keeps in the same file (darktable’s, for example), its own properties, comments. Grade a photo in darktable and rate it in Reveal, and neither program loses the other’s work.

The rating, caption and tags are shared in both directions: Reveal reads what is there and writes the list back as you edit it, so a keyword added elsewhere appears in Reveal as a tag.

Two small caveats. The whitespace between the attributes of the main rdf:Description tag is tidied, though their values are not changed. And if the file Reveal finds is not usable XML, it does not guess: it sets the original aside as IMG.RAF.xmp.bak and writes a fresh sidecar.

A sidecar is written safely, through a temporary file, so an interrupted save never leaves a half-written one.

Previews

IMG.preview.jpg sits beside the original: the photo developed with its recipe, at 2048 pixels on the long edge. The grid, the single-photo view and the Garden’s publish step all read it, and so can other tools, since it doubles as a web-ready export of the photo as it currently looks.

If the camera shot a JPEG next to the RAW, Reveal may use that JPEG for what it shows, since it is the camera’s own rendering of the frame.

When you publish a story, a photo without an IMG.jpg gets one, made from its developed preview. See Publishing to the Garden.

Tidy folder

Right-clicking any folder in the sidebar offers Tidy folder…, a window that shows what filing that folder’s photos by your import rule (Year/Year-Month-Day by default) would do, and lets you apply it once you have read the plan.

• Preview first, then Apply: The window opens as a plan and moves nothing. Apply asks for one more click, then moves the photos and their companions; nothing is moved before that, and no file is ever overwritten or deleted.
• Photos recognized: Primary camera RAWs and standalone JPEGs/HEIC/TIFF files with valid EXIF capture dates are detected and mapped to their capture day. If a RAW has a companion JPEG with the same name, the JPEG travels as a companion rather than a separate photo.
• Companion files stay united: A photo never travels alone. Its sidecar (.xmp), camera renders (.jpg), Live Photo video clips (.mov, .mp4, .m4v), and voice memos (.wav) travel together. If any companion encounters a naming conflict at the destination, the entire photo stays put. If a move fails part way, what already moved is put back, so a photo is never separated from its sidecar.
• Respects human choices: Photos inside folders a person specifically named with an event or description (such as 190305 - Kenya or 2024-05-12 - Portraits) are kept untouched.
• Collision and safety guards: Files without trusted EXIF capture dates (e.g. only system file modification time) and files with future timestamps (camera clock errors) are set aside. Any filename clash with an existing file or another photo in the plan stops the move.

Notes

• Stories are <folder>/<folder name>.md; see Stories.
• The catalogue note is reveal.md at the root of each catalogue: the free-form notes you write in the sidebar’s Library section.
• Exports go where you tell them, by default the Desktop; see Export.

The index

Reveal keeps a small database of every photo it has seen, so that big folders open at once and counts are instant. It lives in ~/Library/Application Support/co.utopie.reveal/ as index-rs.sqlite. It is a mirror of what is on disk: ratings, for instance, are read from the sidecars. It also remembers which folders you added as catalogues. Delete it and Reveal starts empty: add your folders again and it rebuilds the rest from the files. You lose time and that list, not your photos or your decisions.

The same folder holds your preferences (prefs.json), your saved presets and your LUT files.

The caches

Under ~/Library/Caches/co.utopie.reveal/, Reveal keeps developed copies so that a photo you have seen shows again immediately, even from a slow network drive. This cache is trimmed on its own and held to about 4 GiB, with the oldest copies going first.

If you use the Apple Photos library, its working copies are cached too. Settings → Libraries shows their size, lets you set a limit, and has Clear cached copies. Clearing is safe: edits, ratings and captions are kept elsewhere, and only the downloaded copies go.

Small things you may notice

• To learn whether a folder can be written to, Reveal briefly creates a hidden file named .reveal-write-probe-… and deletes it at once.
• macOS makes ._name files on some drives; Reveal ignores them.

What is safe to delete

Delete	What happens
IMG.preview.jpg	A derived copy; Reveal can make it again
The index	Reveal forgets your catalogues; add them again and it rebuilds from the files
The caches	Refilled as you browse
A story’s <folder>.md	The story is gone; the photos are untouched
IMG.RAF.xmp	The rating, caption, tags and development of that photo are gone
The original	Gone. Reveal keeps no other copy.