jellyplex-sync 0.4.0__tar.gz → 0.5.0__tar.gz

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jellyplex-sync
-Version: 0.4.0
+Version: 0.5.0
 Summary: Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror
 Keywords: plex,jellyfin,media-library,movies,sync,hardlink,mirror
 Author: Stefan Schönberger
@@ -32,7 +32,7 @@ Can't decide between Jellyfin and Plex? This tool might help. It synchronizes yo
 
 The script scans the source library, parses each movie folder for metadata (title, year, optional provider ID), and reproduces the same directory structure in the target location. Rather than copying video files, it creates hard links to avoid extra storage usage. Asset folders (e.g., `extras`, `subtitles`) are also mirrored. Loose top-level files (posters, NFOs, subtitles) are synced 1:1 by default since 0.2.0. With `--delete`, any files or folders in the target that are no longer present in the source will be removed.
 
-> **Warning:** This script will **overwrite the entire target directory**. Do not store or edit anything manually in the target library path. The source library is treated as the **only source of truth**, and any unmatched content in the target folder may be deleted without warning.
+> **Warning:** This script will **overwrite the entire target directory**. Do not store or edit anything manually in the target library path. The source library is treated as the **only source of truth**, and any unmatched content in the target folder may be deleted without warning. Folders you mark with `.jellyplex-sync-ignore` are the exception, see [Excluding folders](#excluding-folders).
 
 > **Note:** This tool is only useful if your media library is well-maintained and each movie resides in its own folder.
 
@@ -153,7 +153,8 @@ Exit codes follow the Unix `diff` convention:
 
 - `0` — in sync.
 - `1` — differences found.
-- `2` — setup error (missing directories, indecipherable format).
+- `2` — setup error (missing directories, indecipherable format), or one of the
+  library folders contains `.jellyplex-sync-ignore`.
 
 #### Example
 
@@ -236,6 +237,28 @@ Preview first, keeping the source:
 jellyplex import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
 ```
 
+### Excluding folders
+
+To exclude a folder and everything below it, put an empty file named `.jellyplex-sync-ignore` into it:
+
+```bash
+touch ~/"Media/Plex/Some Movie (2001) {imdb-tt0000000}/.jellyplex-sync-ignore"
+```
+
+The marker means the same in both directions, so it does not matter whether the library is the source or the target of a run:
+
+- **In the source**, the folder is treated as if it did not exist. Nothing in it is synced or imported.
+- **In the target**, nothing is written into the folder and nothing is removed from it, not even with `--delete`. A marked folder that has no counterpart in the source is not reported as a stray.
+
+The marker works at any level: in a movie folder, in an asset folder such as `other`, or further down. The marker file itself is never copied to the other library.
+
+Things to know:
+
+- **Marking a source folder does not keep its copy in the target.** If the folder was synced before, its copy in the target becomes a stray: it is reported, and `--delete` removes it. The source folder is not touched. To keep the copy, put a marker into the target folder as well.
+- **A marked folder is also kept when `--delete` would remove a folder above it.** If a folder in the target has no counterpart in the source but contains a marked folder at any depth, the whole folder is kept.
+- **A marker in the library folder itself stops the run.** `sync` and `import` change nothing, print a warning and exit with code 0. `diff` exits with code 2, and `plan` shows an empty plan. A marked source library is not treated as an empty library, so `--delete` cannot clear the target this way.
+- At the end of a `sync` or `import` run, the number of marked folders is printed; `--verbose` lists them. `diff` and `plan` always list them. In the `--json` output they are in `marked_in_source` and `marked_in_target`.
+
 ### JSON output
 
 All three subcommands accept `--json` for machine-readable output. The document goes to **stdout**; logs continue to go to stderr. Under `--json`, INFO logs are suppressed unless you pass `--verbose` or `--debug`, so the output pipes cleanly into tools like `jq` without filtering.
@@ -247,9 +270,10 @@ The schema (still evolving — pin a version when consuming):
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
 - `summary`: counters; the set of fields depends on the operation.
-  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`.
-  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`, `marked_in_source`, `marked_in_target`.
+  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`, `marked_in_source`, `marked_in_target`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
+- `marked_in_source` / `marked_in_target`: full paths of the folders skipped because they contain `.jellyplex-sync-ignore` (see [Excluding folders](#excluding-folders)). A library folder in one of these lists means the run was stopped.
 - `strays_in_target` (sync only): list of names found in target that aren't in source.
 - `translation_losses`: distinct `{kind, key, value, reason}` tuples for labels/attributes the target format can't express. Deduplicated — one entry per distinct loss, not per affected file.
 - `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove` — `link` covers every creation, including copies in `--copy` mode. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
@@ -321,8 +345,10 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **Hardlinks (default)** — Video files are linked, not copied. Both libraries reference the same physical files on disk. Switch to `--copy` for cross-filesystem setups.
 - **Asset folders** — Subdirectories (e.g., `other`, `interviews`) are processed recursively with the same materialization strategy. Note: rename your Jellyfin `extras` folder to `other`, since Plex does not recognize `extras`.
 - **Loose top-level files** — Sidecar files (`.nfo`, posters, external subtitles, plain notes) at the top of a movie folder are synced 1:1 by default since 0.2.0. Pre-0.2.0 they were silently dropped — which made the tool unsafe for migrations. Dot-files (`.DS_Store`, `.stversions`, …) stay excluded.
-- **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
+- **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed, except folders marked with `.jellyplex-sync-ignore` and folders that contain one. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
 - **Ignored items** — Entries the scanner couldn't classify (stray files at the library root, folders whose names don't parse) are reported in the summary and the `--json` `ignored` array. They are *not* carried over to the target — useful to verify before deleting the source.
+- **Hidden files and folders are skipped.** Names starting with a dot (`.DS_Store`, `.stversions`, `.Trash`) are skipped at every level of the source library, by `import` as well. They do not appear in the list of ignored items.
+- **Marked folders are skipped** on both sides, see [Excluding folders](#excluding-folders).
 - **Video-level clashes auto-resolve** — When two source files would translate to the same target name (a common P→J outcome: `[1080p].mkv` and `[1080p] [remux].mkv` both collapse to `- BD.mkv`), a short hash of the source filename gets appended (e.g. `Movie - BD [a3f7c819].mkv`). Both files get synced; spot the hash in the `plan` output or in `--json` via the per-file `disambiguation` field. Pre-0.3 the whole movie was skipped on clash.
 - **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped with exit code 2, the clashing folders are listed, and you're asked to rename one side.
 

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/README.md

@@ -6,7 +6,7 @@ Can't decide between Jellyfin and Plex? This tool might help. It synchronizes yo
 
 The script scans the source library, parses each movie folder for metadata (title, year, optional provider ID), and reproduces the same directory structure in the target location. Rather than copying video files, it creates hard links to avoid extra storage usage. Asset folders (e.g., `extras`, `subtitles`) are also mirrored. Loose top-level files (posters, NFOs, subtitles) are synced 1:1 by default since 0.2.0. With `--delete`, any files or folders in the target that are no longer present in the source will be removed.
 
-> **Warning:** This script will **overwrite the entire target directory**. Do not store or edit anything manually in the target library path. The source library is treated as the **only source of truth**, and any unmatched content in the target folder may be deleted without warning.
+> **Warning:** This script will **overwrite the entire target directory**. Do not store or edit anything manually in the target library path. The source library is treated as the **only source of truth**, and any unmatched content in the target folder may be deleted without warning. Folders you mark with `.jellyplex-sync-ignore` are the exception, see [Excluding folders](#excluding-folders).
 
 > **Note:** This tool is only useful if your media library is well-maintained and each movie resides in its own folder.
 
@@ -127,7 +127,8 @@ Exit codes follow the Unix `diff` convention:
 
 - `0` — in sync.
 - `1` — differences found.
-- `2` — setup error (missing directories, indecipherable format).
+- `2` — setup error (missing directories, indecipherable format), or one of the
+  library folders contains `.jellyplex-sync-ignore`.
 
 #### Example
 
@@ -210,6 +211,28 @@ Preview first, keeping the source:
 jellyplex import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
 ```
 
+### Excluding folders
+
+To exclude a folder and everything below it, put an empty file named `.jellyplex-sync-ignore` into it:
+
+```bash
+touch ~/"Media/Plex/Some Movie (2001) {imdb-tt0000000}/.jellyplex-sync-ignore"
+```
+
+The marker means the same in both directions, so it does not matter whether the library is the source or the target of a run:
+
+- **In the source**, the folder is treated as if it did not exist. Nothing in it is synced or imported.
+- **In the target**, nothing is written into the folder and nothing is removed from it, not even with `--delete`. A marked folder that has no counterpart in the source is not reported as a stray.
+
+The marker works at any level: in a movie folder, in an asset folder such as `other`, or further down. The marker file itself is never copied to the other library.
+
+Things to know:
+
+- **Marking a source folder does not keep its copy in the target.** If the folder was synced before, its copy in the target becomes a stray: it is reported, and `--delete` removes it. The source folder is not touched. To keep the copy, put a marker into the target folder as well.
+- **A marked folder is also kept when `--delete` would remove a folder above it.** If a folder in the target has no counterpart in the source but contains a marked folder at any depth, the whole folder is kept.
+- **A marker in the library folder itself stops the run.** `sync` and `import` change nothing, print a warning and exit with code 0. `diff` exits with code 2, and `plan` shows an empty plan. A marked source library is not treated as an empty library, so `--delete` cannot clear the target this way.
+- At the end of a `sync` or `import` run, the number of marked folders is printed; `--verbose` lists them. `diff` and `plan` always list them. In the `--json` output they are in `marked_in_source` and `marked_in_target`.
+
 ### JSON output
 
 All three subcommands accept `--json` for machine-readable output. The document goes to **stdout**; logs continue to go to stderr. Under `--json`, INFO logs are suppressed unless you pass `--verbose` or `--debug`, so the output pipes cleanly into tools like `jq` without filtering.
@@ -221,9 +244,10 @@ The schema (still evolving — pin a version when consuming):
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
 - `summary`: counters; the set of fields depends on the operation.
-  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`.
-  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`, `marked_in_source`, `marked_in_target`.
+  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`, `marked_in_source`, `marked_in_target`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
+- `marked_in_source` / `marked_in_target`: full paths of the folders skipped because they contain `.jellyplex-sync-ignore` (see [Excluding folders](#excluding-folders)). A library folder in one of these lists means the run was stopped.
 - `strays_in_target` (sync only): list of names found in target that aren't in source.
 - `translation_losses`: distinct `{kind, key, value, reason}` tuples for labels/attributes the target format can't express. Deduplicated — one entry per distinct loss, not per affected file.
 - `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove` — `link` covers every creation, including copies in `--copy` mode. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
@@ -295,8 +319,10 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **Hardlinks (default)** — Video files are linked, not copied. Both libraries reference the same physical files on disk. Switch to `--copy` for cross-filesystem setups.
 - **Asset folders** — Subdirectories (e.g., `other`, `interviews`) are processed recursively with the same materialization strategy. Note: rename your Jellyfin `extras` folder to `other`, since Plex does not recognize `extras`.
 - **Loose top-level files** — Sidecar files (`.nfo`, posters, external subtitles, plain notes) at the top of a movie folder are synced 1:1 by default since 0.2.0. Pre-0.2.0 they were silently dropped — which made the tool unsafe for migrations. Dot-files (`.DS_Store`, `.stversions`, …) stay excluded.
-- **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
+- **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed, except folders marked with `.jellyplex-sync-ignore` and folders that contain one. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
 - **Ignored items** — Entries the scanner couldn't classify (stray files at the library root, folders whose names don't parse) are reported in the summary and the `--json` `ignored` array. They are *not* carried over to the target — useful to verify before deleting the source.
+- **Hidden files and folders are skipped.** Names starting with a dot (`.DS_Store`, `.stversions`, `.Trash`) are skipped at every level of the source library, by `import` as well. They do not appear in the list of ignored items.
+- **Marked folders are skipped** on both sides, see [Excluding folders](#excluding-folders).
 - **Video-level clashes auto-resolve** — When two source files would translate to the same target name (a common P→J outcome: `[1080p].mkv` and `[1080p] [remux].mkv` both collapse to `- BD.mkv`), a short hash of the source filename gets appended (e.g. `Movie - BD [a3f7c819].mkv`). Both files get synced; spot the hash in the `plan` output or in `--json` via the per-file `disambiguation` field. Pre-0.3 the whole movie was skipped on clash.
 - **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped with exit code 2, the clashing folders are listed, and you're asked to rename one side.
 

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jellyplex-sync"
-version = "0.4.0"
+version = "0.5.0"
 description = "Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror"
 requires-python = ">=3.11"
 readme = "README.md"

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "jellyplex-sync"
-version = "0.4.0"
+version = "0.5.0"
 description = "Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror"
 authors = [{ name = "Stefan Schönberger", email = "stefan@sniner.dev" }]
 requires-python = ">=3.11"

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/compare.py

@@ -12,9 +12,10 @@ without a side-channel to the Planner's reporter.
 
 from __future__ import annotations
 
+import pathlib
 from dataclasses import dataclass
 
-from .library import Drop, IgnoredEntry
+from .library import Drop, IgnoredEntry, find_marked
 from .plan import Plan, collect_drops
 
 
@@ -41,11 +42,17 @@ class MovieOnlyInSource:
 
 @dataclass
 class DiffResult:
+    """`marked_in_source` and `marked_in_target` are the folders left out
+    of the comparison because they contain the ignore marker. They are
+    no difference: a sync leaves them alone as well."""
+
     movies_only_in_source: tuple[MovieOnlyInSource, ...] = ()
     movies_only_in_target: tuple[str, ...] = ()
     differing_movies: tuple[DiffEntry, ...] = ()
     drops: tuple[Drop, ...] = ()
     ignored: tuple[IgnoredEntry, ...] = ()
+    marked_in_source: tuple[pathlib.Path, ...] = ()
+    marked_in_target: tuple[pathlib.Path, ...] = ()
 
     @property
     def has_differences(self) -> bool:
@@ -62,11 +69,16 @@ def compare(plan: Plan) -> DiffResult:
     as the pre-0.3 diff implementation."""
     planned_folder_names = {m.target_folder.name for m in plan.movies}
     planned_by_name = {m.target_folder.name: m for m in plan.movies}
+    marked_folder_names = {
+        p.relative_to(plan.target_root).parts[0]
+        for p in plan.marked_in_target
+        if p != plan.target_root
+    }
 
     actual: dict[str, set[str]] = {}
     if plan.target_root.is_dir():
         for entry in plan.target_root.iterdir():
-            if not entry.is_dir():
+            if not entry.is_dir() or entry.name in marked_folder_names:
                 continue
             actual[entry.name] = {sub.name for sub in entry.iterdir()}
 
@@ -90,7 +102,15 @@ def compare(plan: Plan) -> DiffResult:
             | {a.folder_name for a in pm.assets}
         )
         src_only = tuple(sorted(expected_files - actual[name]))
-        tgt_only = tuple(sorted(actual[name] - expected_files))
+        # Same rule as the Realizer: an entry that is or holds a marked
+        # folder would not be removed, so it is no difference.
+        tgt_only = tuple(
+            sorted(
+                sub
+                for sub in actual[name] - expected_files
+                if not _holds_marker(plan.target_root / name / sub)
+            )
+        )
         if src_only or tgt_only:
             differing.append(
                 DiffEntry(
@@ -106,4 +126,10 @@ def compare(plan: Plan) -> DiffResult:
         differing_movies=tuple(differing),
         drops=collect_drops(plan),
         ignored=tuple(plan.ignored),
+        marked_in_source=plan.marked_in_source,
+        marked_in_target=plan.marked_in_target,
     )
+
+
+def _holds_marker(path: pathlib.Path) -> bool:
+    return not path.is_symlink() and bool(find_marked(path))

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/discover.py

@@ -19,7 +19,13 @@ from collections.abc import Iterable
 from dataclasses import dataclass
 from typing import Protocol
 
-from .library import ACCEPTED_VIDEO_SUFFIXES, IgnoredEntry, LibraryReader
+from .library import (
+    ACCEPTED_VIDEO_SUFFIXES,
+    IgnoredEntry,
+    LibraryReader,
+    find_marked,
+    is_marked,
+)
 from .model import MovieInfo
 
 
@@ -47,11 +53,16 @@ class DiscoveredGroup:
 
 
 class SourceDiscoverer(Protocol):
+    """Finds candidate groups below `root`. Entries it cannot use go to
+    `ignored`; directories it skips because they contain the ignore
+    marker go to `marked`, `root` included."""
+
     def discover(
         self,
         root: pathlib.Path,
         *,
         ignored: list[IgnoredEntry] | None = None,
+        marked: list[pathlib.Path] | None = None,
     ) -> Iterable[DiscoveredGroup]: ...
 
 
@@ -69,24 +80,39 @@ class TwoLevelDiscoverer:
         root: pathlib.Path,
         *,
         ignored: list[IgnoredEntry] | None = None,
+        marked: list[pathlib.Path] | None = None,
     ) -> Iterable[DiscoveredGroup]:
+        if is_marked(root):
+            if marked is not None:
+                marked.append(root)
+            return
         for entry in sorted(root.glob("*")):
+            if entry.name.startswith("."):
+                # OS/sync junk (.DS_Store, .stversions, .Trash, ...), skipped
+                # without a report at every level. The readers would accept
+                # such a name as a movie title.
+                continue
             if not entry.is_dir():
                 if ignored is not None:
                     ignored.append(IgnoredEntry(entry, "not a directory"))
                 continue
+            if is_marked(entry):
+                if marked is not None:
+                    marked.append(entry)
+                continue
             videos: list[pathlib.Path] = []
             assets: list[pathlib.Path] = []
             loose: list[pathlib.Path] = []
-            for child in entry.glob("*"):
+            for child in sorted(entry.glob("*")):
                 if child.name.startswith("."):
-                    # OS/sync junk (.DS_Store, .stversions, ...). Skipped
-                    # in both file and folder form, matching legacy behaviour.
                     continue
                 if child.is_file() and child.suffix.lower() in ACCEPTED_VIDEO_SUFFIXES:
                     videos.append(child)
                 elif child.is_file():
                     loose.append(child)
+                elif child.is_dir() and is_marked(child):
+                    if marked is not None:
+                        marked.append(child)
                 elif child.is_dir():
                     assets.append(child)
             yield DiscoveredGroup(
@@ -137,15 +163,25 @@ class FlatDiscoverer:
         root: pathlib.Path,
         *,
         ignored: list[IgnoredEntry] | None = None,
+        marked: list[pathlib.Path] | None = None,
     ) -> Iterable[DiscoveredGroup]:
         groups: dict[_MovieKey, list[pathlib.Path]] = {}
         source_paths: dict[_MovieKey, pathlib.Path] = {}
         movies: dict[_MovieKey, MovieInfo] = {}
 
+        marked_dirs = self._marked_dirs(root)
+        if marked is not None:
+            marked.extend(sorted(marked_dirs))
+
         for path in sorted(root.rglob("*")):
             if not path.is_file():
                 continue
-            if path.name.startswith("."):
+            # Dot-files and everything below a dot-folder (.Trash,
+            # .stversions). Only the parts below root count: the staging
+            # root itself may lie inside a dot-folder.
+            if _is_hidden(path, root):
+                continue
+            if any(parent in marked_dirs for parent in path.parents):
                 continue
             if path.suffix.lower() not in ACCEPTED_VIDEO_SUFFIXES:
                 if ignored is not None:
@@ -174,3 +210,14 @@ class FlatDiscoverer:
                 loose_files=(),
                 movie=movies[key],
             )
+
+    @staticmethod
+    def _marked_dirs(root: pathlib.Path) -> set[pathlib.Path]:
+        """Marked directories at or below `root`. A marker inside a
+        dot-folder does not count: that folder is skipped anyway, and
+        reporting it would name something the user never sees."""
+        return {d for d in find_marked(root) if not _is_hidden(d, root)}
+
+
+def _is_hidden(path: pathlib.Path, root: pathlib.Path) -> bool:
+    return any(part.startswith(".") for part in path.relative_to(root).parts)

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/json_output.py

@@ -34,6 +34,10 @@ def _ignored_payload(
     return [{"path": str(e.path), "name": e.path.name, "reason": e.reason} for e in entries]
 
 
+def _paths_payload(paths: list[pathlib.Path] | tuple[pathlib.Path, ...]) -> list[str]:
+    return [str(p) for p in paths]
+
+
 def _drop_payload(d: Drop) -> dict[str, Any]:
     return {"kind": d.kind, "key": d.key, "value": d.value, "reason": d.reason}
 
@@ -97,8 +101,12 @@ def write_sync_json(
             "items_ignored": len(stats.ignored),
             "strays_in_target": len(stats.strays_in_target),
             "clashes": len(stats.clashes),
+            "marked_in_source": len(stats.marked_in_source),
+            "marked_in_target": len(stats.marked_in_target),
         },
         "ignored": _ignored_payload(stats.ignored),
+        "marked_in_source": _paths_payload(stats.marked_in_source),
+        "marked_in_target": _paths_payload(stats.marked_in_target),
         "strays_in_target": list(stats.strays_in_target),
         "translation_losses": _drops_payload(drops),
         "clashes": _clashes_payload(stats.clashes),
@@ -173,12 +181,16 @@ def write_plan_json(out: TextIO, plan: Plan) -> None:
             "movie_clashes": len(plan.clashes),
             "translation_losses": len(distinct_drops),
             "ignored": len(plan.ignored),
+            "marked_in_source": len(plan.marked_in_source),
+            "marked_in_target": len(plan.marked_in_target),
         },
         "movies": [_planned_movie_payload(m) for m in plan.movies],
         "folder_clashes": _folder_clashes_payload(plan.folder_clashes),
         "movie_clashes": _clashes_payload(list(plan.clashes)),
         "translation_losses": _drops_payload(drops),
         "ignored": _ignored_payload(list(plan.ignored)),
+        "marked_in_source": _paths_payload(plan.marked_in_source),
+        "marked_in_target": _paths_payload(plan.marked_in_target),
     }
     json.dump(payload, out, indent=2)
     out.write("\n")
@@ -218,6 +230,8 @@ def write_diff_json(
         ],
         "translation_losses": _drops_payload(result.drops),
         "ignored": _ignored_payload(result.ignored),
+        "marked_in_source": _paths_payload(result.marked_in_source),
+        "marked_in_target": _paths_payload(result.marked_in_target),
     }
     json.dump(payload, out, indent=2)
     out.write("\n")

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/library.py

@@ -12,6 +12,29 @@ log = logging.getLogger(__name__)
 
 ACCEPTED_VIDEO_SUFFIXES = {".mkv", ".m4v"}
 
+# A directory containing this file is left out of every run, together with
+# everything below it: in the source it is not read, in the target nothing
+# is written into it or removed from it.
+IGNORE_MARKER = ".jellyplex-sync-ignore"
+
+
+def is_marked(folder: pathlib.Path) -> bool:
+    """True if `folder` itself contains the ignore marker."""
+    return (folder / IGNORE_MARKER).exists()
+
+
+def find_marked(tree: pathlib.Path) -> list[pathlib.Path]:
+    """The outermost directories at or below `tree` that contain the
+    ignore marker, sorted. A marked directory inside another one is left
+    out, the outer one already covers it. Empty for a file or a missing
+    path."""
+    if not tree.is_dir():
+        return []
+    if is_marked(tree):
+        return [tree]
+    found = {m.parent for m in tree.rglob(IGNORE_MARKER)}
+    return sorted(d for d in found if not any(p in found for p in d.parents))
+
 
 # ---------------------------------------------------------------------------
 # Reporter: how Writers tell the caller about lossy decisions

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/plan.py

@@ -5,9 +5,10 @@ would be created in the target library if the sync ran. It is the
 single source of truth for what the Realizer should do, what the
 Comparator should expect, and what the JSON output reports.
 
-Plans are pure data — building one never touches the target filesystem.
-That property is what makes them auditable, serialisable, comparable
-across runs, and safely shareable between phases.
+Plans are pure data. Building one never writes to the target
+filesystem; it reads the target only to find ignore markers. That
+property is what makes them auditable, serialisable, comparable across
+runs, and safely shareable between phases.
 """
 
 from __future__ import annotations
@@ -86,7 +87,17 @@ class Plan:
     `protected_folders` holds the target folder names of source movies
     that could not be planned at all (folder clashes, or every video
     unresolved) — they are absent from `movies`, but the Realizer must
-    not treat an existing target folder of that name as a stray."""
+    not treat an existing target folder of that name as a stray.
+
+    `marked_in_source` and `marked_in_target` hold the directories left
+    out because they contain the ignore marker. On the source side these
+    were not read. On the target side nothing is planned into them, and
+    the Realizer must neither remove them nor count them as strays. The
+    target list covers the library level (marked folders, and marked
+    folders anywhere inside a folder no source movie maps to) and the
+    asset folders the Plan would have written into. Markers deeper
+    inside a planned movie folder are not listed; the Realizer checks
+    for them before it removes anything."""
 
     source_root: pathlib.Path
     target_root: pathlib.Path
@@ -97,6 +108,19 @@ class Plan:
     clashes: tuple[MovieClash, ...] = ()
     folder_clashes: tuple[FolderClash, ...] = ()
     protected_folders: tuple[str, ...] = ()
+    marked_in_source: tuple[pathlib.Path, ...] = ()
+    marked_in_target: tuple[pathlib.Path, ...] = ()
+
+    @property
+    def locked_root(self) -> pathlib.Path | None:
+        """The library root that contains the ignore marker, if any. A
+        marked root locks the whole run: the Plan is empty, and acting on
+        it must not change the target, not even with --delete."""
+        if self.source_root in self.marked_in_source:
+            return self.source_root
+        if self.target_root in self.marked_in_target:
+            return self.target_root
+        return None
 
 
 def collect_drops(plan: Plan) -> tuple[Drop, ...]:

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/planner.py

@@ -2,8 +2,9 @@
 
 The Planner is a pure function (modulo Reader I/O for `parse_movie` /
 `parse_video`): it reads the source tree, produces an immutable Plan,
-and never touches the target filesystem. The `Realizer` (next module)
-is the only layer that turns a Plan into actions on disk.
+and never writes to the target filesystem. It reads the target only to
+find ignore markers. The `Realizer` (next module) is the only layer
+that turns a Plan into actions on disk.
 
 This separation is what makes the new pipeline auditable: the same
 Plan can be inspected (`plan` subcommand), compared against an existing
@@ -15,6 +16,7 @@ from __future__ import annotations
 import logging
 import pathlib
 from collections import defaultdict
+from collections.abc import Collection
 from dataclasses import dataclass
 
 from .disambig import (
@@ -33,6 +35,8 @@ from .library import (
     LoggingReporter,
     MovieClash,
     Reporter,
+    find_marked,
+    is_marked,
 )
 from .model import MovieInfo
 from .plan import Plan, PlannedAsset, PlannedFile, PlannedMovie
@@ -81,15 +85,24 @@ class Planner:
         if source_root == target_root:
             raise ValueError("Cannot plan a library into itself")
 
+        locked = self._locked_plan(source_root, target_root)
+        if locked is not None:
+            return locked
+
         ignored: list[IgnoredEntry] = []
         clashes: list[MovieClash] = []
+        marked_src: list[pathlib.Path] = []
 
-        candidates_by_target = self._group_candidates(source_root, ignored)
+        candidates_by_target = self._group_candidates(source_root, ignored, marked_src)
+        marked_tgt = self._marked_in_target(target_root, candidates_by_target.keys())
+        marked_movie_folders = {p for p in marked_tgt if p.parent == target_root}
         planned_movies: list[PlannedMovie] = []
         folder_clashes: list[FolderClash] = []
         protected_folders: list[str] = []
 
         for target_name, items in candidates_by_target.items():
+            if target_root / target_name in marked_movie_folders:
+                continue
             if len(items) > 1:
                 folder_clashes.append(
                     FolderClash(
@@ -100,7 +113,12 @@ class Planner:
                 protected_folders.append(target_name)
                 continue
             (candidate,) = items
-            pm, movie_clashes = self._build_planned_movie(candidate, target_root / target_name)
+            pm, movie_clashes = self._build_planned_movie(
+                candidate,
+                target_root / target_name,
+                marked_src,
+                marked_tgt,
+            )
             clashes.extend(movie_clashes)
             if pm is not None:
                 planned_movies.append(pm)
@@ -120,22 +138,66 @@ class Planner:
             clashes=tuple(clashes),
             folder_clashes=tuple(folder_clashes),
             protected_folders=tuple(protected_folders),
+            marked_in_source=tuple(sorted(marked_src)),
+            marked_in_target=tuple(sorted(marked_tgt)),
         )
 
     # ------------------------------------------------------------------
     # internals
     # ------------------------------------------------------------------
 
+    def _locked_plan(self, source_root: pathlib.Path, target_root: pathlib.Path) -> Plan | None:
+        """An empty Plan if either library root is marked, else None.
+        Checked before anything is scanned: a marked source root must not
+        read as an empty library, or --delete would clear the target."""
+        source_marked = is_marked(source_root)
+        target_marked = is_marked(target_root)
+        if not (source_marked or target_marked):
+            return None
+        return Plan(
+            source_root=source_root,
+            target_root=target_root,
+            source_format=self._reader.shortname(),
+            target_format=self._writer.shortname(),
+            marked_in_source=(source_root,) if source_marked else (),
+            marked_in_target=(target_root,) if target_marked else (),
+        )
+
+    def _marked_in_target(
+        self,
+        target_root: pathlib.Path,
+        mapped: Collection[str],
+    ) -> list[pathlib.Path]:
+        """Marked directories at the library level of the target. A folder
+        some source movie maps to counts only if it is marked itself;
+        inside it, the planned asset folders are checked while they are
+        built, and the Realizer checks the rest before removing anything.
+        In a folder no source movie maps to, a marker at any depth counts,
+        so that the folder is not reported as a stray."""
+        if not target_root.is_dir():
+            return []
+        found: list[pathlib.Path] = []
+        for entry in sorted(target_root.iterdir()):
+            if not entry.is_dir():
+                continue
+            if entry.name in mapped:
+                if is_marked(entry):
+                    found.append(entry)
+            else:
+                found.extend(find_marked(entry))
+        return found
+
     def _group_candidates(
         self,
         source_root: pathlib.Path,
         ignored: list[IgnoredEntry],
+        marked: list[pathlib.Path],
     ) -> dict[str, list[_Candidate]]:
         """Run discovery + parse_movie, group surviving candidates by the
         target folder name the Writer would produce. Candidates whose
         folder name doesn't parse are added to `ignored`."""
         grouped: dict[str, list[_Candidate]] = defaultdict(list)
-        for group in self._discoverer.discover(source_root, ignored=ignored):
+        for group in self._discoverer.discover(source_root, ignored=ignored, marked=marked):
             # A discoverer that parsed names to find group boundaries
             # ships the identity with the group; only folder-based
             # discovery leaves the parsing to us.
@@ -163,6 +225,8 @@ class Planner:
         self,
         candidate: _Candidate,
         target_folder: pathlib.Path,
+        marked_src: list[pathlib.Path],
+        marked_tgt: list[pathlib.Path],
     ) -> tuple[PlannedMovie | None, list[MovieClash]]:
         videos_info = [(self._reader.parse_video(p), p) for p in candidate.group.video_files]
 
@@ -191,7 +255,11 @@ class Planner:
             PlannedFile(source=p, target_name=p.name) for p in candidate.group.loose_files
         )
 
-        planned_assets = tuple(self._build_planned_asset(p) for p in candidate.group.asset_dirs)
+        planned_assets: list[PlannedAsset] = []
+        for p in candidate.group.asset_dirs:
+            asset = self._build_planned_asset(p, target_folder / p.name, marked_src, marked_tgt)
+            if asset is not None:
+                planned_assets.append(asset)
 
         # All-clashes corner case: every video in this folder ended up
         # unresolved, and there's nothing else to sync. Returning None
@@ -206,7 +274,7 @@ class Planner:
             movie=candidate.movie,
             videos=planned_videos,
             loose_files=planned_loose,
-            assets=planned_assets,
+            assets=tuple(planned_assets),
             folder_drops=candidate.folder_drops,
             protected_files=tuple(c.target_filename for c in dis_result.unresolved),
         )
@@ -221,14 +289,35 @@ class Planner:
             for drop in pf.drops:
                 self._reporter.drop(drop)
 
-    def _build_planned_asset(self, asset_dir: pathlib.Path) -> PlannedAsset:
+    def _build_planned_asset(
+        self,
+        asset_dir: pathlib.Path,
+        target_dir: pathlib.Path,
+        marked_src: list[pathlib.Path],
+        marked_tgt: list[pathlib.Path],
+    ) -> PlannedAsset | None:
+        """Plan one source asset folder into `target_dir`, recursively.
+        None if `target_dir` is marked: nothing gets written into it.
+        Marked source subfolders are left out and recorded."""
+        if is_marked(target_dir):
+            marked_tgt.append(target_dir)
+            return None
         files: list[PlannedFile] = []
         subfolders: list[PlannedAsset] = []
         for child in sorted(asset_dir.glob("*")):
             if child.name.startswith("."):
                 continue
-            if child.is_dir():
-                subfolders.append(self._build_planned_asset(child))
+            if child.is_dir() and is_marked(child):
+                marked_src.append(child)
+            elif child.is_dir():
+                sub = self._build_planned_asset(
+                    child,
+                    target_dir / child.name,
+                    marked_src,
+                    marked_tgt,
+                )
+                if sub is not None:
+                    subfolders.append(sub)
             elif child.is_file():
                 files.append(PlannedFile(source=child, target_name=child.name))
         return PlannedAsset(

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/realize.py

@@ -13,13 +13,42 @@ import pathlib
 from dataclasses import dataclass, field
 
 from . import utils
-from .library import FileEvent
+from .library import IGNORE_MARKER, FileEvent, find_marked
 from .materializer import FileMaterializer, HardlinkMaterializer
 from .plan import Plan, PlannedAsset, PlannedFile, PlannedMovie
 
 log = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True)
+class _MarkerGuard:
+    """Keeps every removal away from marked target folders."""
+
+    target_root: pathlib.Path
+    marked: frozenset[pathlib.Path]
+
+    def keeps(self, entry: pathlib.Path) -> bool:
+        """True if removing `entry` would remove a marked folder."""
+        if entry in self.marked:
+            # Listed in the Plan and reported with the summary.
+            return True
+        # A symlink is only unlinked; whatever it points to stays.
+        found = [] if entry.is_symlink() else find_marked(entry)
+        if not found:
+            return False
+        rel = entry.relative_to(self.target_root)
+        if found[0] == entry:
+            log.info("Keeping '%s', it contains %s", rel, IGNORE_MARKER)
+        else:
+            log.info(
+                "Keeping '%s', '%s' in it contains %s",
+                rel,
+                found[0].relative_to(entry),
+                IGNORE_MARKER,
+            )
+        return True
+
+
 @dataclass
 class RealizeStats:
     """Aggregate counters and events from one Realizer.apply() call.
@@ -53,7 +82,10 @@ class Realizer:
             raise ValueError(f"Target directory '{plan.target_root}' does not exist")
 
         stats = stats or RealizeStats()
+        if plan.locked_root is not None:
+            return stats
         stats.ignored_count += len(plan.ignored)
+        guard = _MarkerGuard(plan.target_root, frozenset(plan.marked_in_target))
 
         for movie in plan.movies:
             self._realize_movie(
@@ -62,6 +94,7 @@ class Realizer:
                 delete=delete,
                 verbose=verbose,
                 stats=stats,
+                guard=guard,
             )
             stats.movies_processed += 1
 
@@ -71,8 +104,12 @@ class Realizer:
         # dry-run output without the planned folder masking it).
         # Folders of clash-skipped movies are not strays: they belong to a
         # source movie, so "skipped" must mean their target stays untouched.
+        # The same holds for folders that are marked or hold a marked folder.
         planned_folder_names = {m.target_folder.name for m in plan.movies}
         protected_folder_names = set(plan.protected_folders)
+        protected_folder_names.update(
+            p.relative_to(plan.target_root).parts[0] for p in plan.marked_in_target
+        )
         for entry in sorted(plan.target_root.iterdir()):
             if entry.name in planned_folder_names:
                 continue
@@ -85,6 +122,7 @@ class Realizer:
                     dry_run=dry_run,
                     context="library_stray",
                     stats=stats,
+                    guard=guard,
                 )
 
         return stats
@@ -101,6 +139,7 @@ class Realizer:
         delete: bool,
         verbose: bool,
         stats: RealizeStats,
+        guard: _MarkerGuard,
     ) -> None:
         self._ensure_dir(movie.target_folder, dry_run=dry_run)
 
@@ -131,6 +170,7 @@ class Realizer:
                     dry_run=dry_run,
                     context="movie_stray",
                     stats=stats,
+                    guard=guard,
                 )
 
         for asset in movie.assets:
@@ -141,6 +181,7 @@ class Realizer:
                 delete=delete,
                 verbose=verbose,
                 stats=stats,
+                guard=guard,
             )
 
     def _realize_asset(
@@ -152,6 +193,7 @@ class Realizer:
         delete: bool,
         verbose: bool,
         stats: RealizeStats,
+        guard: _MarkerGuard,
     ) -> None:
         self._ensure_dir(target_path, dry_run=dry_run)
 
@@ -170,6 +212,7 @@ class Realizer:
                     dry_run=dry_run,
                     context="asset_stray",
                     stats=stats,
+                    guard=guard,
                 )
 
         for subfolder in asset.subfolders:
@@ -180,6 +223,7 @@ class Realizer:
                 delete=delete,
                 verbose=verbose,
                 stats=stats,
+                guard=guard,
             )
 
     def _materialize_file(
@@ -215,7 +259,10 @@ class Realizer:
         dry_run: bool,
         context: str,
         stats: RealizeStats,
+        guard: _MarkerGuard,
     ) -> None:
+        if guard.keeps(entry):
+            return
         if dry_run:
             log.info("DELETE %s", entry)
         else:

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/report.py

@@ -10,7 +10,7 @@ import pathlib
 from typing import TextIO
 
 from .compare import DiffResult
-from .library import Drop, dedupe_drops
+from .library import IGNORE_MARKER, Drop, dedupe_drops
 from .plan import Plan, PlannedAsset, collect_drops
 
 
@@ -60,6 +60,14 @@ def print_diff(
             print(f"  ! '{i.path.name}': {i.reason}", file=out)
         print(file=out)
 
+    _print_marked(
+        result.marked_in_source,
+        result.marked_in_target,
+        source_path.resolve(),
+        target_path.resolve(),
+        out,
+    )
+
     if not result.has_differences:
         print("In sync. No differences found.", file=out)
 
@@ -73,6 +81,15 @@ def print_plan(plan: Plan, out: TextIO) -> None:
     )
     print(file=out)
 
+    if plan.locked_root is not None:
+        side = "source" if plan.locked_root == plan.source_root else "target"
+        print(
+            f"Empty plan: the {side} library contains {IGNORE_MARKER}, a sync would "
+            "change nothing. Delete that file to include the library.",
+            file=out,
+        )
+        return
+
     if plan.movies:
         print(f"Movies ({len(plan.movies)}):", file=out)
         for m in plan.movies:
@@ -116,6 +133,14 @@ def print_plan(plan: Plan, out: TextIO) -> None:
             print(f"  ! '{i.path.name}': {i.reason}", file=out)
         print(file=out)
 
+    _print_marked(
+        plan.marked_in_source,
+        plan.marked_in_target,
+        plan.source_root,
+        plan.target_root,
+        out,
+    )
+
     if not (plan.movies or plan.folder_clashes or plan.clashes or plan.ignored):
         print("Empty plan. Nothing to sync.", file=out)
 
@@ -131,5 +156,23 @@ def _print_drops(drops: tuple[Drop, ...], out: TextIO) -> None:
     print(file=out)
 
 
+def _print_marked(
+    in_source: tuple[pathlib.Path, ...],
+    in_target: tuple[pathlib.Path, ...],
+    source_root: pathlib.Path,
+    target_root: pathlib.Path,
+    out: TextIO,
+) -> None:
+    count = len(in_source) + len(in_target)
+    if not count:
+        return
+    print(f"Skipped because they contain {IGNORE_MARKER} ({count}):", file=out)
+    for path in in_source:
+        print(f"  source '{path.relative_to(source_root)}'", file=out)
+    for path in in_target:
+        print(f"  target '{path.relative_to(target_root)}'", file=out)
+    print(file=out)
+
+
 def _count_asset_files(asset: PlannedAsset) -> int:
     return len(asset.files) + sum(_count_asset_files(sf) for sf in asset.subfolders)

{jellyplex_sync-0.4.0 → jellyplex_sync-0.5.0}/src/jellyplex_sync/sync.py

@@ -25,6 +25,7 @@ from .formats import guess_library_type as guess_library_type
 from .formats import resolve_endpoints
 from .json_output import write_diff_json, write_plan_json
 from .library import (
+    IGNORE_MARKER,
     Drop,
     FileEvent,
     IgnoredEntry,
@@ -32,9 +33,10 @@ from .library import (
     MovieClash,
     NullReporter,
     Reporter,
+    is_marked,
 )
 from .materializer import FileMaterializer, HardlinkMaterializer, MoveMaterializer
-from .plan import collect_drops
+from .plan import Plan, collect_drops
 from .planner import Planner
 from .realize import Realizer, RealizeStats
 from .report import print_diff, print_plan
@@ -60,6 +62,8 @@ class LibraryStats:
     strays_in_target: list[str] = field(default_factory=list)
     events: list[FileEvent] = field(default_factory=list)
     clashes: list[MovieClash] = field(default_factory=list)
+    marked_in_source: list[pathlib.Path] = field(default_factory=list)
+    marked_in_target: list[pathlib.Path] = field(default_factory=list)
 
 
 @dataclass
@@ -125,6 +129,19 @@ def sync(
             target_short.capitalize(),
         )
 
+    if _stop_at_marked_root(
+        source_reader.base_dir,
+        target_writer.base_dir,
+        lib_stats,
+        "synced",
+    ):
+        return SyncResult(
+            exit_code=_EXIT_OK,
+            source_format=source_short,
+            target_format=target_short,
+            stats=lib_stats,
+        )
+
     if not target_writer.base_dir.is_dir():
         if create:
             target_writer.base_dir.mkdir(parents=True)
@@ -210,6 +227,8 @@ def sync(
     lib_stats.strays_in_target.extend(realize_stats.strays_in_target)
     lib_stats.events.extend(realize_stats.events)
     lib_stats.clashes.extend(plan.clashes)
+    lib_stats.marked_in_source.extend(plan.marked_in_source)
+    lib_stats.marked_in_target.extend(plan.marked_in_target)
 
     ignored_count = len(lib_stats.ignored)
     stray_count = len(lib_stats.strays_in_target)
@@ -232,6 +251,8 @@ def sync(
         for item in lib_stats.ignored:
             log.info("  '%s' (%s)", item.path.name, item.reason)
 
+    _log_marked(plan, verbose=verbose)
+
     if strays_kept:
         log.warning(
             "%d item(s) in target are not in the source library. "
@@ -278,8 +299,9 @@ def diff(
 
     Read-only: never touches the filesystem. Exit codes follow the Unix
     `diff` convention — 0 if no differences, 1 if differences are found,
-    2 if there's a setup error. With `as_json=True`, emits the machine-
-    readable JSON document instead of the human-readable text report.
+    2 if there's a setup error or a library root contains the ignore
+    marker. With `as_json=True`, emits the machine-readable JSON document
+    instead of the human-readable text report.
     """
     stream: TextIO = out if out is not None else sys.stdout
     source_path = pathlib.Path(source)
@@ -293,6 +315,21 @@ def diff(
         log.error("Target directory '%s' does not exist", endpoints.target_writer.base_dir)
         return 2
 
+    marked = _find_marked_root(
+        endpoints.source_reader.base_dir,
+        endpoints.target_writer.base_dir,
+    )
+    if marked is not None:
+        side, root = marked
+        log.error(
+            "Not compared: the %s library '%s' contains %s. Delete that file to include "
+            "the library",
+            side,
+            root,
+            IGNORE_MARKER,
+        )
+        return 2
+
     # 0.3 pipeline: Planner.plan() + compare(plan). The Plan records the
     # translation drops itself, so compare() carries them into the
     # DiffResult — no reporter side-channel needed.
@@ -415,6 +452,19 @@ def import_media(
             target_short.capitalize(),
         )
 
+    if _stop_at_marked_root(
+        source_reader.base_dir,
+        target_writer.base_dir,
+        lib_stats,
+        "imported",
+    ):
+        return SyncResult(
+            exit_code=_EXIT_OK,
+            source_format=source_short,
+            target_format=target_short,
+            stats=lib_stats,
+        )
+
     if not target_writer.base_dir.is_dir():
         if create:
             target_writer.base_dir.mkdir(parents=True)
@@ -450,6 +500,8 @@ def import_media(
     lib_stats.ignored.extend(plan.ignored)
     lib_stats.events.extend(realize_stats.events)
     lib_stats.clashes.extend(plan.clashes)
+    lib_stats.marked_in_source.extend(plan.marked_in_source)
+    lib_stats.marked_in_target.extend(plan.marked_in_target)
 
     verb = "moved" if isinstance(materializer, MoveMaterializer) else "copied"
     summary = (
@@ -465,6 +517,8 @@ def import_media(
         for item in lib_stats.ignored:
             log.info("  '%s' (%s)", item.path.name, item.reason)
 
+    _log_marked(plan, verbose=verbose)
+
     if lib_stats.clashes:
         log.warning(
             "%d movie(s) skipped because two or more source files map to the "
@@ -479,3 +533,61 @@ def import_media(
         stats=lib_stats,
         drops=collect_drops(plan),
     )
+
+
+def _find_marked_root(
+    source_root: pathlib.Path,
+    target_root: pathlib.Path,
+) -> tuple[str, pathlib.Path] | None:
+    """The first library root that contains the ignore marker, with the
+    side it is on."""
+    for side, root in (("source", source_root), ("target", target_root)):
+        if is_marked(root):
+            return side, root
+    return None
+
+
+def _stop_at_marked_root(
+    source_root: pathlib.Path,
+    target_root: pathlib.Path,
+    stats: LibraryStats,
+    verb: str,
+) -> bool:
+    """Check both library roots for the ignore marker before anything is
+    scanned or created. A marked root stops the run; it is recorded in
+    `stats` and reported. Returns True if the run has to stop."""
+    marked = _find_marked_root(source_root, target_root)
+    if marked is None:
+        return False
+    side, root = marked
+    if side == "source":
+        stats.marked_in_source.append(root)
+    else:
+        stats.marked_in_target.append(root)
+    log.warning(
+        "Nothing was %s: the %s library '%s' contains %s. Delete that file to include "
+        "the library",
+        verb,
+        side,
+        root,
+        IGNORE_MARKER,
+    )
+    return True
+
+
+def _log_marked(plan: Plan, *, verbose: bool) -> None:
+    count = len(plan.marked_in_source) + len(plan.marked_in_target)
+    if not count:
+        return
+    if not verbose:
+        log.info(
+            "%d folder(s) skipped because they contain %s. Pass --verbose to list them",
+            count,
+            IGNORE_MARKER,
+        )
+        return
+    log.info("%d folder(s) skipped because they contain %s:", count, IGNORE_MARKER)
+    for path in plan.marked_in_source:
+        log.info("  source '%s'", path.relative_to(plan.source_root))
+    for path in plan.marked_in_target:
+        log.info("  target '%s'", path.relative_to(plan.target_root))