Skip to content

Latest commit

 

History

History
230 lines (170 loc) · 10.6 KB

GLOSSARY.md

File metadata and controls

230 lines (170 loc) · 10.6 KB

immich-sync

An Immich desktop sync client for Windows. The client uploads files from user-selected folders to one Immich server. It runs in the background with a config window and a tray icon.

Language

Sync

Source folder: A local directory that the user selected for upload. Avoid: sync root, watched folder, library

Owner: The one source folder a sync item belongs to: the first source folder in the client's folder list that contains the item's path. That folder's card counts the item and its traffic meter counts its bytes, so a nested folder owns only the files no folder before it contains. Avoid: parent folder, matching folder

Sync item: One local file that the client tracks from discovery to upload result. Avoid: job, task, file record

Unsupported file: A file whose extension is not one Immich accepts. The client never queues it: it is not a sync item, has no attempt, and never becomes a failure. The folder detail shows how many the last scan of that folder refused, and the count is stored with the folder so a restart keeps it. Avoid: invalid file, rejected file, bad format

Tracking: The client's record of the source folders it holds and the decisions the user has made about their items. One module owns it, so a signed-out client and a running engine write the same rows by the same rules. Avoid: library, registry, folder list

Reconciliation scan: A full read of a source folder. The client uses it to find changes that watch events missed. Avoid: rescan, poll

Album mapping: A per-folder rule that creates one Immich album for the folder. The album's title defaults to the folder's name and can be changed. One album belongs to one folder: two folders that share a name are two albums. Avoid: folder sync, album mode

Album title: The user-visible name of one mapped album. The source folder's own album takes the user's title, which defaults to the folder's name and can be changed after the album exists. A leaf folder's album takes the leaf's path relative to the source folder, optionally starting with the source folder's album title, or the leaf folder's name alone. Changing a title renames the Immich album. Avoid: album name, title override

Album scope: The user's choice for one mapped source folder: one album for the whole source folder, or one album per folder that directly contains files. Under the per-folder choice, the folder's two naming choices title the albums it makes. Avoid: album mode, album structure

Duplicate: A sync item whose content already exists on the server. Avoid: existing file, clash

Rename: A missing file and a new file with the same content and size. The client keeps the asset mapping and raises no review item. Avoid: move, path change

Version: The content of a sync item at one point in time. Each version is a separate asset, and the client keeps the versions in one stack. Avoid: revision, copy

Missing file: A sync item whose local file is no longer present. The client asks the user what to do with the server copy. Avoid: deleted file, orphan

Deletion review: The list in the config window where the user decides the server fate of each missing file. The client changes nothing on the server before a decision. Avoid: deletion queue, cleanup list

Upload

Upload attempt: One try to send one sync item to the server. Avoid: transfer, job

Retriable error: A failure that can succeed on a later attempt, such as a timeout or a 503 response. Avoid: soft error, temporary failure

Permanent error: A failure that cannot succeed on a later attempt without a change, such as an unsupported format or a bad credential. Avoid: hard error, fatal error

Dead letter: The state of a sync item after the client stops its automatic retries. The user can retry the item by hand. Avoid: failed queue, DLQ

Bandwidth limit: The user-set maximum number of upload bytes per second. Avoid: speed cap, throttle

Concurrency limit: The user-set maximum number of uploads that may run at one time. Avoid: parallelism, workers

Upload throughput: The rate at which upload bodies move bytes to the server, measured over a short rolling window. Avoid: speed, transfer rate

Upload in flight: An upload request that has started and has not finished. Hashing, indexing, and the server duplicate check are not uploads in flight. Avoid: active upload, running transfer

Sync tag: The one Immich tag, immich-sync, that the client adds to the assets it syncs so they can be found with Immich's tag search. It is on by default; the user can turn it off in Settings. While it is on, the client tags new uploads and backfills the tag onto the assets it uploaded before. Avoid: upload tag, source tag

Backfill: The pass that adds the sync tag to the assets the client uploaded before the setting was turned on: every current asset, every old version, and every duplicate, a batch of ids per request. Its progress and completion are recorded, so a restart resumes it instead of starting over. Avoid: re-tag, scan

Immich

Asset: One media object on the Immich server. Avoid: photo, file, media

Asset link: The Immich web address of one uploaded asset, opened in the default browser. Avoid: photo URL, deep link

Album: An Immich collection of assets. It is the closest server-side match for a local folder. Avoid: collection, gallery

Sidecar: An XMP file that carries metadata for one asset. Avoid: metadata file

Live photo pair: A photo asset and its linked video asset. Avoid: motion photo, burst

Stack: An Immich group of related assets. The timeline shows one stack entry. Avoid: group, collection

Credentials

Session token: The credential that the Immich login endpoint returns. The server can revoke it or delete it at any time. Avoid: access token, bearer token, JWT

API key: A long-lived Immich credential with a fixed permission list. Avoid: token, secret

Credential store: The operating-system secret store. On Windows this is the Credential Manager, on macOS the login Keychain, and on Linux the Secret Service. Avoid: vault, password file

Shell

Config window: The main window. The user sets the server, the credentials, the source folders, the limits, and the deletion review here. Avoid: settings dialog, preferences

Tray icon: The status icon in the notification area. It shows sync state and it opens the config window. Avoid: system tray, notification icon

Pause: The user's hold on new uploads, from the dashboard control, the tray menu, or one source folder's own control. Each hold is separate from the others, so resuming one never overrides another. Avoid: stop, disable sync

Folder pause: One source folder's own pause. The reconciliation scan and the watcher leave a paused folder alone, so it costs no scanning, hashing, or disk work, and its queued items wait without failing; resuming scans it and drains the queue. It follows Owner, so pausing a folder stops exactly the items that folder's card counts. Avoid: per-folder setting, folder hold

Folder status: The sync state of one source folder. The dashboard shows one card per source folder, and the folder detail renders the same status in full. Avoid: folder state, folder progress

Folder setup: The dialog that confirms a new source folder's recursion and album settings. The client records and scans the folder only when the user confirms. Avoid: add dialog, onboarding

Folder detail: The enlarged view of one source folder: its full path, live state and counts, its own upload activity, settings, timestamps, and the list of the assets it has uploaded, with links into the Failed and Review views filtered to it. Its Remove needs a confirmation, because the folder's uploaded assets stay on the server. Avoid: folder modal, folder popup

Known networks: The user's list of network names for the Sync only on known networks setting, compared against the name the OS reports for the current wireless network. A wired link always syncs, because it has no name to match. The list is off by default. Avoid: allowed networks, trusted networks, whitelist

Network check: The client's one read of the OS's current network, through a network source per platform. It decides whether uploads are held, and its answer is what the Settings page shows as the current network. Avoid: SSID lookup, network probe, reachability check

Network source: The platform backend that answers the network check: NetworkManager over D-Bus on Linux, the Network List Manager on Windows, and CoreWLAN with CaptiveNetwork on macOS. It also reports the OS's network-change events, which the client uses to re-check before the 30-second fallback poll. Avoid: provider, adapter, detector

Pause reason: Why uploads are held: the user's own pause, or the known-network list. Both read as the paused activity state; the dashboard and the tray tooltip phrase the reason. Avoid: pause kind, pause cause, hold type

Updates

Update check: The client's one read of GitHub's newest published release: at startup and at most once every 24 hours, with a switch on the Updates page and no ability to install anything. Failure is silent; the reason is one line in the log. Avoid: auto-update, version poll, release feed

Release page: The GitHub page one published release carries. The client links to it and never builds the URL from the version, so a stale link cannot open an empty page. Avoid: download page, changelog URL

Dismissed release: A release the user silenced with Don't remind me about <version>. The silence is stored as that release's version, so it survives a restart, the control turns into Remind me about <version>, and the next release speaks again. Avoid: muted update, ignored version, snooze

Diagnostics

Client version: The package version and the short source revision the running binary was built from, for example 0.1.0 (abc1234). Diagnostics and the log's start line both report it, and a build outside a git repository reports unknown in place of the revision. Avoid: app version, build version

Server version: The version the connected Immich server reports. Diagnostics shows it beside the client version, so a support session can tell which side a fault is on. Avoid: Immich version, API version

Debug bundle: One archive Diagnostics collects for a support message: the logs, versions, database information, configuration, and sizing. Avoid: support bundle, log bundle, diagnostics archive

Live tail: The Logs view's automatic reading of new lines from the newest log file. Following pauses while the user reads older lines or holds a selection. Avoid: auto-refresh, follow mode