feat: split --write-metadata into xmp/exif variants

Add --write-metadata-xmp and --write-metadata-exif for independent
control of XMP sidecar generation and EXIF tag writing.

--write-metadata remains as shorthand for both. All three flags
accept category lists: all, rating, keywords, title, datetime,
dates, orientation, location. Omitting value defaults to 'all'.

New categories:
- datetime: DateTimeOriginal + CreateDate
- dates: datetime + ModifyDate (superset)

Deprecations (still functional, with warnings):
- --xmp-sidecar -> --write-metadata-xmp
- --set-exif-datetime -> --write-metadata-exif datetime

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: teh-hippo

src/icloudpd/base.py

@@ -291,8 +291,8 @@ def run_with_configs(global_config: GlobalConfig, user_configs: Sequence[UserCon
     # Create shared logger
     logger = create_logger(global_config)
 
-    # Check exiftool availability if any user has --write-metadata
-    if any(uc.write_metadata for uc in user_configs):
+    # Check exiftool availability if any user has --write-metadata-exif
+    if any(uc.write_metadata_exif for uc in user_configs):
         from icloudpd.metadata_writer import ExiftoolNotFoundError, check_exiftool
         try:
             ver = check_exiftool()
@@ -473,12 +473,12 @@ def password_provider(_username: str) -> str | None:
                     user_config.force_size,
                     global_config.only_print_filenames,
                     user_config.set_exif_datetime,
-                    user_config.write_metadata,
+                    user_config.write_metadata_exif,
                     user_config.skip_live_photos,
                     user_config.live_photo_size,
                     user_config.dry_run,
                     user_config.file_match_policy,
-                    user_config.xmp_sidecar,
+                    user_config.write_metadata_xmp,
                     lp_filename_generator,
                     filename_builder,
                     user_config.align_raw,
@@ -890,12 +890,12 @@ def download_builder(
     force_size: bool,
     only_print_filenames: bool,
     set_exif_datetime: bool,
-    write_metadata_config: frozenset[str],
+    write_metadata_exif: frozenset[str],
     skip_live_photos: bool,
     live_photo_size: LivePhotoVersionSize,
     dry_run: bool,
     file_match_policy: FileMatchPolicy,
-    xmp_sidecar: bool,
+    write_metadata_xmp: frozenset[str],
     lp_filename_generator: Callable[[str], str],
     filename_builder: Callable[[PhotoAsset], str],
     raw_policy: RawTreatmentPolicy,
@@ -1144,10 +1144,10 @@ def download_builder(
                             )
                     logger.info("Downloaded %s", truncated_path)
 
-        if xmp_sidecar:
-            generate_xmp_file(logger, download_path, photo._asset_record, dry_run, dir_cache)
+        if write_metadata_xmp:
+                        generate_xmp_file(logger, download_path, photo._asset_record, dry_run, dir_cache)
 
-        if write_metadata_config:
+        if write_metadata_exif:
             # Skip in-file metadata for videos — XMP sidecar is the canonical source.
             # QuickTime Keys metadata is redundant when the sidecar exists.
             if os.path.splitext(download_path.lower())[1] not in (".mov", ".mp4", ".m4v", ".avi"):

src/icloudpd/cli.py

@@ -34,7 +34,7 @@ def map_align_raw_to_enum(align_raw_str: str) -> RawTreatmentPolicy:
     return mapping[align_raw_str]
 
 
-_VALID_WRITE_METADATA = {"all", "rating", "keywords", "title", "dates", "datetime", "orientation", "location"}
+_VALID_WRITE_METADATA = {"all", "rating", "keywords", "title", "dates", "orientation", "location", "datetime"}
 
 
 def _parse_write_metadata(value: str | None) -> frozenset[str]:
@@ -161,11 +161,40 @@ def add_options_for_user(parser: argparse.ArgumentParser) -> argparse.ArgumentPa
     cloned.add_argument(
         "--write-metadata",
         help=(
-            "Write iCloud metadata into file EXIF/XMP using exiftool. "
+            "Write iCloud metadata as both XMP sidecars and EXIF tags. "
+            "Shorthand for --write-metadata-xmp and --write-metadata-exif. "
             "Comma-separated list of field categories: "
-            "all, rating, keywords, title, dates, orientation. "
-            "Requires exiftool to be installed. Default: disabled."
+            "all, rating, keywords, title, datetime, dates, orientation, location. "
+            "Requires exiftool to be installed. "
+            "Default when specified without value: all."
         ),
+        nargs="?",
+        const="all",
+        default=None,
+    )
+    cloned.add_argument(
+        "--write-metadata-xmp",
+        help=(
+            "Write iCloud metadata as XMP sidecar files. "
+            "Comma-separated list of field categories: "
+            "all, rating, keywords, title, datetime, dates, orientation, location. "
+            "Default when specified without value: all."
+        ),
+        nargs="?",
+        const="all",
+        default=None,
+    )
+    cloned.add_argument(
+        "--write-metadata-exif",
+        help=(
+            "Write iCloud metadata into file EXIF/XMP tags using exiftool. "
+            "Comma-separated list of field categories: "
+            "all, rating, keywords, title, datetime, dates, orientation, location. "
+            "Requires exiftool to be installed. "
+            "Default when specified without value: all."
+        ),
+        nargs="?",
+        const="all",
         default=None,
     )
 
@@ -456,6 +485,37 @@ def format_help() -> str:
 
 
 def map_to_config(user_ns: argparse.Namespace) -> UserConfig:
+    # Resolve write-metadata flags
+    write_metadata_base = _parse_write_metadata(user_ns.write_metadata)
+    write_metadata_xmp = _parse_write_metadata(user_ns.write_metadata_xmp)
+    write_metadata_exif = _parse_write_metadata(user_ns.write_metadata_exif)
+
+    # --write-metadata sets both if specific variants not given
+    if write_metadata_base:
+        if not write_metadata_xmp:
+            write_metadata_xmp = write_metadata_base
+        if not write_metadata_exif:
+            write_metadata_exif = write_metadata_base
+
+    # --xmp-sidecar is deprecated alias for --write-metadata-xmp all
+    if user_ns.xmp_sidecar:
+        import logging
+
+        logging.getLogger("icloudpd").warning(
+            "--xmp-sidecar is deprecated, use --write-metadata-xmp instead"
+        )
+        if not write_metadata_xmp:
+            write_metadata_xmp = frozenset({"all"})
+
+    # --set-exif-datetime adds datetime to exif set
+    if user_ns.set_exif_datetime:
+        import logging
+
+        logging.getLogger("icloudpd").warning(
+            "--set-exif-datetime is deprecated, use --write-metadata-exif datetime instead"
+        )
+        write_metadata_exif = write_metadata_exif | frozenset({"datetime"})
+
     return UserConfig(
         username=user_ns.username,
         password=user_ns.password,
@@ -474,12 +534,12 @@ def map_to_config(user_ns: argparse.Namespace) -> UserConfig:
         list_libraries=user_ns.list_libraries,
         skip_videos=user_ns.skip_videos,
         skip_live_photos=user_ns.skip_live_photos,
-        xmp_sidecar=user_ns.xmp_sidecar,
         force_size=user_ns.force_size,
         auto_delete=user_ns.auto_delete,
         folder_structure=user_ns.folder_structure,
         set_exif_datetime=user_ns.set_exif_datetime,
-        write_metadata=_parse_write_metadata(user_ns.write_metadata),
+        write_metadata_xmp=write_metadata_xmp,
+        write_metadata_exif=write_metadata_exif,
         smtp_username=user_ns.smtp_username,
         smtp_password=user_ns.smtp_password,
         smtp_host=user_ns.smtp_host,

src/icloudpd/config.py

@@ -27,12 +27,12 @@ class _DefaultConfig:
     list_libraries: bool
     skip_videos: bool
     skip_live_photos: bool
-    xmp_sidecar: bool
     force_size: bool
     auto_delete: bool
     folder_structure: str
     set_exif_datetime: bool
-    write_metadata: frozenset[str]
+    write_metadata_xmp: frozenset[str]
+    write_metadata_exif: frozenset[str]
     smtp_username: str | None
     smtp_password: str | None
     smtp_host: str

tests/test_cli.py

@@ -211,12 +211,12 @@ def test_cli_parser(self) -> None:
                         list_libraries=False,
                         skip_videos=False,
                         skip_live_photos=False,
-                        xmp_sidecar=False,
                         force_size=False,
                         auto_delete=False,
                         folder_structure="{:%Y/%m/%d}",
                         set_exif_datetime=False,
-                        write_metadata=frozenset(),
+                        write_metadata_xmp=frozenset(),
+                        write_metadata_exif=frozenset(),
                         smtp_username=None,
                         smtp_password=None,
                         smtp_host="smtp.gmail.com",
@@ -252,12 +252,12 @@ def test_cli_parser(self) -> None:
                         list_libraries=False,
                         skip_videos=False,
                         skip_live_photos=False,
-                        xmp_sidecar=False,
                         force_size=False,
                         auto_delete=False,
                         folder_structure="{:%Y/%m/%d}",
                         set_exif_datetime=False,
-                        write_metadata=frozenset(),
+                        write_metadata_xmp=frozenset(),
+                        write_metadata_exif=frozenset(),
                         smtp_username=None,
                         smtp_password=None,
                         smtp_host="smtp.gmail.com",
@@ -329,12 +329,12 @@ def test_cli_parser(self) -> None:
                         list_libraries=False,
                         skip_videos=False,
                         skip_live_photos=False,
-                        xmp_sidecar=False,
                         force_size=False,
                         auto_delete=False,
                         folder_structure="{:%Y/%m/%d}",
                         set_exif_datetime=False,
-                        write_metadata=frozenset(),
+                        write_metadata_xmp=frozenset(),
+                        write_metadata_exif=frozenset(),
                         smtp_username=None,
                         smtp_password=None,
                         smtp_host="smtp.gmail.com",