From Finch's built-in help · All help pages

Sync

How to carry your profiles and watch history to another device, and what Finch does with them.

What Finch remembers

Finch remembers your profiles, where you stopped in each episode or movie, what you’ve finished, any “Fix matching” choices you’ve made, and your playback preferences. All of it lives in one folder of plain text files, ~/.local/share/finch/sync/ (or ~/.var/app/dev.quietfield.Finch/data/finch/sync/ in the Flatpak):

  • history-<device>.jsonl: one line per change, written only by that device.
  • profiles.json: the list of profiles.
  • matches.json: your “Fix matching” choices.
  • preferences.json: playback preferences (passthrough, subtitle size and position, volume, preferred audio and subtitle language, play next episode, the next episode countdown, pause when leaving a video).

The library database and the posters and backdrops are not in that folder. They are rebuilt from the drive, so there is nothing to sync there. Each profile’s controls, its My list, and the choices made in a show’s menu (play next, shuffle, hide spoilers), stay on the device they were made on.

Steam Cloud

Nothing to set up if Finch came from Steam. Steam copies the sync folder when Finch launches and again when it exits. To turn this off for Finch, use Steam’s per-game Cloud setting.

Syncthing, Nextcloud, or any folder sync tool

Point the tool at the sync folder on every device. Two devices never write the same history log, so there is never a conflict to resolve by hand there; a merge happens the next time Finch starts, or scans a drive. A sync tool’s conflict copy of profiles.json or matches.json (Syncthing names them *.sync-conflict-*) can be deleted: profiles come back from the other devices at the next launch, and this device keeps its own match fixes in its library (a fix made only on the discarded copy is lost, so redo it with Fix series matching or Fix movie matching, under More… in Y’s menu on the title, if a poster looks wrong).

If an older copy of profiles.json comes back (a sync conflict settled the other way, or a folder restored by hand), each profile keeps its age limit, its daily limit and its bedtime each as it was last set, and its name, colour and picture as they were last changed, so an older copy never takes away a limit or a rule set since.

USB stick

Copy the folder over by hand, in either direction. History files that arrived from other devices get merged in, never overwritten.

Portable mode

Keep everything, including the library itself, on the media drive, so it follows the drive from one Finch install to the next.

Turn it on in Settings, then Advanced, then Sync, then “Portable mode”, and pick a folder on the drive. The picker lists removable drives; press Y to type the path of another folder instead. It refuses a folder on the drive that holds Finch’s own data folder.

From the command line, run this once with the drive plugged in:

finch --portable /run/media/deck/<drive>

This creates a Finch folder on the drive; --portable refuses the same folders the picker does. To go back to using this device’s own library:

finch --portable off

While the drive is unplugged, Finch uses this device’s own library and says so on screen. Steam Cloud never sees the drive’s folder.

Turning portable mode off goes back to the library this device had before; progress made while the drive was in use stays on the drive until you turn portable mode on again. Turning it on again also brings to the drive what you watched with it off.

Settings, then Advanced, then Sync shows which folder is in use and whether Finch could write its history there.

Profiles

Profiles are managed in Settings, then Profiles: add, rename, recolour, change the picture, remove or switch. Removing a profile removes its watch history from every device, once each one has synced with this one.

For scripts, the command line still works: finch --add-profile <name>, finch --remove-profile <name>, and finch --profile <name> to skip the “Who’s watching?” question.