From f25a2993097ad7b2b8ab2d1c787db58c0d799a41 Mon Sep 17 00:00:00 2001
From: Rhet Turnbull <rturnbull+git@gmail.com>
Date: Wed, 30 Dec 2020 08:51:01 -0800
Subject: [PATCH] Updated README for finder tags

---
 README.md             | 32 ++++++++++++++++++++++++++++++++
 osxphotos/__main__.py | 22 ++++++++++++++++++++--
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 9b09dac6..482088f0 100644
--- a/README.md
+++ b/README.md
@@ -412,6 +412,20 @@ Options:
                                   could specify --description-template
                                   "{descr} exported with osxphotos on
                                   {today.date}" See Templating System below.
+  --finder-tag-template TEMPLATE  Set Finder tags to TEMPLATE. These tags can
+                                  be searched in the Finder or Spotlight with
+                                  'tag:tagname' format. For example, '--
+                                  finder-tag-template "{label}"' to set Finder
+                                  tags to photo labels. You may specify
+                                  multiple TEMPLATE values by using '--finder-
+                                  tag-template' multiple times. See also '--
+                                  finder-tag-keywords and Extended Attributes
+                                  below.'.
+  --finder-tag-keywords           Set Finder tags to keywords; any keywords
+                                  specified via '--keyword-template', '--
+                                  person-keyword', etc. will also be used as
+                                  Finder tags. See also '--finder-tag-template
+                                  and Extended Attributes below.'.
   --directory DIRECTORY           Optional template for specifying name of
                                   output directory in the form
                                   '{name,DEFAULT}'. See below for additional
@@ -514,6 +528,24 @@ option to re-export the entire library thus rebuilding the
 '.osxphotos_export.db' database.
 
 
+** Extended Attributes **
+
+Some options (currently '--finder-tag-template' and '--finder-tag-keywords')
+write additional metadata to extended attributes in the file. These options
+will only work if the destination filesystem supports extended attributes
+(most do). For example, --finder-tag-keyword writes all keywords (including
+any specified by '--keyword-template' or other options) to Finder tags that
+are searchable in Spotlight using the syntax: 'tag:tagname'. For example, if
+you have images with keyword "Travel" then using '--finder-tag-keywords' you
+could quickly find those images in the Finder by typing 'tag:Travel' in the
+Spotlight search bar. Finder tags are written to the
+'com.apple.metadata:_kMDItemUserTags' extended attribute. Unlike EXIF
+metadata, extended attributes do not modify the actual file. Most cloud
+storage services do not synch extended attributes. Dropbox does sync them and
+any changes to a file's extended attributes will cause Dropbox to re-sync the
+files.
+
+
 ** Templating System **
 
 Several options, such as --directory, allow you to specify a template  which
diff --git a/osxphotos/__main__.py b/osxphotos/__main__.py
index b0b4c0df..9d1f7e57 100644
--- a/osxphotos/__main__.py
+++ b/osxphotos/__main__.py
@@ -181,6 +181,24 @@ class ExportCommand(click.Command):
             + "You can always run export without the --update option to re-export the entire library thus "
             + f"rebuilding the '{OSXPHOTOS_EXPORT_DB}' database."
         )
+        formatter.write("\n\n")
+        formatter.write_text("** Extended Attributes **")
+        formatter.write("\n")
+        formatter.write_text(
+            """
+Some options (currently '--finder-tag-template' and '--finder-tag-keywords') write
+additional metadata to extended attributes in the file. These options will only work
+if the destination filesystem supports extended attributes (most do).
+For example, --finder-tag-keyword writes all keywords (including any specified by '--keyword-template'
+or other options) to Finder tags that are searchable in Spotlight using the syntax: 'tag:tagname'.
+For example, if you have images with keyword "Travel" then using '--finder-tag-keywords' you could quickly
+find those images in the Finder by typing 'tag:Travel' in the Spotlight search bar.
+Finder tags are written to the 'com.apple.metadata:_kMDItemUserTags' extended attribute.
+Unlike EXIF metadata, extended attributes do not modify the actual file. Most cloud storage services
+do not synch extended attributes. Dropbox does sync them and any changes to a file's extended attributes
+will cause Dropbox to re-sync the files.
+            """
+        )
 
         formatter.write("\n\n")
         formatter.write_text("** Templating System **")
@@ -1464,13 +1482,13 @@ def query(
     help="Set Finder tags to TEMPLATE. These tags can be searched in the Finder or Spotlight with "
     "'tag:tagname' format. For example, '--finder-tag-template \"{label}\"' to set Finder tags to photo labels. "
     "You may specify multiple TEMPLATE values by using '--finder-tag-template' multiple times. "
-    "See also '--finder-tag-keywords'.",
+    "See also '--finder-tag-keywords and Extended Attributes below.'.",
 )
 @click.option(
     "--finder-tag-keywords",
     is_flag=True,
     help="Set Finder tags to keywords; any keywords specified via '--keyword-template', '--person-keyword', etc. "
-    "will also be used as Finder tags. See also '--finder-tag-template'.",
+    "will also be used as Finder tags. See also '--finder-tag-template and Extended Attributes below.'.",
 )
 @click.option(
     "--directory",