> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/match-by-file-path.md). # Match by file path Match media-server items by their normalized file paths when IDs cannot resolve them. Match by file path is an optional fallback for sync pairs between Plex, Jellyfin, and Emby. It also works between separate instances of the same provider. CrossWatch tries ID matching first. When no ID resolves an item, it compares normalized file-path endings in the destination libraries selected for that feature. This setting also permits the fallback when **Strict ID matching** is enabled. It does not enable title searches. ### Supported features Match by file path supports: * Movie and episode history * Ratings * Playback progress It does not support watchlists, playlists, collections, or tracker services such as Trakt and SIMKL. Kodi is not supported. ### Enable matching 1. Open the pair configuration. 2. Go to **General → Matching**. 3. Enable **Match by file path**. The setting is off by default. It applies in both directions for two-way pairs. ### How paths match For example, these movie paths match: ``` /mnt/media/movies/Alien (1979)/Alien.mkv D:\Movies\Alien (1979)\Alien.mkv ``` * Movies use the last two path segments. * Episodes use the last three path segments, season, and episode numbers. * Separators and letter case are normalized. * Explicit multipart movie numbers remain distinct. CrossWatch does not read file contents. Different filenames, trailing folders, or episode numbering do not match. ### Resolution rules CrossWatch requires one matching destination item. Duplicate path matches and conflicting external IDs are skipped and logged. Successful fallback lookups are logged as `path_match` with `resolution_method=file_path`. ### Catalogue and cache behavior Enabling this option can require a full metadata catalogue read, including unwatched destination items. Large libraries may take longer to sync. CrossWatch stores the catalogue in its local SQLite database and reuses it across pairs and features with the same server, user credentials, and selected libraries. Credentials are hashed into the cache identity, not stored in the catalogue. Catalogue reuse checks: * Plex library scan and content-change timestamps. * Jellyfin and Emby item counts and a verified metadata-change filter. * The server HTTP date, with a two-minute overlap, for Jellyfin and Emby. Servers that reject the filter or omit required timestamps use a five-minute fallback. A change signal or catalogue older than 24 hours triggers a full refresh. Without a usable change signal, CrossWatch reuses the catalogue for up to five minutes. Within one adapter, checks are cached for up to 90 seconds. Cache-read and change-check errors trigger a full catalogue read. Cache-write errors still permit the new catalogue to be used. Failed or incomplete reads do not replace a complete catalogue or serve stale data. CrossWatch prunes unused catalogues after seven days when it saves a new catalogue. This is a periodically refreshed index, not webhook-driven indexing. Changes can remain unseen during the short cache window. Existing snapshots gain path metadata as they refresh. No manual database migration is needed. ### Related controls Strict ID matching is also under **General → Matching**, with a separate control for each supported provider in the pair. Plex **Marked Watched** is under **History → Plex** and is saved for this pair only. Pairs without a Marked Watched override inherit the existing Plex default. ### Clear catalogues Use **Maintenance → Retry provider items** to clear saved file-path catalogues and invalidate their in-memory copies. The preview shows the catalogue count and stored payload size. Catalogues rebuild when needed. Sync baselines remain intact. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/match-by-file-path.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.