Skip to content

Local File Structure

This documentation describes the local file structure, that is written by this application. Even though the design of this application should handle alterations to the file system structure, it is not recommended to change it manually.

Root folder

The root folder is specified through environment variable DATA_DIR. All assets and information are stored here:

  • _All-Photos folder (aka. PRIMARY_ASSET_DIR, see src)
  • _Shared-Photos folder (aka. SHARED_ASSET_DIR, see src)
  • _Archive folder (aka. ARCHIVE_DIR, see src)
  • .icloud-photos-sync.log log file (overwritten upon application restart)
  • .trust-token.icloud file ( MFA trust token used for re-authentication)
  • User created folders from the iCloud Library

Primary Asset Dir

The asset dir contains all assets stored in the primary iCloud Photos Library. Their filename is the checksum, as provided by the iCloud backend, together with the correct file extension.

The m-time is set, based on the returned 'modified' timestamp.

Shared Asset Dir

The asset dir contains all assets stored in the shared iCloud Photos Library. Their filename is the checksum, as provided by the iCloud backend, together with the correct file extension.

The m-time is set, based on the returned 'modified' timestamp.

Archive Dir

If an archived folder is deleted in the iCloud backend, this folder will be moved to the archive dir. When archived folders are moved on the backend, a subfolder (.stash) is used to keep track of them. Files and folders in this directory are ignored by this application and can be organized in this folder as you wish.

User Folders

Every user folder has two components:

  • A link with the display name of the folder/album, which links to
  • A folder containing the data, named after the UUID of the folder (and hidden: .{UUID})

For each asset within an album, a link to the asset dir is created. Naming is based on the filename, provided by iCloud. Original files don't have a suffix, edits are suffixed with -edited, live photos are suffixed with -live (see src).

Due to current limitations of the iCloud Web API, user folders only contain assets from the primary library, assets from the shared library cannot be linked to user folders.

If a user folder contains a non-safe file (see Safe Files), this marks the folder as archived, and its content is ignored upon future syncs.