The TrueArchive handbook.

Installation

You need a Mac with macOS 15 or later. A single package is intended for Intel and Apple Silicon. Check the release notes for your version’s testing status.

Download the current alpha from the website and install it as follows:

1. Finish any running imports. Close the older TrueArchive app before updating.
2. Extract the downloaded app package. Move TrueArchive.app to the Applications folder.
3. Open the app. On first launch, the normal interface opens with guidance on connecting sources and an archive.

No signup is needed for the alpha. Share your feedback after trying it.

Read the Release Notes for your app package. You will also find a link to the matching checksum there.

Shared preview: Starting with 0.39, enable “Receive verified preview versions” under App Updates on both Macs to receive the same centrally verified package. Without this option you receive released versions. The installed version and build number appear alongside the setting. Turning previews off does not downgrade the app. An offline Mac updates after reconnecting and once archive work is safely idle.

App updates

From version 0.6.0, automatic app updates are enabled by default. TrueArchive checks roughly once a day while the app is running and the Mac is awake. A new, verified package is installed when idle; the app then restarts.

Updates wait during checking, importing, pauses or keyword tagging. An unfinished setup or open import preview also prevents an automatic restart. This includes a retained preview in a source section that is currently collapsed. No new archive jobs start during an update.

Under TrueArchive → Settings → App updates you can turn off automatic updates. “Check for updates now” remains available for manual updates. You can also use the TrueArchive menu; “App updates …” in the menu bar window opens the setting.

The app’s update mode control is locked during an update. Selecting automatic updates in the update dialog applies to future updates; it does not cancel an update that has already been prepared. If the connection fails or installation encounters an error, you can check again later.

Optional Local Metadata Index

Optional in Alpha 0.38.0. Open TrueArchive → Settings → Performance and enable “Use Local Metadata Index”. The option is off by default and applies to verified XMP associations from all sources on this Mac.

During archiving, TrueArchive remembers derived metadata on the Mac. Subsequent checks can interpret the same XMP associations faster, including after restarting the app. Complete XMPs are still read and changes checked. Downloads, copying and full original verification remain necessary; the benefit depends on the archive and operation.

The index contains no images. Its database is limited to 64 MiB and 25,000 entries. Originals and XMPs in the archive remain authoritative. If the index cannot be used, normal verification continues. “Clear Local Index” removes it; while enabled, it rebuilds during the next check. Disabling the option retains existing cache files but stops using them.

Direct archive import: While enabled, TrueArchive also remembers an archive's inventory (derived XMP details per file, at most 1 GiB and 1,000,000 entries). The first preview still reads the destination archive completely. Afterwards only files whose file identity, size or modification times differ are read again; all folders and files are still listed and checked, and duplicates are still detected by checksum across the whole archive. Without a valid inventory, TrueArchive reads everything as before.

Changing and clearing the index are disabled during archive work. It is local to each macOS user, is not synced between Macs, and is not part of the archive or its backup.

Choose language

Under TrueArchive → Settings → General → Sprache / Language choose System, Deutsch or English. With “System”, TrueArchive uses the first supported language in your preferred system languages. If neither German nor English is listed, it uses English. Your explicit choice stays saved on this Mac.

Navigation, settings and the last all-source sync summary change immediately. Existing individual error messages keep their language until the next action. System dialog controls and update dialogs use the language selected by macOS. Changing language does not restart ongoing archive work. Your source names, filenames, paths and archived metadata remain unchanged. The automatic keyword language has its own selection in each source’s settings (in archive settings through 0.17.3); imported metadata is not translated.

The website initially follows your preferred browser languages, with English as the fallback. Use DE / ENG at the bottom of any page to switch. Your choice stays saved if the browser permits it. The language links also work without JavaScript. Use the browser language automatically again.

Your first archive

1. Connect an archive. At “Archive destination” at the top, choose a new empty archive folder, your existing TrueArchive archive or directly use an existing picture folder. The destination requires APFS or HFS+.
2. Add a source. Use “Add source” to connect Apple Photos, an SD card, an external drive, local picture folders, a Google Takeout export or an Immich account. Connection and settings open in the same workspace.
3. Review the scope and start. Check the source folder and subfolder option, or the capture date range. “Archive” next to a local source or Apple Photos starts directly; “Archive all connected” starts the combined run. For Immich, select and check the uploads you want first.

Short hints in the workspace show what is still missing. Once at least one source is connected and the archive has been checked, TrueArchive remembers the setup. Completing setup does not start an import. Sources, the archive and an optional Photos capture date range stay saved on this Mac. Enable schedules and automatic keywords separately.

Use an existing picture folder as the archive

1. Choose the archive folder. Open “Archive → Overview” and select your existing folder on a supported APFS or HFS+ drive. That exact folder becomes the archive.
2. Import new pictures. Start a sync for the selected source or all connected sources. New media and their XMP files are placed under year → month → day.

Connecting preserves existing media and XMP files in place. It neither reads all pictures nor adds missing XMP files throughout the old collection. TrueArchive creates only its small control files in the hidden .bildarchiv folder; no additional database or persistent verification cache is needed.

What does an import compare? TrueArchive checks the relevant destination folders and protects existing files from overwrites. Previously associated files there can be recognized. Pictures with different names, locations or changed capture dates may be copied again, including pictures previously archived with TrueArchive. Unclear metadata associations are not resolved by overwriting them.

For a comparison of the entire collection, deliberately start “Check duplicates” later. This separate check can take longer and is not a prerequisite for importing. Connecting a folder does not prove that all previously stored files are complete or undamaged.

If 0.17.0 already started registration: Previously added XMP files remain. A provable pending write is first completed safely, then the folder can be used directly. The remaining collection is not automatically registered. Ambiguous or damaged transaction evidence is preserved and must be resolved.

Other interrupted imports: TrueArchive shows the pending operation. The required evidence is checked only when you start recovery. For older archive formats, this explicit check may cover the entire collection and take longer. Files are not changed without valid evidence.

File packages stay closed during connection and ordinary imports. Photo libraries, applications and other Finder packages remain unchanged. A package itself cannot be the archive destination. Existing folders are not automatically reorganized.

Four areas for your archive

The sidebar keeps four areas within reach: Overview, Sources, Archive and Backup. The archive name identifies the destination you are working with. Settings and help stay at the bottom of the sidebar.

• Overview: See current activity, archive availability and the last completed backup. Compact source rows open the relevant source directly.
• Sources: Add connections, select media and archive them. Each source shows its own connection status and last sync.
• Archive: Overview contains the connection and Finder actions; Maintenance contains archive tools; On devices contains Apple Photos previews and Immich integration.
• Backup: Progress, older snapshots, recovery and connection settings. A Hetzner destination or a configured Hetzner travel connection also offers Travel transfer.

Within a source, Preview, Result, Connection, Date range, Schedule, Free up space and Keywords are directly accessible tabs. The pastel background and source name identify your current context. Switching sources keeps the selected tab; the X returns to the source list.

“Archive” starts a configured and available local source or Apple Photos. It replaces that source’s open preview; other sources keep their selections and reports. Immich first opens its explicit upload selection. If a prerequisite is missing, the source shows the required next step.

The fixed bottom bar keeps activity and the queue accessible. “View operation” opens the appropriate details, including during a backup. Pausing the queue prevents subsequent starts; stopping the active operation is a separate action. Queue additional sources.

Confirm a date range in its own tab with “Apply date range”. Changes remain protected while archive work is running; results, help and current progress remain accessible.

Start and end dates for each source

Open a source and choose the “Date range” tab. “Apply date range” saves it for this source, including after restarting the app.

• “From” only: Include recordings from that day onward, including matching items added later. There is no end date.
• “To” only: Include recordings up to and including the entire end day, with no start boundary.
• Both boundaries: Include only the chosen range. Both calendar days are included in full.
• “All items”: No date filter. An end date before the start cannot be saved.

The saved range applies to previews, individual and combined imports, existing schedules and the review of the same configured drive. A start date alone does not create a schedule; enable one separately if needed. Google Takeout and Immich remain manual.

Local sources use embedded camera metadata, falling back to the file modification or creation date. Takeout uses the capture date in Google metadata, falling back to embedded camera metadata. Apple Photos and Immich use the recording’s capture date. Known instants use the saved timezone; camera clocks without a timezone keep their calendar day. Unassignable dates are excluded while filtering. The preview reports skipped files as information, not import failures.

Changing the range clears the old preview or Immich selection. While a changed draft is open, that source’s starts and combined runs wait; other sources remain available individually. Existing archive files are preserved. A matching Live Photo includes all of its associated components.

Connection symbols and text explain the last checked state. Green means reachable, or full access for Apple Photos. It does not confirm a complete import or the availability of every iCloud original. Missing permissions, disconnected drives and unresolved issues have specific guidance.

The fixed work display names the operation, source actually being processed and trigger, such as “Manual” or “Automatic”. Known counts and progress appear with the supported pause and cancel actions. You can view results while work continues and queue additional local sources for later; this does not change the running job or its settings. After a specific confirmation, running keyword analysis can be interrupted for a requested archive action.

“Recent results” opens the sources’ last reports from this app session. Successes and unresolved items appear together: “80 archived · 2 open” is a partial success. Expand issues to find the appropriate recheck, setting or support report. A new attempt replaces that source’s report; there is no persistent result history after restarting the app yet.

Use Archive → Overview to choose or reconnect the archive folder. “Change archive …” or “Choose archive folder …” opens the file picker. You can create a new folder there and confirm with “Use as archive”. The chosen folder itself becomes the archive; the destination requires APFS or HFS+. Maintenance contains duplicate checks, location suggestions and other archive tools. Recovery required after interrupted archive work stays visible at the archive.

Finder actions open the actual archive or local source folder. Eligible external volumes also offer Eject, both at sources and at the archive destination. Safely disconnect drives. App settings, help and support are available through the labelled actions and the macOS menu.

Changing the archive invalidates existing previews. If you change “Include subfolders” for a source, check that source again; a different source’s selection remains. You also create a fresh preview after restarting the app.

Archive all connected

When idle, “Archive all connected” starts a manual combined run with one click: configured local sources in their listed order, including Takeout, followed by Apple Photos. Each folder uses its subfolder option; Apple Photos uses the confirmed capture date range. Without a date filter, all accessible items are synced.

Immich stays separate: The round result marks these accounts as “selection required”. Choose “Select …” at the intended Immich source to check its uploads and then archive them. The combined button does not import a previously prepared Immich selection either.

The source list shows the active source and the sources that follow. Double clicks do not create a second combined run. You can queue additional local sources as separate one-time jobs for later; this does not change the running combined run’s order or settings. Each source’s result opens directly at its row. New and existing content, supplemented metadata, variants and unresolved cases stay together. Missing sources are skipped with a reason; other sources can continue. The run stops if the archive is unsafe or the setup changes.

Pause local work with “Pause” and continue it with “Resume”. “Cancel sync” ends the entire run; later sources will not start. Apple Photos supports cancellation but does not yet support pausing. Files already archived are kept and recognized on the next run.

Your schedules and their global pause remain unchanged. Apple Photos must already have full access. Running archive work and app updates prevent a second simultaneous run.

Quick actions in the menu bar

Click the TrueArchive drive in the macOS menu bar. The compact window shows the same archive destination and, directly below it, the same automation state as the main window. “Open” brings the existing app window to the front.

When idle, it offers “Archive all connected” and up to three eligible local sources or Apple Photos with “Archive”. Their order matches the workspace. “More sources …” opens that list in the main window. For Immich, “Select …” opens the relevant selection directly.

During an operation, its controls replace quick starts. The source, trigger and known progress match the main window. Apple Photos and Immich support cancellation but not pausing. A pause is confirmed only when the worker has paused; cancellation remains in progress until it has actually stopped.

“View result …” opens an unresolved source report in the right place. If the archive is missing, “Archive & maintenance …” opens its connection controls. Settings, Finder and support remain accessible. Quitting waits for active work to stop safely. Opening the menu starts no sync and changes no scheduled time.

Free up space on a source

Open “Free up space” directly at a source. Archiving continues to read from the source. This separate, optional operation may permanently delete already archived source files after your confirmation. The archive copies remain.

Remove large videos from Apple Photos

Open “Free up space” at your Apple Photos source and load the video overview. It includes accessible videos in this account regardless of the import date range. Known sizes appear largest first; unknown sizes and an incomplete overview are explicitly marked.

1. Watch and compare: Check name, capture date, size and archive status. “Play” loads a temporary playback copy from Photos if needed, which may download it from iCloud. A video that has not been fully archived cannot be selected for deletion.
2. Measure missing sizes: This explicit action reads the video resources and may download them from iCloud. It shows progress and can be cancelled. The resource total does not measure your iCloud storage usage.
3. Check archive copies: Choose up to 20 videos per operation. This initial check does not delete anything. TrueArchive compares current originals, edited versions and associated data with the connected archive. An earlier successful import alone is insufficient. If anything is missing or changed, archive the video again and reload the overview.
4. Confirm deletion: Confirm the exact selection. For a paired account, the person in that macOS account must also approve the request in TrueArchive Photos Access. macOS may then show an additional Photos confirmation. Nothing is deleted without the required approval.

This feature never deletes videos automatically. A separate second backup of the archive is sensible but is not required for this manual selection. After cancellation or an uncertain result, deletion is not retried automatically; check the actual state in Photos first.

Set up local cards and drives

Defaults for local sources: keep at least 20% free, oldest captures first, a second backup required and favorites protected.

Supported sources are local SD cards, external drives and explicitly selected media folders. Source and archive must be on verified independent physical devices; a different partition on the same drive is not enough. The required second backup must also be independent. Archive and backup folders, as well as overlapping sources, are excluded.

Immich, Google Takeout and Lightroom exports show an explanation in this tab. No source files are deleted there. Network folders, cloud sync folders, photo libraries and managed Immich folders are also excluded.

1. Choose “Keep at least this much free”: 20, 40, 60 or 80 %, or a custom value from 5 to 90 %. Free space is measured for the entire drive. Only eligible files within the configured source scope may be removed.
2. Choose the order: “Oldest captures” keeps newer captures for as long as possible; “Largest captures” frees space by removing fewer captures; “Oldest videos” leaves photos on the source. If there are not enough videos, the target remains unmet.
3. Under “What is preserved?”, requiring a second backup and protecting favorites are enabled by default. Turning off the second backup requires a separate confirmation: the archive may then be the only remaining copy.
4. If write access is missing, choose “Allow access…” and select exactly the same source folder again. “Connect archive”, “Set up second backup …” or “Back up now” lead to the required action when a prerequisite is missing.

Check and confirm what to free

“Check what can be freed” deletes nothing. Each bounded preview shows up to 128 capture groups with their associated files, date and estimated size. You can deselect groups. This selection applies only to manual removal. An already queued automatic operation waits while this preview is open. After you close it or switch tabs, the confirmed rules may also remove deselected captures. The red button states the estimated amount; the following specific confirmation authorizes permanent removal. For larger sources, further sections can be checked afterwards.

Before removal, the current original bytes, their source association, and all required metadata and companion files are verified in the archive. If a second backup is required, those exact current files are checked in a confirmed backup snapshot. A green import status or a previously successful backup alone is insufficient. Unclear groups, unknown companions and incompletely preserved metadata remain on the source; a RAW with an unresolved Nitro companion is not partially removed.

Captures without a reliable date and new or changed files remain protected; both the capture and its last modification must be at least 24 hours old. With favorite protection enabled, five-star captures and favorites are also preserved. Videos without a fully readable record of their ratings remain protected too. In this version, that includes MOV and MP4 videos because their embedded ratings cannot yet be checked completely. Choosing “Oldest videos” with the default favorite protection therefore cannot free space from these videos yet. If too few groups qualify, the view explains the unmet target and protection reasons. File size is an estimate; actual free space is measured again.

Automatic freeing, stopping and interruption

“Automatically free up space” first presents the specific rule for confirmation. Enabling it does not delete anything. The rule applies only after a future fully or partially successful import from this source. Cancelled imports, starting the app and simply connecting a drive do not trigger removal. If the second backup is missing, an already queued operation waits for a matching backup to finish; “Back up now” starts that backup explicitly. The import can end normally.

Later runs with the same confirmed rule do not ask again. Changing the target, order, protection rules or bound source, archive or backup connections revokes activation. Another Mac requires a new confirmation. Turning the option off prevents future operations. During a run, the tab shows its phase and progress; “Stop” waits for the current file to finish safely.

Freeing space does not use the Trash. Some source files may already be gone after cancellation; their verified archive copies remain. After an interrupted operation, explicitly choose “Resolve interrupted operation”. Remaining files are returned without overwriting anything. This does not resume deletion: a new check and confirmation are then required. The last completed result remains under “Last space freed”. To restore files, use the archive or the second backup.

Edit in Nitro, keep in the archive, view in Immich

Nitro creates the edit. TrueArchive preserves originals, finished versions and XMP. Immich displays the connected collection. Follow one example picture through the whole workflow:

1. Finish the edit in Nitro: Keep the RAW and Nitro XMP together. Also export a JPEG or HEIC with the finished appearance, for example to Apple Photos. The XMP recipe alone does not apply the edit in Immich.
2. Archive both paths: Import the SD card with its RAW and XMP, and sync Apple Photos separately. The finished version may arrive first. Check completion for both sources; similar names or the same subject do not automatically link RAW and JPEG.
3. Check the example: Inspect its description, tags and stars. “Day unknown” is not an exact capture date. While TrueArchive is writing, avoid editing the same XMP files in another application.
4. View in Immich: Connect the archive read-only in the correct account’s external library. After scanning, check the picture and its search results. “Scan requested” does not confirm completed metadata processing. Do not upload the archive files again to make them appear.
5. Optionally add a heart for five stars: Enable the star rule and start “Back up now”. It applies only to exactly five standard XMP stars on the verified archive file in its bound owner account. A heart on the RAW does not carry over to a separate JPEG. Lower ratings never remove a heart; with five stars still present, a manually removed heart can return.
6. Complete the second backup: Wait for a confirmed backup snapshot. A successful import, a picture visible in Immich and an accessible backup destination are separate results.

Enabling the star rule alone does not start a round. For regular rounds, also enable “Automatically back up Immich changes”. Supported Immich changes can be saved in XMP; this does not provide general automatic synchronisation of every XMP field in both directions.

Recover a file or an earlier edit

1. Choose the time: Select a confirmed snapshot under Second backup. On a new Mac, the backup destination, backup password and, for Hetzner, storage credentials are sufficient; the old archive drive is not needed. Unconfirmed snapshots are only for explicitly chosen file rescue with unknown completeness.
2. Select media and XMP: For one picture, select both files, such as Example.ARW and Example.ARW.xmp, or their containing folder. Include a finished JPEG/HEIC separately if needed: it remains its own media file.
3. Restore separately: Use a separate empty destination folder, then check the file, metadata and edit there. Do not overwrite the existing archive in Finder. A recovered selection is not a fully restored archive.
4. Try it in Nitro: Open copies of the RAW and XMP in a test folder. Nitro expects different sidecar names depending on format, so do not rename sidecars across the archive. Compare the recipe, crop and appearance; after saving again, also check third-party tags, regions and extra metadata.
5. Restore Immich organisation if needed: Make the pictures available in the correct external library first, then deliberately choose “Restore in Immich…” for the supported information you want. Restoring files alone does not restore the Immich database, people or sharing links.

Verification limit: TrueArchive does not render the Nitro recipe. A complete open-and-save roundtrip in Nitro remains unverified. Automatically selecting media with its XMP is part of the proposed new backup dialog; always check that both files are selected before starting.

Second backup and restore

Since Alpha 0.28.0: “Backup” provides an encrypted backup on a separate physical drive. Snapshots also preserve earlier file versions.

1. Choose Set up second backup … and an empty folder on a different APFS/HFS+ drive. Two volumes on the same physical drive are not an independent backup.
2. Choose a password with at least twelve characters and store it safely outside this Mac. TrueArchive also saves a copy in the local keychain. The encrypted backup cannot be recovered without its password.
3. Choose Back up now. Selecting the folder alone does not start a backup. TrueArchive checks the archive, saves its files and confirms the completed snapshot.

If backup is blocked, the overview names the specific reason and at most the matching next action. Wait while an archive check is running. For a missing archive drive choose Connect archive, for a safely recoverable import choose Continue import, and for a mismatched backup choose Check backup assignment. Back up now appears only after the archive and backup assignment have been verified.

All regular archive files are included, including unassigned media and foreign XMP sidecars. Repair interrupted archive operations first. Unknown administrative files, links, package folders or nested mounted volumes prevent a confirmed completion. Close other metadata editors and older TrueArchive versions during backup. This is not an atomic filesystem snapshot.

Imports, keywords, Immich work, updates, ejection and quitting respect the shared operation lock. A requested import can stop the backup; the import begins after the backup process has fully ended. Previous confirmed snapshots are preserved. Old snapshots are not deleted automatically.

Keychain permission: Access that is already allowed continues without an extra explanation. If macOS needs permission, TrueArchive first shows the selected action and Continue to Keychain. macOS may ask for the login keychain password, usually your Mac login password; enter it only in the system dialog. With Hetzner, the backup password and Storage Box credentials may require separate permissions. Credentials read with one-time permission are used for that action. Denying access does not trigger an automatic permission retry; choose the intended action again. Background access opens no permission dialog. Before changed credentials are saved, TrueArchive also explains the Keychain purpose. macOS manages lasting permissions and may ask again after app changes.

Set Up a Hetzner Storage Box

New in Alpha 0.38.0: Open Backup → Settings and choose Hetzner Storage Box. No terminal commands, personal keys or network-drive mounting are needed.

A Hetzner backup also remains blocked while the working archive is missing, an import needs to be continued, or the saved backup is assigned to another archive. Resolve the action shown in the app; merely checking the connection does not start a backup.

1. Create an Account and Order Storage

1. Open Hetzner Accounts and choose Register now. Add your contact and billing information, confirm your email and supply the requested payment details. Complete any identity verification directly with Hetzner. Optionally enable two-factor authentication. Official account guide.
2. Open a project in Hetzner Console, then choose Storage Boxes → Create Storage Box. Pick a location and capacity based on the space your archive uses, leaving room for new photos and older versions. Current capacities and prices.
3. Enable External Reachability. Set a dedicated Storage Box password and keep it in your password manager. Once provisioned, copy the username, such as u123456, or server address. Hetzner ordering guide.

Order a Storage Box. This connection is not for Cloud servers or Storage Share. TrueArchive does not need the extra “SSH Support” option; it uses the available file-transfer connection. Hetzner connections and settings.

2. Connect in TrueArchive

1. Choose Hetzner Storage Box, enter the username or server address and Storage Box Password. Check Connection verifies access. It does not create a backup.
2. Select New Backup. Choose a separate Backup Password of at least twelve characters, repeat it and confirm independent safekeeping. It encrypts photos and XMP files before upload. Neither the Hetzner account password nor the Box password replaces it.
3. Choose Set Up Hetzner Backup, then Back Up Now. The default backup name is TrueArchive. For separate archives, expand “Use a Different Backup Name” and keep that name with your password. There is currently one configured backup destination per archive; changing it does not delete earlier backups.

The login and backup password are saved in this Mac’s Keychain. Keep an independent copy of the backup password. Resetting a password at Hetzner cannot decrypt the backup. If this name already holds a backup, choose Existing Backup and supply its current password.

3. Daily Use and Recovery on a New Mac

The first upload can take a long time depending on archive size and upload speed. Later backups transfer new and changed data while preserving older snapshots. Wait for Backup completed in full. Cancelling leaves the previous confirmed snapshot usable. Enable the daily schedule explicitly when wanted: TrueArchive must be open, the Mac awake, the archive connected and internet available.

For recovery, choose Restore Archive from Backup… → Hetzner Storage Box, enter the Box login and backup password, then Open Hetzner Snapshots. Use the same backup name if previously changed. Select a date and restore into a new empty local folder. The original drive and old Mac’s preferences are not required. First check a small selection together with its XMP files.

After changing the Box password, open Settings… → Verify and Save Login. For connection failures, check internet access and External Reachability. An unverified server identity blocks the connection. Storage usage and billing remain visible in Hetzner Console.

Links and commission: Hetzner’s current FAQ says the referral programme has ended. These are direct provider links; TrueArchive currently receives no commission. Checked 16 September 2026.

From your trip to your home archive

Send home extends an existing Hetzner backup. There is no additional archive mode. Without Hetzner, this option stays hidden. The first workflow is designed for two Macs.

1. On your trip: Connect the travel archive and open its Hetzner backup. Expand Send home, set up the travel connection and export its connection file. This file contains connection details, but no passwords.
2. At home: Connect a different, independent home archive. In Hetzner setup, open the option to receive a travel connection on this Mac. Import the connection file and enter the Storage Box password and backup password. Keep the travel repository separate from the home archive’s own second backup.
3. Prepare reception: Select a dedicated empty inbox folder outside the home archive. It needs space for one complete backed-up travel snapshot; adjust the space limit as needed. Verify the connection and confirm reception into this home archive. The check uses an encrypted technical record, not a personal test photo.
4. Try it manually first: Send the current travel archive to Hetzner. On the home Mac, check reception and preview the planned import, then receive it. Originals remain unchanged and repeating an import does not create duplicate originals. Conflicting photo information can be compared and selected individually on the home Mac.

The overview distinguishes the travel archive, Hetzner and home archive. Only a verified home import produces an encrypted receipt for the travel Mac. An older receipt confirms only its specific snapshot; it cannot tell whether the home Mac is currently awake.

Expand setup and previous confirmations to enable sending after archiving on the travel Mac and automatic reception on the home Mac separately. Both start off. TrueArchive must be running, each Mac awake and its archive connected. The home Mac checks no more often than every 15 minutes; existing archive work takes priority. Changes made by other programs are checked again when you send manually.

Pause stops active work cleanly. Resume processes the same unchanged inbox again. Do not edit that inbox yourself: changed or unrelated files are preserved and prevent automatic cleanup. Only after confirmed import may TrueArchive replace its own unchanged temporary snapshot with the next delivery.

Finishing the trip on this Mac only ends its local automation. Do this separately on the other Mac. It deletes neither originals nor backup snapshots and never propagates deletions into the home archive. Background transfer on iPhone or iPad is not part of this Mac workflow.

Optional daily backup

A new schedule starts at its next selected time. If the Mac is off then, that first missed run is caught up at the next opportunity. Older saved schedules without a start time catch up once at the next opportunity.

In Settings …, select the hour and choose Enable schedule on this Mac. One Mac owns the schedule; explicitly enabling it on another Mac transfers responsibility. TrueArchive must be open, the Mac awake and both drives connected. One missed run is caught up, without running once for every missed day. Turn off leaves manual backups available.

Restore a snapshot or individual files

The Overview, Restore and Settings sections keep your input, selection and scroll position when switching. Previously loaded folders reappear immediately; the first folder level is prepared when opening the connection. Back to folder start returns to the first page. Before a restore, TrueArchive verifies the selected snapshot and files again.

Restore → Restore archive from backup … works without the original archive or the old Mac’s configuration. Open the backup folder, enter its password and select a date. The selected snapshot shows its full ID. Confirmed snapshots have an encrypted completion record. An unconfirmed rescue snapshot needs explicit consent; its completeness is not established.

Choose Restore entire snapshot … or select files and choose Restore selection …. Folders include all their contents. For individual images, the matching filename.extension.xmp is included; review the combined selection in the preview. Choose a new empty folder outside the original archive and backup repository. Files appear in its Archiv subfolder and are verified before completion. Further catalogue and file pages have direct buttons; the folder path and Up one level keep navigation visible.

Resume interrupted restore … accepts only the unchanged destination owned by that operation. An unconfirmed crash during transfer requires a new empty folder. Keep rescued files and the adjacent restore record together, and do not edit them before resuming.

A confirmed full restore of a supported format offers Use as archive. Original media, XMP bytes and logical identities are retained; only the physical root binding may change. Unknown archive/XMP versions remain available as a file rescue. Automatic tasks start paused when the restored archive is connected; review the result before allowing them again. Existing sources and date ranges stay configured.

Check a backup and recover without the app

Check structure checks the repository’s structure. Read and verify all backup data also reads every stored data block. A structure check alone does not replace this full check. Neither action deletes snapshots or unlocks the repository automatically.

Standard restic 0.18.1 can recover files with the password independently of the old keychain. List data snapshots with snapshots --json --tag truearchive-data-v1, choose the full data ID and restore ID:/ into a new empty destination with --verify. Avoid a moving latest reference, technical receipt/schedule snapshots and the working archive as a destination. Official instructions.

A direct restic restore copies the old marker without physically rebinding the archive. To connect it safely as a working archive, use the app’s restore workflow into another empty folder. Version details and verification limits.

View archive images on iPhone

“View your archive on iPhone” creates small views of selected archive images in Apple Photos. The only destination is the current macOS user’s System Photo Library. If iCloud Photos is enabled there, Apple handles syncing to your devices. TrueArchive confirms local creation, not completion in iCloud.

Connect the configured archive, enable Apple Photos as a source and allow full Photos access. Under Archive → On devices, choose “View your archive on iPhone”. Paired Photos access from other Mac users cannot be used as a write destination for this feature.

1. Select an archive range. Check archive searches the whole archive in small metadata batches. Narrow it with From/Through, a discovered year, or Only images without a capture date. Imprecise year and month values count when they overlap the range. The overview shows at most 100 examples but reports the full number of matching images. Select every possible preview in this range also includes matches not shown as examples. Existing Photos matches and TrueArchive previews are labelled. “Uncertain match – check manually” does not mean the image is missing from Photos. These images start unselected.
2. Storage required. Choose “Compact” with up to 2048 pixels or “More detail” with up to 3072 pixels. For a small individual selection, calculation creates and measures the actual previews. For a large range selection, TrueArchive uses a bounded sample from the whole range and explicitly labels the extrapolation as Estimated. The later transfer processes the range in batches of no more than 20 images. Changing selection or size recalculates it. It uses HEIC when available, otherwise JPEG, with SDR output in sRGB.
3. Add and check the result. Check the Photos destination and storage amount. Confirm possible additional copies once for the selection and, if still required, that other TrueArchive apps writing to this archive have been updated. Only then does Add to Apple Photos … permit the transfer. The dedicated result step distinguishes confirmed additions from unresolved previews, cancellation and errors. Check the overview again before another attempt; stored receipts prevent a confirmed duplicate transfer. Images appear in the library and in the “TrueArchive – Archivvorschauen” album. There is no automatic preview schedule.

Which image is created?

For verified Photos groups, an available finished image is preferred. A standalone RAW uses a default rendering supported by the system, which may differ from the camera’s image. Nitro or other RAW editing instructions are not applied. Videos, Live Photo motion and editable recipes are not transferred. RAW/JPEG files with matching names are not treated as one item based on their names alone. Original media in the archive stays unchanged.

Storage and repeat attempts

The measured or explicitly estimated storage applies only to the selected previews and is not an iCloud allowance: Apple may need additional storage. Check available iCloud storage and sync status in Apple’s own settings. Previews replace neither originals nor a second backup. Uncertain matches cannot provide a general guarantee against duplicate photos.

“Stop” waits for any request already submitted to Apple. An uncertain outcome, an unavailable preview or an earlier Photos connection does not trigger another copy automatically. Use “Check transfer” for an unresolved earlier request. After reconnecting or switching Photos off and on, an old preview binding remains blocked for review. If only preparation had completed, prepare the preview again and confirm the selection again.

When subsequently archiving from Apple Photos, verified unchanged TrueArchive previews are skipped and counted separately. This count does not verify archived originals. Changed image data, edits, metadata or conflicting matches remain open for review; a filename alone is not evidence.

Add photos from another Mac user

From Alpha 0.32.0: Each Apple Account uses a separate Mac user with its own System Photo Library. TrueArchive collects their photos in one archive. The other user only needs the small TrueArchive Photos Access app.

1. Set up the other user once. Create a user in macOS Users & Groups. Sign in with the other Apple Account and configure the intended System Photo Library and, if wanted, iCloud Photos in Apple Photos. Skip this step if already done.
2. Start in your archive user. In TrueArchive, choose Add source → Apple Photos → Another Mac user’s photos. Select the person. TrueArchive suggests a source name and makes Photos Access directly launchable from Applications. If TrueArchive is still in Downloads, move it to Applications first; missing write permissions are reported explicitly.
3. Request a connection. The request stays open for up to ten minutes. No pairing code or Apple email address needs to be transferred.
4. Switch to the other Mac user. Use the user menu or “Switch User” on the lock screen, select the person and enter their Mac login password. Do not choose “Log Out”: your archive user must remain signed in. If the user menu is missing, search System Settings for “Fast User Switching” and enable it in the menu bar or Control Center.
5. Open the small app. Open TrueArchive Photos Access from Applications or Spotlight. If needed, choose Allow Photos access and grant full access. The request identifies the Mac user who wants to archive these photos. Confirm that specific connection with Allow access for [name]. No archive setup is required here.
6. Return and archive. Switch back to your archive user. TrueArchive automatically adds the approved source. Set the starting date under “Date range”, save and choose “Archive”. Preview, result and keyword settings belong to this source. Its schedule starts disabled.

Everyday use

Photos Access supplies originals in the background. Its window can be closed; the app must stay running. Start at login is optional. If the switch is disabled because it is unavailable for this installation, open Photos Access manually after each login for now. This occurred during the Build 96 startup test; automatic login startup remains unconfirmed for that installation. After restarting the Mac, both users must sign in once. The Mac must be awake to archive. TrueArchive does not enable automatic user login or wake the Mac.

The small app comes with TrueArchive. No separate download is needed. Its Applications entry opens the current Photos Access included with TrueArchive. Use App Updates when a new version is available; TrueArchive coordinates signed-in users. Quit Photos Access in other users yourself before manually replacing the app in Finder, or if TrueArchive explicitly identifies an older version that requires this. If a later release changes the small launcher itself, setup may ask you to move the previous entry in Finder and prepare it again. An existing different app is never overwritten.

When a connection is waiting

If the other user is signed out or their Photos Access is closed, those imports wait. Other reachable sources can continue. Grant missing Photos permission in the corresponding Mac user. Temporary Apple errors first call for another connection check, not a new source.

If the previous library can no longer be identified, explicit approval is required again. Unavailable change history can also cause this; the message alone does not prove that the library changed. Reapproval preserves the source name, date range, keyword settings and archived origins; enable its schedule again if needed.

Expired or cancelled requests are not silently approved again. Start a fresh request if needed. Existing code-based connections from 0.31.0 remain usable while their bindings are valid.

Cancellation and retries: Incomplete transfers are never confirmed as archived. Retries recognize existing originals; identical pictures from different accounts retain their origins. Apple Photos imports support cancellation, not pause. Removing a source deletes neither Photos items nor archive files. If its access app is offline during removal, also revoke the approvals in the other user.

Connection keys remain in each user's Keychain. Photos Access reads only the approved library; it does not write an archive or delete photos. Being signed in alone does not prove that every iCloud original is available.

Select uploads from Immich

1. Connect each account separately

1. Sign into the Immich account you want to use. Open the account settings through your profile and create a separate API key for TrueArchive. Each family account needs its own key; an administrator key does not replace the keys for other accounts. Immich’s API key guide.
2. Allow user.read, asset.read, asset.download, assetFile.read and assetFile.download. Optionally add asset.view for small image previews. No permission to write or delete assets is required.
3. In TrueArchive, choose Add source → Add Immich account. Enter a display name, the direct HTTPS server address, such as https://immich.example.com, and your key. Click “Check and save connection” and check the account displayed. The key is stored only in the macOS keychain.
4. Connect the actual archive destination at the top before checking a selection. Reconnect its drive if it is missing. This does not require a new inventory of the entire archive; a different folder cannot stand in for the missing archive.

Settings from 0.19.0: Once the app saves its local source configuration in the new format, those settings require at least 0.19.0. Older versions cannot open them. Archived media remain ordinary files.

Use the source’s gear button to replace the key with one for the same account. Leaving an optional key field empty keeps its saved key. “Remove from source list …” removes the connection and its saved keys after confirmation; uploads and archived files remain.

2. Select, check and archive

1. Choose “Select …” at the Immich source and click “Load uploads”. The list contains available uploads owned by this account. Assets belonging to other accounts, deleted or unavailable items and external library files are excluded. The eye button optionally loads a small image preview.
2. Select individual items or “Select this page”. The selection applies to the displayed page. “Not checked yet” means the archive comparison has not happened. Clear or archive your selection before opening “Next uploads”; there is no selection spanning all pages.
3. Click “Check selection”. TrueArchive temporarily downloads the selected originals and any available exportable XMP files to this Mac, with no more than two downloads at once. A Live Photo’s associated video is included. Keep enough free local storage available. The media has not yet been archived; this check determines its archive status.
4. Review destination paths and the labels “Already archived”, “Ready to archive” or “Conflict”. For conflicts, choose “Change selection”, adjust it and check again. Originals already in the archive may also be downloaded temporarily again for this comparison.
5. Choose “Archive now”. TrueArchive rechecks the account, unchanged selection and actual archive destination. If automatic keyword analysis is running or paused, you can confirm “Interrupt and archive”.
6. “Last archive operation” shows new and existing files, updated metadata and unresolved errors. Uploads remain in Immich. Load the next page afterwards and handle it as a separate selection.

Cancel and retry: “Cancel” waits for the active work to stop safely. Partially downloaded files are not published as completed archive files; verified imports remain. A new attempt downloads required originals again from the beginning, without resuming at the last downloaded byte. If TrueArchive requests recovery, complete it before starting another import.

3. Originals, metadata and limits

Original files are copied unchanged. Downloads are checked against Immich’s SHA-1 checksum; the archive also uses SHA-256. Available API metadata and exportable source XMP contribute to the shared XMP file, including capture date, description, rating, GPS and keywords where present and supported. Provenance records the server, account and asset, including the Live Photo relationship.

Metadata coverage remains partial. This is not a complete export of the Immich database or every possible XMP field. Existing XMP keeps unknown fields too; contradictory information appears as a conflict. Some unusable optional camera values may be omitted with a notice while the original and any source XMP are preserved. The upload import does not transfer albums or sharing settings automatically. Organization of the external archive copy can be backed up separately after Immich has indexed it. An external archive copy later read by Immich has its own Immich ID.

For archives created with the current app and directly used existing folders, duplicate searches compare the relevant destination folders for the capture date. Identical originals elsewhere or with a different capture date may be copied again. Older TrueArchive layouts are checked throughout their subfolders. Additional readiness or recovery checks may read other parts of the archive independently of the duplicate search and take longer.

Date precision and XMP compatibility

From Alpha 0.23.0: When XMP contains only a year and month, the preview shows a value such as “1984-03” and new local imports use 1984/1984-03/Tag unbekannt. A year without a month uses 1984/Monat unbekannt. A date filter covering only part of the possible capture period requires review.

Immich receives an explicitly labelled search placeholder: the 15th of the known month, or July 15 for year-only dates. XMP retains the original value and precision; descriptions and tags explain the placeholder. More precise or conflicting dates are not overwritten automatically. Existing files require a separate repair with rollback copies and are not moved by an update.

The shared tag view includes digiKam, Lightroom and flat keywords. Lightroom development recipes are preserved; the corresponding JPEG provides the finished Lightroom rendering. Once these metadata functions are enabled, the archive requires the new writer from 0.23.0 or later; older apps refuse further writes.

4. Optional: show the archive in Immich

First create an external library in Immich and give it read access to the actual archive. TrueArchive does not set up the server or its drive mounts. The archive path must be correct from inside the Immich container, such as /mnt/archive; a Mac drive path alone is not enough. Immich’s external library guide.

1. After saving the source, open its gear button and “Archive library in Immich (optional)”. Enter the library ID, archive path inside the container and a separate administrator API key with user.read, library.read and library.update. Choose “Check and save archive library”. This key manages the library; it does not import other accounts’ uploads.
2. After a selection has been archived successfully, choose “Refresh archive in Immich…”. TrueArchive shows any additional year folders needed for this import.
3. Check the paths and confirm “Add folders and start scan”. If no additional paths are needed, the action reads “Start library scan”. Existing import paths and exclusion rules are preserved. Viewing the proposal alone does not change the library.

“Library scan requested” confirms only the request. Immich processes it in the background; check the result there. Prepare another refresh for each additional archived selection. Importing from your own accounts and viewing the result on the iMac or in Immich still need separate confirmation.

5. Back up Immich organization in the archive

Alpha 0.26.0 / Build 50: The Immich source includes “Back up Immich organization”. Link an external archive library owned by this account to the current archive destination. Choose “Back up now” or enable “Back up Immich changes automatically”.

The account API key also needs asset.download for this backup. Before changing an XMP file, TrueArchive compares the local original with the unedited original from Immich. The data is streamed for verification without storing another copy. Unchanged rounds do not transfer originals again; verifying large videos before a change can take longer.

TrueArchive backs up favorites, owned albums, descriptions, tags and ratings for the exact archive file. A RAW file and its finished JPEG remain separate renditions. Removing a favorite or album membership is also recorded. Dates, GPS and other people’s shares are outside this first reverse direction.

Find albums: Organization backup adds owned albums as flat XMP keywords, such as Album: Summer 2026. The spelling stays the same in both languages. In titles, / becomes %2F, | becomes %7C, % becomes %25, and control characters become UTF-8 bytes written as %XX, preventing unintended hierarchies. Very long search keywords are shortened with a distinct checksum suffix; full album titles and identifiers remain backed up. Renaming or removing albums updates only TrueArchive’s additions, preserving identical existing manual tags. Restoration still creates real Immich albums; the search keywords are not restored as extra ordinary Immich tags. First update every Mac that writes to this archive to at least 0.28.0, supporting immich-album-keywords-v1.

Removed album search keywords stay removed even if Immich later returns them as ordinary tags. To deliberately reuse a former keyword as your own tag, choose a different name in Immich or add it manually to the archive XMP. Otherwise, TrueArchive cannot distinguish an identical new Immich tag from a delayed return of its earlier addition.

People and faces: Enable “Include people and face regions” and grant face.read to the account key. TrueArchive saves named, visible people and their face rectangles in the common XMP. Correct wrong assignments in Immich first. RAW and JPEG files keep their individual assignments; originals remain unchanged. Videos and images edited in Immich do not receive new face regions through this feature.

Name changes for known faces are saved. Previously saved faces remain in the archive when Immich stops returning them, hides them or removes them during a new recognition run. New face IDs may add regions. Other applications’ regions are preserved. Missing permissions or uncertain image dimensions appear under “Assets not fully backed up”; other valid organization values can still be saved.

Large libraries are checked in batches with progress and cancellation. After a complete round, automatic backup starts another round no sooner than five minutes later while the app and Mac are running and the archive is connected. Cancel pauses it until “Resume backup”, including across an app restart. The upload import’s date range does not limit this backup of the entire linked archive library.

Conflicting simultaneous edits show current and previously saved values. Choose “Keep archive value” or “Use Immich value” for each field, then “Save decision”. Use “Check values again” if they have since changed. Other files in the current round can continue to be backed up.

Restore: “Restore in Immich…” previews archive and Immich values for up to 20 existing assets per page. Select the desired assets and confirm “Restore selection in Immich”. Archive values replace their current Immich values, including actual owned albums and favorites. “Preview the next assets for restoration” continues through further pages. Ambiguous same-name albums are not merged. A partial failure keeps the XMP backup protected; preview again and explicitly resume. People and faces are not yet restored into Immich. Their XMP backup is preserved.

Backup additionally requires the account key’s permission to read owned albums. Restoration also needs write permissions for assets, owned albums and tag/album memberships. Another account’s administrator key cannot replace this key. Mount the archive read-only in Immich; TrueArchive writes the common XMP files locally on the Mac.

After the first backup, every Mac writing to this archive needs 0.25.0 or later. The new format guard prevents older TrueArchive versions from writing. After the first saved face region, every writing Mac needs at least 0.26.0. Preferences use schema 9. Original media remain unchanged and the backup lives in the common XMP without a second required database.

Face backup in 0.26.0 · Immich backup in 0.25.0 · Candidate 0.19.0 release notes · Help with problems

Import another TrueArchive archive

Under Archive → Maintenance → Import another TrueArchive archive, import an existing archive from a connected drive into the current destination archive. The source archive remains unchanged. The same entry is available under “Add source”.

1. Check the destination. Connect the archive that should receive the photos under Archive → Overview.
2. Choose source archive … Select the top-level folder of the other TrueArchive archive. The preview compares both archives and shows new files, updates, files already present and open items. Nothing is imported yet.
3. Review photo metadata. TrueArchive merges details that differ only in form (whitespace, list order, “default” language) and additional keywords by itself. The remaining conflicts are grouped by kind, each with a count and up to three examples. Choose “Keep destination archive” or “Use source archive” per kind – or “For all” at the top. The choice applies to every case of that kind, including those not shown. Under “Decide individually” you can set single cases differently as long as no bulk choice applies to their kind. Unsupported or incomplete items remain explicitly open.
4. Import reviewed files … Check the destination path and confirm with “Import now”. The result separately counts confirmed photos and open files.

If the source or destination has changed since the preview, choose “Check again”. A partial or stopped import also needs a new check; previously imported files are recognised. “Close import” only clears this working state.

Pausing and stopping keep access reserved until the worker has actually finished. Archives sharing the same archive identity – such as a backup copy of the same archive – cannot be combined using this workflow. Unmanaged files in an adopted collection are outside the import scope and counted separately. The import does not confirm an entire drive and does not replace an independent backup.

Review old drives

1. Choose a drive or photo folder. Open Archive → Maintenance → Import photos from another drive and choose Choose a drive or photo folder …. The same review path appears under “Add source” as “Review an old drive…” and directly in the row of a configured local source. Choosing a new folder starts the search; for a known source, choose “Find folders”.
2. Understand the scope. Completed folders show media count, size and path. “Show subfolders” splits a group into separately selectable areas. Incomplete or excluded areas do not count as fully examined.
3. View pictures. “View” opens three real previews within the app: the first, middle and last file in the sorted list. “Other random pictures” replaces the trio. “More previews” shows up to twelve pictures per page. Click a picture to enlarge it; “Only 3 previews” returns to the last trio. Finder opens only through its own labelled action.
4. Archive directly. “Archive” in a folder row imports that folder. With no checkmarks, the main action explicitly says “Archive all … folders”; with checkmarks it names the selected folder count. Checking boxes does not start work. The archive destination is shown alongside. “What's missing from the archive?” offers an optional comparison without writing anything.

Random samples repeat files only after a pass through the folder. With six or more files, every trio differs completely from the previous one; with four or five, some overlap is necessary. With three or fewer files, all are already visible. Sampling never changes checkmarks or import scope and is not evidence of archive coverage.

Comparison and import use the same media and XMP checks as local imports. Newly archived, already present, updated and pending files are counted separately. “Retry pending files only” retries the recorded pending files from the previous import. Results apply to that selection, not to the whole drive.

Extract ZIPs explicitly

“Extract ZIP…” first selects a destination outside the source and archive. TrueArchive shows the exact new folder; only “Extract” starts work. Existing folders are not overwritten, and the ZIP remains unchanged. Extracted files retain the modification date stored in the ZIP; as with local imports, this is the fallback when no capture date is available. After complete success, “Review extracted folder” opens a separate review. That new folder can be archived after disconnecting the old drive.

Damaged, encrypted or multipart ZIPs, symbolic links and duplicate paths are rejected. Nested containers are not automatically extracted. On cancellation, TrueArchive removes only its own verified work folder after processing ends. Any unremoved remnants are reported with their path for inspection in Finder.

Pauses and limits

Search, comparison, import and extraction can be paused or stopped. Ejection waits while a worker or preview is still reading a volume. Afterwards, eligible external volumes can be safely ejected. Use the archive destination's own Eject button for its volume.

Up to four recent reviews are kept locally as a rebuildable working state. Resuming checks the source identity and previously observed directories; changed areas need another scan. After a new scan, previously selected folders not yet found again are explicitly reported. A reviewed source gets no schedule and does not join the batch action for configured sources.

Search is limited to 100,000 media files, 50,000 folders and bounded path and notice lists. Choose a smaller source folder if a limit is reached. ZIP extraction is limited to 100,000 entries, 512 GiB, available storage and one hour of active processing. Previews hold no more than twelve pictures of up to 1024 pixels per page. Unsupported preview formats can be opened separately in Finder; they are not silently excluded from imports.

Hidden areas, system directories, photo libraries, other archives, packages, symbolic links and other volumes are listed as not examined. Capture dates are never invented from folder names. Review reads local sources without changing or deleting originals.

Import Lightroom exports

From Alpha 0.24.0: Connect a completed Lightroom export as its own source. Originals, videos and additional edited JPEGs are copied unchanged; existing XMP sidecars are preserved and extended.

1. Export from Lightroom. Export your selection as “Original” into a dedicated folder. Export any finished edits separately as full-size JPEGs, for example into an “Edited” subfolder. Include available metadata. Adobe export guide.
2. Keep XMP files beside their images. In Lightroom Classic, changes stored only in the catalog must first be saved or exported. TrueArchive does not read the Lightroom catalog. Adobe: save metadata.
3. Add source → Lightroom export. Choose the common export folder or multiple separate folders. Subfolders are included. Adding the source does not archive any files.
4. Adjust options in the source tabs. Change the capture date range, keywords or schedule if needed. Select “Archive” to start; a preview for selecting individual files is optional.

Recurring import: Continue exporting new files from Lightroom into the connected folders. The schedule checks these local folders, not Adobe’s cloud. Unchanged files are recognized. Finish exporting before archiving; inputs changed after a preview require a new check.

Import Google Photos from Takeout

Google Takeout is Google’s data export service. It gives you a copy of your photos and videos on your Mac. TrueArchive then imports the extracted folder into your archive.

Already received Google’s completion email? Start at 2. Download and extract.

1. Request an export from Google

1. Open Google Takeout with the account that holds your Google Photos collection.
2. Choose “Deselect all”, then select only “Google Photos”. For your first TrueArchive test, we recommend a small album: open the album selection under Google Photos and limit the export to it.
3. Continue to the next step. Choose an email download link, a one-time export and ZIP. We suggest 2 GB per file to start; the part size does not limit the number of selected photos.
4. Create the export. Wait for Google’s email and download before the deadline it gives. Google’s official instructions.

For later backups, see Import recurring Google exports.

2. Download and extract every part

1. Open the completion email. Follow the download link, sign in to Google again if asked, and finish downloading every ZIP part of this export.
2. Allow enough space. You need room for the ZIPs, the extracted files and the later archive copy. For large exports, use a folder on an external drive with enough free space. Keep the export folder outside your TrueArchive archive folder.
3. One ZIP file: Open its location in Finder and double-click it to extract it. The resulting folder usually contains Takeout with Google Photos or Google Fotos inside. TrueArchive needs the folder containing the extracted files, not the ZIP.
4. Several ZIP files: Create a common folder, such as Google-Export, with Part-1, Part-2 and so on inside it. Put exactly one ZIP from this export in each part folder and double-click it there to extract it. Keep the contained folders separate; do not overwrite files by merging them. After extraction, keep the ZIP files outside this common folder. Then select the Google-Export folder containing the extracted parts in TrueArchive.

3. Archive in TrueArchive

1. Check the destination. Your intended archive folder should appear under “Archive destination” at the top.
2. Connect the source. Choose + Add source → Google Photos (Takeout), then the extracted export folder. For several parts, select their common parent folder. Adding the source does not start an import.
3. Include subfolders. Open the gear beside the new source and leave “Include subfolders” enabled. This also applies to a single ZIP containing nested photo folders.
4. Start the import. Click “Archive” beside this source. A preview is optional if you want to check the selection and notices first.
5. Check the result. Open the result directly at the Google source. “Last sync” shows imported, existing and deferred files. Resolve open entries before treating the export as fully imported.

No photos found? Check that the selected folder contains extracted photos and that subfolders are included. Missing JSON files? First check that every ZIP part of the same export has finished downloading and extracting.

What happens to metadata

Which additional Google fields are not imported? TrueArchive cannot yet map information such as googlePhotosOrigin or additional fields within GPS data reliably. This does not automatically mean that pictures are missing. Supported capture dates, GPS, descriptions and proven album titles are still imported when present and valid. The limited metadata coverage remains recorded in the archive; the extra information stays in the export’s unchanged JSON files. Check the result separately for any files reported as deferred or failed.

Media and matching JSON files belong together. Supported sidecars use the full media filename followed by .json or .supplemental-metadata.json; the title inside the JSON must match the media filename exactly. Matching across parts must be unambiguous under Google Photos or Google Fotos. Shortened names, multiple matching files and damaged metadata are not guessed.

If a matching JSON file is missing, the media item is initially deferred. To explicitly accept that loss, enable “Import files even when Google metadata is missing” in the source settings and check again. The missing metadata remains permanently recorded in the archive. This option only permits missing sidecars; damaged, invalid or ambiguous JSON files remain blocked. Changing the option discards only this source’s preview.

After a mixed result, “Partially archived” keeps the successful counts visible. Expand the problems to see which files or changes were not imported. Use “Inspect source again” to prepare a new preview; it does not start an import. For Google Takeout, the report also links to “Choose export folder…” and “Import options…”.

Valid Google capture time, description and GPS data are added to the shared standard XMP. The supported capture time determines date folders according to the archive layout: year, month and day for new archives from 0.14.0; download and export times do not replace it. An album title established by supported album metadata becomes a readable keyword. A folder name alone is not enough. Favorites remain source information and are not converted into star ratings. Conflicts with existing XMP need to be resolved; local edits are not silently overwritten. Changes to the stored metadata coverage or favorite status are not automatically replaced by later exports either.

TrueArchive preserves the supplied media bytes and leaves the export source unchanged. JSON files are not additionally copied into the archive. Unsupported extra fields and album information stay in the export source. Google’s zero-coordinate placeholders do not become a capture location; verified capture times use UTC for archive placement. These general limitations do not produce a notice for every photo. Specific association and data errors remain visible in the report. An export does not prove original camera quality or completeness of your Google library; the provenance retains that limitation.

For a later export from the same source, open its gear → “Choose a new export folder …”. The saved source identifier is retained. TrueArchive checks the folder and possible overlaps before switching; this source’s preview is discarded and other previews are preserved. Removing the source and adding it again creates a new source instead.

Import recurring Google exports

1. Schedule with Google: Select only Google Photos in Google Takeout. Enable scheduled exports every two months for one year. For Google Photos, Google also offers exports of new and updated data. Official Google instructions.
2. Wait for the export email: Download every part of the new export before its deadline and extract it into a separate folder. Do not combine old and new exports by overwriting files.
3. Use the same source: In TrueArchive, open the gear next to your Google source and select “Choose a new export folder …”. Select the newly extracted export. Your saved source identifier is retained.
4. Archive now: Start the import for this source. Previously archived content is checked and recognized; conflicting metadata still needs a decision. Renew the export schedule with Google after one year.

What happens automatically? Google creates the scheduled exports. Downloading, extracting and starting the import remain manual steps; TrueArchive does not yet run an automatic Google sync. You do not need to remove and add the source again for a later export.

TrueArchive provides no Google sign-in, automatic download or schedule for Takeout. It reads only the local files you deliberately provide. Pause, cancel and the result report use the existing source controls.

Archive sources one after another

New in Alpha 0.38.0. “Archive now” on a local source creates a one-time job. During another import, the action becomes “Archive next”. If the source or archive is unavailable, “Archive now” is disabled. Use the separate “Queue for later” button to save a request explicitly. It waits until both source and archive are available; a paused queue must be resumed first. You can add and queue further local sources during a local or Apple Photos import. The running source’s settings remain protected.

The archive queue appears in the sources overview, showing the running import and queue positions. Clicking a queued source opens the list without creating a duplicate job. “Move up”, “Move down” and “Remove from queue” apply only to waiting jobs. Removing a job does not delete any media.

“Pause queue” prevents the next job from starting; a running import continues. Explicitly interrupting or cancelling an import also pauses the pending queue. Choose “Resume queue” to process available jobs again. The queue and its pause survive an app restart. An unexpectedly interrupted job is checked again; previously archived originals are recognised.

A disconnected card stays queued as “Waiting for the source”. Reconnect that exact source; other available sources can start first. For “Waiting for the archive”, “Check archive connection” opens the archive destination, where you can reconnect its drive. The app does not look for replacement folders.

A job remembers its source, date range, options and archive destination. If these settings change, it will not silently use different values. Review the source and deliberately choose “Queue again with current settings”. For failed or incomplete imports, review the source’s result and queue it again when ready. If the source has been removed, remove its old job and add the intended source again.

The queue is one-time. A schedule checks a source repeatedly; “Archive when connected” is also a separate option. Queuing does not enable or change these automations. Apple Photos and Immich keep their existing start actions.

Release Notes

For each version, we document new features, fixes, important update notes and known limitations. Earlier entries remain available so you can look up your installed version too.

Read all release notes

Find the version number in the app under TrueArchive → About TrueArchive. The handbook explains the current state; the version history shows when each feature became available.

Troubleshooting

View the activity log: From 0.27.1, Help → Show activity log… or the log icon at the bottom of the menu bar panel opens a separate window. It remains accessible during imports and backups. It shows starts, phases, counts, results and error categories, with new entries at the bottom. Automatic refresh runs every two seconds and can be disabled.

The window displays the latest 500 entries. “Copy” copies this view, “Open log file” opens the entire available history in the associated text application, and “Show in Finder” selects the file. Its location is ~/Library/Application Support/community.bildarchiv.pilot/Diagnostics/TrueArchive.log. Timestamps are explicitly UTC. Readable and structured history share a limit of 5 MiB and seven days; older entries are removed automatically.

Entries contain no private filenames, paths, accounts, passwords or raw server responses. If the file cannot be written, available entries remain copyable in the window. Gaps are disclosed; a missing completion from a previous session does not by itself prove a crash.

Note the action and the message shown. Under Help → Diagnostic report … you can view the technical report and copy it with “Copy report”.

Save a support package: “Support report…” in a local or Apple Photos import report also opens this dialog. The locally stored diagnostic history is limited and may not fully cover older operations.

1. Open the diagnostic report and, if needed, “Support package contents” to review the technical summary.
2. Choose “Save support package…” and a destination. The ZIP file contains a text summary, TrueArchive.log and structured technical states, counts and error categories.
3. Review the package and attach it to your message yourself. It contains no photos, filenames, paths, accounts or credentials. TrueArchive sends nothing automatically. If saving fails, you can still copy the report.

Check the testing status and known limitations in the release notes for your test version. TrueArchive is a personal community project in its pilot phase.

Send feedback on testing or Suggest a feature.