forked/osxphotos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

README.md update [skip ci]

Browse Source
This commit is contained in:
Rhet Turnbull
2021-05-22 10:31:52 -07:00
parent 9f2268fb2b
commit 96037508c1
1 changed files with 12 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
README.md
View File

@@ -527,13 +527,13 @@ osxphotos is very flexible. If you merely want to backup your Photos library, t
Usage: osxphotos export [OPTIONS] [PHOTOS_LIBRARY]... DEST Usage: osxphotos export [OPTIONS] [PHOTOS_LIBRARY]... DEST
Export photos from the Photos database. Export path DEST is required. Export photos from the Photos database. Export path DEST is required.
Optionally, query the Photos database using 1 or more search options; if Optionally, query the Photos database using 1 or more search options; if more
more than one option is provided, they are treated as "AND" (e.g. search for than one option is provided, they are treated as "AND" (e.g. search for photos
photos matching all options). If no query options are provided, all photos matching all options). If no query options are provided, all photos will be
will be exported. By default, all versions of all photos will be exported exported. By default, all versions of all photos will be exported including
including edited versions, live photo movies, burst photos, and associated edited versions, live photo movies, burst photos, and associated raw images.
raw images. See --skip-edited, --skip-live, --skip-bursts, and --skip-raw See --skip-edited, --skip-live, --skip-bursts, and --skip-raw options to
options to modify this behavior. modify this behavior.
Options: Options:
--db <Photos database path> Specify Photos database path. Path to Photos --db <Photos database path> Specify Photos database path. Path to Photos
@@ -544,57 +544,45 @@ Options:
use in the following order: 1. last opened use in the following order: 1. last opened
library, 2. system library, 3. library, 2. system library, 3.
~/Pictures/Photos Library.photoslibrary ~/Pictures/Photos Library.photoslibrary
-V, --verbose Print verbose output. -V, --verbose Print verbose output.
--keyword KEYWORD Search for photos with keyword KEYWORD. If --keyword KEYWORD Search for photos with keyword KEYWORD. If
more than one keyword, treated as "OR", e.g. more than one keyword, treated as "OR", e.g.
find photos matching any keyword find photos matching any keyword
--person PERSON Search for photos with person PERSON. If more --person PERSON Search for photos with person PERSON. If more
than one person, treated as "OR", e.g. find than one person, treated as "OR", e.g. find
photos matching any person photos matching any person
--album ALBUM Search for photos in album ALBUM. If more than --album ALBUM Search for photos in album ALBUM. If more than
one album, treated as "OR", e.g. find photos one album, treated as "OR", e.g. find photos
matching any album matching any album
--folder FOLDER Search for photos in an album in folder --folder FOLDER Search for photos in an album in folder
FOLDER. If more than one folder, treated as FOLDER. If more than one folder, treated as
"OR", e.g. find photos in any FOLDER. Only "OR", e.g. find photos in any FOLDER. Only
searches top level folders (e.g. does not look searches top level folders (e.g. does not look
at subfolders) at subfolders)
--name FILENAME Search for photos with filename matching --name FILENAME Search for photos with filename matching
FILENAME. If more than one --name options is FILENAME. If more than one --name options is
specified, they are treated as "OR", e.g. find specified, they are treated as "OR", e.g. find
photos matching any FILENAME. photos matching any FILENAME.
--uuid UUID Search for photos with UUID(s). --uuid UUID Search for photos with UUID(s).
--uuid-from-file FILE Search for photos with UUID(s) loaded from --uuid-from-file FILE Search for photos with UUID(s) loaded from
FILE. Format is a single UUID per line. Lines FILE. Format is a single UUID per line. Lines
preceded with # are ignored. preceded with # are ignored.
--title TITLE Search for TITLE in title of photo. --title TITLE Search for TITLE in title of photo.
--no-title Search for photos with no title. --no-title Search for photos with no title.
--description DESC Search for DESC in description of photo. --description DESC Search for DESC in description of photo.
--no-description Search for photos with no description. --no-description Search for photos with no description.
--place PLACE Search for PLACE in photo's reverse --place PLACE Search for PLACE in photo's reverse
geolocation info geolocation info
--no-place Search for photos with no associated place --no-place Search for photos with no associated place
name info (no reverse geolocation info) name info (no reverse geolocation info)
--label LABEL Search for photos with image classification --label LABEL Search for photos with image classification
label LABEL (Photos 5 only). If more than one label LABEL (Photos 5 only). If more than one
label, treated as "OR", e.g. find photos label, treated as "OR", e.g. find photos
matching any label matching any label
--uti UTI Search for photos whose uniform type --uti UTI Search for photos whose uniform type
identifier (UTI) matches UTI identifier (UTI) matches UTI
-i, --ignore-case Case insensitive search for title, -i, --ignore-case Case insensitive search for title,
description, place, keyword, person, or album. description, place, keyword, person, or album.
--edited Search for photos that have been edited. --edited Search for photos that have been edited.
--external-edit Search for photos edited in external editor. --external-edit Search for photos edited in external editor.
--favorite Search for photos marked favorite. --favorite Search for photos marked favorite.
@@ -603,67 +591,51 @@ Options:
--not-hidden Search for photos not marked hidden. --not-hidden Search for photos not marked hidden.
--shared Search for photos in shared iCloud album --shared Search for photos in shared iCloud album
(Photos 5 only). (Photos 5 only).
--not-shared Search for photos not in shared iCloud album --not-shared Search for photos not in shared iCloud album
(Photos 5 only). (Photos 5 only).
--burst Search for photos that were taken in a burst. --burst Search for photos that were taken in a burst.
--not-burst Search for photos that are not part of a --not-burst Search for photos that are not part of a
burst. burst.
--live Search for Apple live photos --live Search for Apple live photos
--not-live Search for photos that are not Apple live --not-live Search for photos that are not Apple live
photos. photos.
--portrait Search for Apple portrait mode photos. --portrait Search for Apple portrait mode photos.
--not-portrait Search for photos that are not Apple portrait --not-portrait Search for photos that are not Apple portrait
mode photos. mode photos.
--screenshot Search for screenshot photos. --screenshot Search for screenshot photos.
--not-screenshot Search for photos that are not screenshot --not-screenshot Search for photos that are not screenshot
photos. photos.
--slow-mo Search for slow motion videos. --slow-mo Search for slow motion videos.
--not-slow-mo Search for photos that are not slow motion --not-slow-mo Search for photos that are not slow motion
videos. videos.
--time-lapse Search for time lapse videos. --time-lapse Search for time lapse videos.
--not-time-lapse Search for photos that are not time lapse --not-time-lapse Search for photos that are not time lapse
videos. videos.
--hdr Search for high dynamic range (HDR) photos. --hdr Search for high dynamic range (HDR) photos.
--not-hdr Search for photos that are not HDR photos. --not-hdr Search for photos that are not HDR photos.
--selfie Search for selfies (photos taken with front- --selfie Search for selfies (photos taken with front-
facing cameras). facing cameras).
--not-selfie Search for photos that are not selfies. --not-selfie Search for photos that are not selfies.
--panorama Search for panorama photos. --panorama Search for panorama photos.
--not-panorama Search for photos that are not panoramas. --not-panorama Search for photos that are not panoramas.
--has-raw Search for photos with both a jpeg and raw --has-raw Search for photos with both a jpeg and raw
version version
--only-movies Search only for movies (default searches both --only-movies Search only for movies (default searches both
images and movies). images and movies).
--only-photos Search only for photos/images (default --only-photos Search only for photos/images (default
searches both images and movies). searches both images and movies).
--from-date DATETIME Search by item start date, e.g. --from-date DATETIME Search by item start date, e.g.
2000-01-12T12:00:00, 2000-01-12T12:00:00,
2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO
8601 with/without timezone). 8601 with/without timezone).
--to-date DATETIME Search by item end date, e.g. --to-date DATETIME Search by item end date, e.g.
2000-01-12T12:00:00, 2000-01-12T12:00:00,
2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO
8601 with/without timezone). 8601 with/without timezone).
--from-time TIME Search by item start time of day, e.g. 12:00, --from-time TIME Search by item start time of day, e.g. 12:00,
or 12:00:00. or 12:00:00.
--to-time TIME Search by item end time of day, e.g. 12:00 or --to-time TIME Search by item end time of day, e.g. 12:00 or
12:00:00. 12:00:00.
--has-comment Search for photos that have comments. --has-comment Search for photos that have comments.
--no-comment Search for photos with no comments. --no-comment Search for photos with no comments.
--has-likes Search for photos that have likes. --has-likes Search for photos that have likes.
@@ -671,10 +643,8 @@ Options:
--is-reference Search for photos that were imported as --is-reference Search for photos that were imported as
referenced files (not copied into Photos referenced files (not copied into Photos
library). library).
--in-album Search for photos that are in one or more --in-album Search for photos that are in one or more
albums. albums.
--not-in-album Search for photos that are not in any albums. --not-in-album Search for photos that are not in any albums.
--min-size SIZE Search for photos with size >= SIZE bytes. The --min-size SIZE Search for photos with size >= SIZE bytes. The
size evaluated is the photo's original size size evaluated is the photo's original size
@@ -683,7 +653,6 @@ Options:
units. For example, the following are all units. For example, the following are all
valid and equivalent sizes: '1048576' valid and equivalent sizes: '1048576'
'1.048576MB', '1 MiB'. '1.048576MB', '1 MiB'.
--max-size SIZE Search for photos with size <= SIZE bytes. The --max-size SIZE Search for photos with size <= SIZE bytes. The
size evaluated is the photo's original size size evaluated is the photo's original size
(when imported to Photos). Size may be (when imported to Photos). Size may be
@@ -691,14 +660,12 @@ Options:
units. For example, the following are all units. For example, the following are all
valid and equivalent sizes: '1048576' valid and equivalent sizes: '1048576'
'1.048576MB', '1 MiB'. '1.048576MB', '1 MiB'.
--regex REGEX TEMPLATE Search for photos where TEMPLATE matches --regex REGEX TEMPLATE Search for photos where TEMPLATE matches
regular expression REGEX. For example, to find regular expression REGEX. For example, to find
photos in an album that begins with 'Beach': ' photos in an album that begins with 'Beach': '
--regex "^Beach" "{album}"'. You may specify --regex "^Beach" "{album}"'. You may specify
more than one regular expression match by more than one regular expression match by
repeating '--regex' with different arguments. repeating '--regex' with different arguments.
--query-eval CRITERIA Evaluate CRITERIA to filter photos. CRITERIA --query-eval CRITERIA Evaluate CRITERIA to filter photos. CRITERIA
will be evaluated in context of the following will be evaluated in context of the following
python list comprehension: `photos = [photo python list comprehension: `photos = [photo
@@ -713,19 +680,14 @@ Options:
https://rhettbull.github.io/osxphotos/ for https://rhettbull.github.io/osxphotos/ for
additional documentation on the PhotoInfo additional documentation on the PhotoInfo
class. class.
--missing Export only photos missing from the Photos --missing Export only photos missing from the Photos
library; must be used with --download-missing. library; must be used with --download-missing.
--deleted Include photos from the 'Recently Deleted' --deleted Include photos from the 'Recently Deleted'
folder. folder.
--deleted-only Include only photos from the 'Recently --deleted-only Include only photos from the 'Recently
Deleted' folder. Deleted' folder.
--update Only export new or updated files. See notes --update Only export new or updated files. See notes
below on export and --update. below on export and --update.
--ignore-signature When used with '--update', ignores file --ignore-signature When used with '--update', ignores file
signature when updating files. This is useful signature when updating files. This is useful
if you have processed or edited exported if you have processed or edited exported
@@ -744,15 +706,12 @@ Options:
not; 3) if a sidecar does not exist for the not; 3) if a sidecar does not exist for the
photo, a sidecar will be written whether or photo, a sidecar will be written whether or
not the photo file was written or updated. not the photo file was written or updated.
--only-new If used with --update, ignores any previously --only-new If used with --update, ignores any previously
exported files, even if missing from the exported files, even if missing from the
export folder and only exports new files that export folder and only exports new files that
haven't previously been exported. haven't previously been exported.
--dry-run Dry run (test) the export but don't actually --dry-run Dry run (test) the export but don't actually
export any files; most useful with --verbose. export any files; most useful with --verbose.
--export-as-hardlink Hardlink files instead of copying them. Cannot --export-as-hardlink Hardlink files instead of copying them. Cannot
be used with --exiftool which creates copies be used with --exiftool which creates copies
of the files with embedded EXIF data. Note: on of the files with embedded EXIF data. Note: on
@@ -760,58 +719,45 @@ Options:
giving many of the same advantages as giving many of the same advantages as
hardlinks without having to use --export-as- hardlinks without having to use --export-as-
hardlink. hardlink.
--touch-file Sets the file's modification time to match --touch-file Sets the file's modification time to match
photo date. photo date.
--overwrite Overwrite existing files. Default behavior is --overwrite Overwrite existing files. Default behavior is
to add (1), (2), etc to filename if file to add (1), (2), etc to filename if file
already exists. Use this with caution as it already exists. Use this with caution as it
may create name collisions on export. (e.g. if may create name collisions on export. (e.g. if
two files happen to have the same name) two files happen to have the same name)
--retry RETRY Automatically retry export up to RETRY times --retry RETRY Automatically retry export up to RETRY times
if an error occurs during export. This may be if an error occurs during export. This may be
useful with network drives that experience useful with network drives that experience
intermittent errors. intermittent errors.
--export-by-date Automatically create output folders to --export-by-date Automatically create output folders to
organize photos by date created (e.g. organize photos by date created (e.g.
DEST/2019/12/20/photoname.jpg). DEST/2019/12/20/photoname.jpg).
--skip-edited Do not export edited version of photo if an --skip-edited Do not export edited version of photo if an
edited version exists. edited version exists.
--skip-original-if-edited Do not export original if there is an edited --skip-original-if-edited Do not export original if there is an edited
version (exports only the edited version). version (exports only the edited version).
--skip-bursts Do not export all associated burst images in --skip-bursts Do not export all associated burst images in
the library if a photo is a burst photo. the library if a photo is a burst photo.
--skip-live Do not export the associated live video --skip-live Do not export the associated live video
component of a live photo. component of a live photo.
--skip-raw Do not export associated raw images of a --skip-raw Do not export associated raw images of a
RAW+JPEG pair. Note: this does not skip raw RAW+JPEG pair. Note: this does not skip raw
photos if the raw photo does not have an photos if the raw photo does not have an
associated jpeg image (e.g. the raw file was associated jpeg image (e.g. the raw file was
imported to Photos without a jpeg preview). imported to Photos without a jpeg preview).
--current-name Use photo's current filename instead of --current-name Use photo's current filename instead of
original filename for export. Note: Starting original filename for export. Note: Starting
with Photos 5, all photos are renamed upon with Photos 5, all photos are renamed upon
import. By default, photos are exported with import. By default, photos are exported with
the the original name they had before import. the the original name they had before import.
--convert-to-jpeg Convert all non-jpeg images (e.g. raw, HEIC, --convert-to-jpeg Convert all non-jpeg images (e.g. raw, HEIC,
PNG, etc) to JPEG upon export. Only works if PNG, etc) to JPEG upon export. Only works if
your Mac has a GPU. your Mac has a GPU.
--jpeg-quality FLOAT RANGE Value in range 0.0 to 1.0 to use with --jpeg-quality FLOAT RANGE Value in range 0.0 to 1.0 to use with
--convert-to-jpeg. A value of 1.0 specifies --convert-to-jpeg. A value of 1.0 specifies
best quality, a value of 0.0 specifies maximum best quality, a value of 0.0 specifies maximum
compression. Defaults to 1.0 compression. Defaults to 1.0 [0.0<=x<=1.0]
--download-missing Attempt to download missing photos from --download-missing Attempt to download missing photos from
iCloud. The current implementation uses iCloud. The current implementation uses
Applescript to interact with Photos to export Applescript to interact with Photos to export
@@ -824,7 +770,6 @@ Options:
export all burst images; only the primary export all burst images; only the primary
photo will be exported--associated burst photo will be exported--associated burst
images will be skipped. images will be skipped.
--sidecar FORMAT Create sidecar for each photo exported; valid --sidecar FORMAT Create sidecar for each photo exported; valid
FORMAT values: xmp, json, exiftool; --sidecar FORMAT values: xmp, json, exiftool; --sidecar
xmp: create XMP sidecar used by Digikam, Adobe xmp: create XMP sidecar used by Digikam, Adobe
@@ -851,7 +796,6 @@ Options:
tags exported in the JSON and exiftool tags exported in the JSON and exiftool
sidecar, see '--exiftool'. See also '--ignore- sidecar, see '--exiftool'. See also '--ignore-
signature'. signature'.
--sidecar-drop-ext Drop the photo's extension when naming sidecar --sidecar-drop-ext Drop the photo's extension when naming sidecar
files. By default, sidecar files are named in files. By default, sidecar files are named in
format 'photo_filename.photo_ext.sidecar_ext', format 'photo_filename.photo_ext.sidecar_ext',
@@ -863,7 +807,6 @@ Options:
of different types but the same name in the of different types but the same name in the
output directory, e.g. 'IMG_1234.JPG' and output directory, e.g. 'IMG_1234.JPG' and
'IMG_1234.MOV'. 'IMG_1234.MOV'.
--exiftool Use exiftool to write metadata directly to --exiftool Use exiftool to write metadata directly to
exported photos. To use this option, exiftool exported photos. To use this option, exiftool
must be installed and in the path. exiftool must be installed and in the path. exiftool
@@ -885,10 +828,8 @@ Options:
QuickTime:ModifyDate (see also --ignore-date- QuickTime:ModifyDate (see also --ignore-date-
modified); QuickTime:GPSCoordinates; modified); QuickTime:GPSCoordinates;
UserData:GPSCoordinates. UserData:GPSCoordinates.
--exiftool-path EXIFTOOL_PATH Optionally specify path to exiftool; if not --exiftool-path EXIFTOOL_PATH Optionally specify path to exiftool; if not
provided, will look for exiftool in $PATH. provided, will look for exiftool in $PATH.
--exiftool-option OPTION Optional flag/option to pass to exiftool when --exiftool-option OPTION Optional flag/option to pass to exiftool when
using --exiftool. For example, --exiftool- using --exiftool. For example, --exiftool-
option '-m' to ignore minor warnings. Specify option '-m' to ignore minor warnings. Specify
@@ -898,27 +839,21 @@ Options:
full list of options. More than one option may full list of options. More than one option may
be specified by repeating the option, e.g. be specified by repeating the option, e.g.
--exiftool-option '-m' --exiftool-option '-F'. --exiftool-option '-m' --exiftool-option '-F'.
--exiftool-merge-keywords Merge any keywords found in the original file --exiftool-merge-keywords Merge any keywords found in the original file
with keywords used for '--exiftool' and '-- with keywords used for '--exiftool' and '--
sidecar'. sidecar'.
--exiftool-merge-persons Merge any persons found in the original file --exiftool-merge-persons Merge any persons found in the original file
with persons used for '--exiftool' and '-- with persons used for '--exiftool' and '--
sidecar'. sidecar'.
--ignore-date-modified If used with --exiftool or --sidecar, will --ignore-date-modified If used with --exiftool or --sidecar, will
ignore the photo modification date and set ignore the photo modification date and set
EXIF:ModifyDate to EXIF:DateTimeOriginal; this EXIF:ModifyDate to EXIF:DateTimeOriginal; this
is consistent with how Photos handles the is consistent with how Photos handles the
EXIF:ModifyDate tag. EXIF:ModifyDate tag.
--person-keyword Use person in image as keyword/tag when --person-keyword Use person in image as keyword/tag when
exporting metadata. exporting metadata.
--album-keyword Use album name as keyword/tag when exporting --album-keyword Use album name as keyword/tag when exporting
metadata. metadata.
--keyword-template TEMPLATE For use with --exiftool, --sidecar; specify a --keyword-template TEMPLATE For use with --exiftool, --sidecar; specify a
template string to use as keyword in the form template string to use as keyword in the form
'{name,DEFAULT}' This is the same format as '{name,DEFAULT}' This is the same format as
@@ -931,7 +866,6 @@ Options:
"{folder_album}" --keyword-template "{folder_album}" --keyword-template
"{created.year}". See '--replace-keywords' and "{created.year}". See '--replace-keywords' and
Templating System below. Templating System below.
--replace-keywords Replace keywords with any values specified --replace-keywords Replace keywords with any values specified
with --keyword-template. By default, with --keyword-template. By default,
--keyword-template will add keywords to any --keyword-template will add keywords to any
@@ -940,7 +874,6 @@ Options:
from --keyword-template will replace any from --keyword-template will replace any
existing keywords instead of adding additional existing keywords instead of adding additional
keywords. keywords.
--description-template TEMPLATE --description-template TEMPLATE
For use with --exiftool, --sidecar; specify a For use with --exiftool, --sidecar; specify a
template string to use as description in the template string to use as description in the
@@ -951,7 +884,6 @@ Options:
--description-template "{descr} exported with --description-template "{descr} exported with
osxphotos on {today.date}" See Templating osxphotos on {today.date}" See Templating
System below. System below.
--finder-tag-template TEMPLATE Set MacOS Finder tags to TEMPLATE. These tags --finder-tag-template TEMPLATE Set MacOS Finder tags to TEMPLATE. These tags
can be searched in the Finder or Spotlight can be searched in the Finder or Spotlight
with 'tag:tagname' format. For example, '-- with 'tag:tagname' format. For example, '--
@@ -960,13 +892,11 @@ Options:
TEMPLATE values by using '--finder-tag- TEMPLATE values by using '--finder-tag-
template' multiple times. See also '--finder- template' multiple times. See also '--finder-
tag-keywords and Extended Attributes below.'. tag-keywords and Extended Attributes below.'.
--finder-tag-keywords Set MacOS Finder tags to keywords; any --finder-tag-keywords Set MacOS Finder tags to keywords; any
keywords specified via '--keyword-template', ' keywords specified via '--keyword-template', '
--person-keyword', etc. will also be used as --person-keyword', etc. will also be used as
Finder tags. See also '--finder-tag-template Finder tags. See also '--finder-tag-template
and Extended Attributes below.'. and Extended Attributes below.'.
--xattr-template ATTRIBUTE TEMPLATE --xattr-template ATTRIBUTE TEMPLATE
Set extended attribute ATTRIBUTE to TEMPLATE Set extended attribute ATTRIBUTE to TEMPLATE
value. Valid attributes are: 'authors', value. Valid attributes are: 'authors',
@@ -977,19 +907,16 @@ Options:
findercomment "{title}; {descr}" See Extended findercomment "{title}; {descr}" See Extended
Attributes below for additional details on Attributes below for additional details on
this option. this option.
--directory DIRECTORY Optional template for specifying name of --directory DIRECTORY Optional template for specifying name of
output directory in the form '{name,DEFAULT}'. output directory in the form '{name,DEFAULT}'.
See below for additional details on templating See below for additional details on templating
system. system.
--filename FILENAME Optional template for specifying name of --filename FILENAME Optional template for specifying name of
output file in the form '{name,DEFAULT}'. File output file in the form '{name,DEFAULT}'. File
extension will be added automatically--do not extension will be added automatically--do not
include an extension in the FILENAME template. include an extension in the FILENAME template.
See below for additional details on templating See below for additional details on templating
system. system.
--jpeg-ext EXTENSION Specify file extension for JPEG files. Photos --jpeg-ext EXTENSION Specify file extension for JPEG files. Photos
uses .jpeg for edited images but many images uses .jpeg for edited images but many images
are imported with .jpg or .JPG which can are imported with .jpg or .JPG which can
@@ -999,14 +926,12 @@ Options:
exported JPEG images. Valid values are jpeg, exported JPEG images. Valid values are jpeg,
jpg, JPEG, JPG; e.g. '--jpeg-ext jpg' to use jpg, JPEG, JPG; e.g. '--jpeg-ext jpg' to use
'.jpg' for all JPEGs. '.jpg' for all JPEGs.
--strip Optionally strip leading and trailing --strip Optionally strip leading and trailing
whitespace from any rendered templates. For whitespace from any rendered templates. For
example, if --filename template is "{title,} example, if --filename template is "{title,}
{original_name}" and image has no title, {original_name}" and image has no title,
resulting file would have a leading space but resulting file would have a leading space but
if used with --strip, this will be removed. if used with --strip, this will be removed.
--edited-suffix SUFFIX Optional suffix template for naming edited --edited-suffix SUFFIX Optional suffix template for naming edited
photos. Default name for edited photos is in photos. Default name for edited photos is in
form 'photoname_edited.ext'. For example, with form 'photoname_edited.ext'. For example, with
@@ -1016,7 +941,6 @@ Options:
suffix is '_edited'. Multi-value templates suffix is '_edited'. Multi-value templates
(see Templating System) are not permitted with (see Templating System) are not permitted with
--edited-suffix. --edited-suffix.
--original-suffix SUFFIX Optional suffix template for naming original --original-suffix SUFFIX Optional suffix template for naming original
photos. Default name for original photos is photos. Default name for original photos is
in form 'filename.ext'. For example, with '-- in form 'filename.ext'. For example, with '--
@@ -1025,11 +949,9 @@ Options:
default suffix is '' (no suffix). Multi-value default suffix is '' (no suffix). Multi-value
templates (see Templating System) are not templates (see Templating System) are not
permitted with --original-suffix. permitted with --original-suffix.
--use-photos-export Force the use of AppleScript or PhotoKit to --use-photos-export Force the use of AppleScript or PhotoKit to
export even if not missing (see also '-- export even if not missing (see also '--
download-missing' and '--use-photokit'). download-missing' and '--use-photokit').
--use-photokit Use with '--download-missing' or '--use- --use-photokit Use with '--download-missing' or '--use-
photos-export' to use direct Photos interface photos-export' to use direct Photos interface
instead of AppleScript to export. Highly instead of AppleScript to export. Highly
@@ -1037,11 +959,9 @@ Options:
iTerm2 (use with Terminal.app). This is faster iTerm2 (use with Terminal.app). This is faster
and more reliable than the default AppleScript and more reliable than the default AppleScript
interface. interface.
--report <path to export report> --report <path to export report>
Write a CSV formatted report of all files that Write a CSV formatted report of all files that
were exported. were exported.
--cleanup Cleanup export directory by deleting any files --cleanup Cleanup export directory by deleting any files
which were not included in this export set. which were not included in this export set.
For example, photos which had previously been For example, photos which had previously been
@@ -1053,7 +973,6 @@ Options:
you intend before using --cleanup. Use --dry- you intend before using --cleanup. Use --dry-
run with --cleanup first if you're not run with --cleanup first if you're not
certain. certain.
--add-exported-to-album ALBUM Add all exported photos to album ALBUM in --add-exported-to-album ALBUM Add all exported photos to album ALBUM in
Photos. Album ALBUM will be created if it Photos. Album ALBUM will be created if it
doesn't exist. All exported photos will be doesn't exist. All exported photos will be
@@ -1063,7 +982,6 @@ Options:
feature is currently experimental. I don't feature is currently experimental. I don't
know how well it will work on large export know how well it will work on large export
sets. sets.
--add-skipped-to-album ALBUM Add all skipped photos to album ALBUM in --add-skipped-to-album ALBUM Add all skipped photos to album ALBUM in
Photos. Album ALBUM will be created if it Photos. Album ALBUM will be created if it
doesn't exist. All skipped photos will be doesn't exist. All skipped photos will be
@@ -1073,7 +991,6 @@ Options:
feature is currently experimental. I don't feature is currently experimental. I don't
know how well it will work on large export know how well it will work on large export
sets. sets.
--add-missing-to-album ALBUM Add all missing photos to album ALBUM in --add-missing-to-album ALBUM Add all missing photos to album ALBUM in
Photos. Album ALBUM will be created if it Photos. Album ALBUM will be created if it
doesn't exist. All missing photos will be doesn't exist. All missing photos will be
@@ -1083,7 +1000,6 @@ Options:
feature is currently experimental. I don't feature is currently experimental. I don't
know how well it will work on large export know how well it will work on large export
sets. sets.
--exportdb EXPORTDB_FILE Specify alternate name for database file which --exportdb EXPORTDB_FILE Specify alternate name for database file which
stores state information for export and stores state information for export and
--update. If --exportdb is not specified, --update. If --exportdb is not specified,
@@ -1092,7 +1008,6 @@ Options:
directory. Must be specified as filename directory. Must be specified as filename
only, not a path, as export database will be only, not a path, as export database will be
saved in export directory. saved in export directory.
--load-config <config file path> --load-config <config file path>
Load options from file as written with --save- Load options from file as written with --save-
config. This allows you to save a complex config. This allows you to save a complex
@@ -1104,11 +1019,9 @@ Options:
line options are used in conjunction with line options are used in conjunction with
--load-config, they will override the --load-config, they will override the
corresponding values in the config file. corresponding values in the config file.
--save-config <config file path> --save-config <config file path>
Save options to file for use with --load- Save options to file for use with --load-
config. File format is TOML. config. File format is TOML.
--help Show this message and exit. --help Show this message and exit.
** Export ** ** Export **
@@ -1163,32 +1076,25 @@ The following attributes may be used with '--xattr-template':
authors The author, or authors, of the contents of the file. A list of authors The author, or authors, of the contents of the file. A list of
strings. (com.apple.metadata:kMDItemAuthors) strings. (com.apple.metadata:kMDItemAuthors)
comment A comment related to the file. This differs from the Finder comment A comment related to the file. This differs from the Finder
comment, kMDItemFinderComment. A string. comment, kMDItemFinderComment. A string.
(com.apple.metadata:kMDItemComment) (com.apple.metadata:kMDItemComment)
copyright The copyright owner of the file contents. A string. copyright The copyright owner of the file contents. A string.
(com.apple.metadata:kMDItemCopyright) (com.apple.metadata:kMDItemCopyright)
description A description of the content of the resource. The description description A description of the content of the resource. The description
may include an abstract, table of contents, reference to a may include an abstract, table of contents, reference to a
graphical representation of content or a free-text account of graphical representation of content or a free-text account of
the content. A string. (com.apple.metadata:kMDItemDescription) the content. A string. (com.apple.metadata:kMDItemDescription)
findercomment Finder comments for this file. A string. findercomment Finder comments for this file. A string.
(com.apple.metadata:kMDItemFinderComment) (com.apple.metadata:kMDItemFinderComment)
headline A publishable entry providing a synopsis of the contents of the headline A publishable entry providing a synopsis of the contents of the
file. A string. (com.apple.metadata:kMDItemHeadline) file. A string. (com.apple.metadata:kMDItemHeadline)
keywords Keywords associated with this file. For example, “Birthday”, keywords Keywords associated with this file. For example, “Birthday”,
“Important”, etc. This differs from Finder tags “Important”, etc. This differs from Finder tags
(_kMDItemUserTags) which are keywords/tags shown in the Finder (_kMDItemUserTags) which are keywords/tags shown in the Finder
and searchable in Spotlight using "tag:tag_name". A list of and searchable in Spotlight using "tag:tag_name". A list of
strings. (com.apple.metadata:kMDItemKeywords) strings. (com.apple.metadata:kMDItemKeywords)
For additional information on extended attributes see: https://developer.apple.c For additional information on extended attributes see: https://developer.apple.c
om/documentation/coreservices/file_metadata/mditem/common_metadata_attribute_key om/documentation/coreservices/file_metadata/mditem/common_metadata_attribute_key
s s
@@ -1412,7 +1318,6 @@ Substitution Description
{name} Current filename of the photo {name} Current filename of the photo
{original_name} Photo's original filename when imported to {original_name} Photo's original filename when imported to
Photos Photos
{title} Title of the photo {title} Title of the photo
{descr} Description of the photo {descr} Description of the photo
{media_type} Special media type resolved in this {media_type} Special media type resolved in this
@@ -1422,48 +1327,35 @@ Substitution Description
'video' if no special type. Customize one or 'video' if no special type. Customize one or
more media types using format: '{media_type,vi more media types using format: '{media_type,vi
deo=vidéo;time_lapse=vidéo_accélérée}' deo=vidéo;time_lapse=vidéo_accélérée}'
{photo_or_video} 'photo' or 'video' depending on what type the {photo_or_video} 'photo' or 'video' depending on what type the
image is. To customize, use default value as image is. To customize, use default value as
in '{photo_or_video,photo=fotos;video=videos}' in '{photo_or_video,photo=fotos;video=videos}'
{hdr} Photo is HDR?; True/False value, use in format {hdr} Photo is HDR?; True/False value, use in format
'{hdr?VALUE_IF_TRUE,VALUE_IF_FALSE}' '{hdr?VALUE_IF_TRUE,VALUE_IF_FALSE}'
{edited} True if photo has been edited (has {edited} True if photo has been edited (has
adjustments), otherwise False; use in format adjustments), otherwise False; use in format
'{edited?VALUE_IF_TRUE,VALUE_IF_FALSE}' '{edited?VALUE_IF_TRUE,VALUE_IF_FALSE}'
{edited_version} True if template is being rendered for the {edited_version} True if template is being rendered for the
edited version of a photo, otherwise False. edited version of a photo, otherwise False.
{favorite} Photo has been marked as favorite?; True/False {favorite} Photo has been marked as favorite?; True/False
value, use in format value, use in format
'{favorite?VALUE_IF_TRUE,VALUE_IF_FALSE}' '{favorite?VALUE_IF_TRUE,VALUE_IF_FALSE}'
{created.date} Photo's creation date in ISO format, e.g. {created.date} Photo's creation date in ISO format, e.g.
'2020-03-22' '2020-03-22'
{created.year} 4-digit year of photo creation time {created.year} 4-digit year of photo creation time
{created.yy} 2-digit year of photo creation time {created.yy} 2-digit year of photo creation time
{created.mm} 2-digit month of the photo creation time (zero {created.mm} 2-digit month of the photo creation time (zero
padded) padded)
{created.month} Month name in user's locale of the photo {created.month} Month name in user's locale of the photo
creation time creation time
{created.mon} Month abbreviation in the user's locale of the {created.mon} Month abbreviation in the user's locale of the
photo creation time photo creation time
{created.dd} 2-digit day of the month (zero padded) of {created.dd} 2-digit day of the month (zero padded) of
photo creation time photo creation time
{created.dow} Day of week in user's locale of the photo {created.dow} Day of week in user's locale of the photo
creation time creation time
{created.doy} 3-digit day of year (e.g Julian day) of photo {created.doy} 3-digit day of year (e.g Julian day) of photo
creation time, starting from 1 (zero padded) creation time, starting from 1 (zero padded)
{created.hour} 2-digit hour of the photo creation time {created.hour} 2-digit hour of the photo creation time
{created.min} 2-digit minute of the photo creation time {created.min} 2-digit minute of the photo creation time
{created.sec} 2-digit second of the photo creation time {created.sec} 2-digit second of the photo creation time
@@ -1476,51 +1368,38 @@ Substitution Description
no template will return null value. See no template will return null value. See
https://strftime.org/ for help on strftime https://strftime.org/ for help on strftime
templates. templates.
{modified.date} Photo's modification date in ISO format, e.g. {modified.date} Photo's modification date in ISO format, e.g.
'2020-03-22'; uses creation date if photo is '2020-03-22'; uses creation date if photo is
not modified not modified
{modified.year} 4-digit year of photo modification time; uses {modified.year} 4-digit year of photo modification time; uses
creation date if photo is not modified creation date if photo is not modified
{modified.yy} 2-digit year of photo modification time; uses {modified.yy} 2-digit year of photo modification time; uses
creation date if photo is not modified creation date if photo is not modified
{modified.mm} 2-digit month of the photo modification time {modified.mm} 2-digit month of the photo modification time
(zero padded); uses creation date if photo is (zero padded); uses creation date if photo is
not modified not modified
{modified.month} Month name in user's locale of the photo {modified.month} Month name in user's locale of the photo
modification time; uses creation date if photo modification time; uses creation date if photo
is not modified is not modified
{modified.mon} Month abbreviation in the user's locale of the {modified.mon} Month abbreviation in the user's locale of the
photo modification time; uses creation date if photo modification time; uses creation date if
photo is not modified photo is not modified
{modified.dd} 2-digit day of the month (zero padded) of the {modified.dd} 2-digit day of the month (zero padded) of the
photo modification time; uses creation date if photo modification time; uses creation date if
photo is not modified photo is not modified
{modified.dow} Day of week in user's locale of the photo {modified.dow} Day of week in user's locale of the photo
modification time; uses creation date if photo modification time; uses creation date if photo
is not modified is not modified
{modified.doy} 3-digit day of year (e.g Julian day) of photo {modified.doy} 3-digit day of year (e.g Julian day) of photo
modification time, starting from 1 (zero modification time, starting from 1 (zero
padded); uses creation date if photo is not padded); uses creation date if photo is not
modified modified
{modified.hour} 2-digit hour of the photo modification time; {modified.hour} 2-digit hour of the photo modification time;
uses creation date if photo is not modified uses creation date if photo is not modified
{modified.min} 2-digit minute of the photo modification time; {modified.min} 2-digit minute of the photo modification time;
uses creation date if photo is not modified uses creation date if photo is not modified
{modified.sec} 2-digit second of the photo modification time; {modified.sec} 2-digit second of the photo modification time;
uses creation date if photo is not modified uses creation date if photo is not modified
{modified.strftime} Apply strftime template to file modification {modified.strftime} Apply strftime template to file modification
date/time. Should be used in form date/time. Should be used in form
{modified.strftime,TEMPLATE} where TEMPLATE is {modified.strftime,TEMPLATE} where TEMPLATE is
@@ -1531,28 +1410,21 @@ Substitution Description
creation date if photo is not modified. See creation date if photo is not modified. See
https://strftime.org/ for help on strftime https://strftime.org/ for help on strftime
templates. templates.
{today.date} Current date in iso format, e.g. '2020-03-22' {today.date} Current date in iso format, e.g. '2020-03-22'
{today.year} 4-digit year of current date {today.year} 4-digit year of current date
{today.yy} 2-digit year of current date {today.yy} 2-digit year of current date
{today.mm} 2-digit month of the current date (zero {today.mm} 2-digit month of the current date (zero
padded) padded)
{today.month} Month name in user's locale of the current {today.month} Month name in user's locale of the current
date date
{today.mon} Month abbreviation in the user's locale of the {today.mon} Month abbreviation in the user's locale of the
current date current date
{today.dd} 2-digit day of the month (zero padded) of {today.dd} 2-digit day of the month (zero padded) of
current date current date
{today.dow} Day of week in user's locale of the current {today.dow} Day of week in user's locale of the current
date date
{today.doy} 3-digit day of year (e.g Julian day) of {today.doy} 3-digit day of year (e.g Julian day) of
current date, starting from 1 (zero padded) current date, starting from 1 (zero padded)
{today.hour} 2-digit hour of the current date {today.hour} 2-digit hour of the current date
{today.min} 2-digit minute of the current date {today.min} 2-digit minute of the current date
{today.sec} 2-digit second of the current date {today.sec} 2-digit second of the current date
@@ -1565,70 +1437,51 @@ Substitution Description
no template will return null value. See no template will return null value. See
https://strftime.org/ for help on strftime https://strftime.org/ for help on strftime
templates. templates.
{place.name} Place name from the photo's reverse {place.name} Place name from the photo's reverse
geolocation data, as displayed in Photos geolocation data, as displayed in Photos
{place.country_code} The ISO country code from the photo's reverse {place.country_code} The ISO country code from the photo's reverse
geolocation data geolocation data
{place.name.country} Country name from the photo's reverse {place.name.country} Country name from the photo's reverse
geolocation data geolocation data
{place.name.state_province} State or province name from the photo's {place.name.state_province} State or province name from the photo's
reverse geolocation data reverse geolocation data
{place.name.city} City or locality name from the photo's reverse {place.name.city} City or locality name from the photo's reverse
geolocation data geolocation data
{place.name.area_of_interest} Area of interest name (e.g. landmark or public {place.name.area_of_interest} Area of interest name (e.g. landmark or public
place) from the photo's reverse geolocation place) from the photo's reverse geolocation
data data
{place.address} Postal address from the photo's reverse {place.address} Postal address from the photo's reverse
geolocation data, e.g. '2007 18th St NW, geolocation data, e.g. '2007 18th St NW,
Washington, DC 20009, United States' Washington, DC 20009, United States'
{place.address.street} Street part of the postal address, e.g. '2007 {place.address.street} Street part of the postal address, e.g. '2007
18th St NW' 18th St NW'
{place.address.city} City part of the postal address, e.g. {place.address.city} City part of the postal address, e.g.
'Washington' 'Washington'
{place.address.state_province} State/province part of the postal address, {place.address.state_province} State/province part of the postal address,
e.g. 'DC' e.g. 'DC'
{place.address.postal_code} Postal code part of the postal address, e.g. {place.address.postal_code} Postal code part of the postal address, e.g.
'20009' '20009'
{place.address.country} Country name of the postal address, e.g. {place.address.country} Country name of the postal address, e.g.
'United States' 'United States'
{place.address.country_code} ISO country code of the postal address, e.g. {place.address.country_code} ISO country code of the postal address, e.g.
'US' 'US'
{searchinfo.season} Season of the year associated with a photo, {searchinfo.season} Season of the year associated with a photo,
e.g. 'Summer'; (Photos 5+ only, applied e.g. 'Summer'; (Photos 5+ only, applied
automatically by Photos' image categorization automatically by Photos' image categorization
algorithms). algorithms).
{exif.camera_make} Camera make from original photo's EXIF {exif.camera_make} Camera make from original photo's EXIF
information as imported by Photos, e.g. information as imported by Photos, e.g.
'Apple' 'Apple'
{exif.camera_model} Camera model from original photo's EXIF {exif.camera_model} Camera model from original photo's EXIF
information as imported by Photos, e.g. information as imported by Photos, e.g.
'iPhone 6s' 'iPhone 6s'
{exif.lens_model} Lens model from original photo's EXIF {exif.lens_model} Lens model from original photo's EXIF
information as imported by Photos, e.g. information as imported by Photos, e.g.
'iPhone 6s back camera 4.15mm f/2.2' 'iPhone 6s back camera 4.15mm f/2.2'
{uuid} Photo's internal universally unique identifier {uuid} Photo's internal universally unique identifier
(UUID) for the photo, a 36-character string (UUID) for the photo, a 36-character string
unique to the photo, e.g. unique to the photo, e.g.
'128FB4C6-0B16-4E7D-9108-FB2E90DA1546' '128FB4C6-0B16-4E7D-9108-FB2E90DA1546'
{comma} A comma: ',' {comma} A comma: ','
{semicolon} A semicolon: ';' {semicolon} A semicolon: ';'
{questionmark} A question mark: '?' {questionmark} A question mark: '?'
@@ -1643,6 +1496,8 @@ Substitution Description
{lf} A line feed: '\n', alias for {newline} {lf} A line feed: '\n', alias for {newline}
{cr} A carriage return: '\r' {cr} A carriage return: '\r'
{crlf} a carriage return + line feed: '\r\n' {crlf} a carriage return + line feed: '\r\n'
{osxphotos_version} The osxphotos version, e.g. '0.42.22'
{osxphotos_cmd_line} The full command line used to run osxphotos
The following substitutions may result in multiple values. Thus if specified for The following substitutions may result in multiple values. Thus if specified for
--directory these could result in multiple copies of a photo being being --directory these could result in multiple copies of a photo being being
@@ -1656,7 +1511,6 @@ Substitution Description
{folder_album} Folder path + album photo is contained in. e.g. {folder_album} Folder path + album photo is contained in. e.g.
'Folder/Subfolder/Album' or just 'Album' if no 'Folder/Subfolder/Album' or just 'Album' if no
enclosing folder enclosing folder
{keyword} Keyword(s) assigned to photo {keyword} Keyword(s) assigned to photo
{person} Person(s) / face(s) in a photo {person} Person(s) / face(s) in a photo
{label} Image categorization label associated with a photo {label} Image categorization label associated with a photo
@@ -1665,11 +1519,9 @@ Substitution Description
categorize images. These are not the same as categorize images. These are not the same as
{keyword} which refers to the user-defined {keyword} which refers to the user-defined
keywords/tags applied in Photos. keywords/tags applied in Photos.
{label_normalized} All lower case version of 'label' (Photos 5+ only) {label_normalized} All lower case version of 'label' (Photos 5+ only)
{comment} Comment(s) on shared Photos; format is 'Person name: {comment} Comment(s) on shared Photos; format is 'Person name:
comment text' (Photos 5+ only) comment text' (Photos 5+ only)
{exiftool} Format: '{exiftool:GROUP:TAGNAME}'; use exiftool {exiftool} Format: '{exiftool:GROUP:TAGNAME}'; use exiftool
(https://exiftool.org) to extract metadata, in form (https://exiftool.org) to extract metadata, in form
GROUP:TAGNAME, from image. E.g. GROUP:TAGNAME, from image. E.g.
@@ -1679,24 +1531,19 @@ Substitution Description
names. You must specify group (e.g. EXIF, IPTC, etc) names. You must specify group (e.g. EXIF, IPTC, etc)
as used in `exiftool -G`. exiftool must be installed as used in `exiftool -G`. exiftool must be installed
in the path to use this template. in the path to use this template.
{searchinfo.holiday} Holiday names associated with a photo, e.g. {searchinfo.holiday} Holiday names associated with a photo, e.g.
'Christmas Day'; (Photos 5+ only, applied 'Christmas Day'; (Photos 5+ only, applied
automatically by Photos' image categorization automatically by Photos' image categorization
algorithms). algorithms).
{searchinfo.activity} Activities associated with a photo, e.g. 'Sporting {searchinfo.activity} Activities associated with a photo, e.g. 'Sporting
Event'; (Photos 5+ only, applied automatically by Event'; (Photos 5+ only, applied automatically by
Photos' image categorization algorithms). Photos' image categorization algorithms).
{searchinfo.venue} Venues associated with a photo, e.g. name of {searchinfo.venue} Venues associated with a photo, e.g. name of
restaurant; (Photos 5+ only, applied automatically by restaurant; (Photos 5+ only, applied automatically by
Photos' image categorization algorithms). Photos' image categorization algorithms).
{searchinfo.venue_type} Venue types associated with a photo, e.g. {searchinfo.venue_type} Venue types associated with a photo, e.g.
'Restaurant'; (Photos 5+ only, applied automatically 'Restaurant'; (Photos 5+ only, applied automatically
by Photos' image categorization algorithms). by Photos' image categorization algorithms).
{photo} Provides direct access to the PhotoInfo object for {photo} Provides direct access to the PhotoInfo object for
the photo. Must be used in format '{photo.property}' the photo. Must be used in format '{photo.property}'
where 'property' represents a PhotoInfo property. For where 'property' represents a PhotoInfo property. For
@@ -1708,7 +1555,6 @@ Substitution Description
underlying PhotoInfo class. See underlying PhotoInfo class. See
https://rhettbull.github.io/osxphotos/ for additional https://rhettbull.github.io/osxphotos/ for additional
documentation on the PhotoInfo class. documentation on the PhotoInfo class.
{function} Execute a python function from an external file and {function} Execute a python function from an external file and
use return value as template substitution. Use in use return value as template substitution. Use in
format: {function:file.py::function_name} where format: {function:file.py::function_name} where
@@ -1720,7 +1566,6 @@ Substitution Description
example of how to implement a template function. example of how to implement a template function.
``` ```
<!-- OSXPHOTOS-EXPORT-USAGE:END --> <!-- OSXPHOTOS-EXPORT-USAGE:END -->
@@ -3352,6 +3197,8 @@ The following template field substitutions are availabe for use the templating s
|{lf}|A line feed: '\n', alias for {newline}| |{lf}|A line feed: '\n', alias for {newline}|
|{cr}|A carriage return: '\r'| |{cr}|A carriage return: '\r'|
|{crlf}|a carriage return + line feed: '\r\n'| |{crlf}|a carriage return + line feed: '\r\n'|
|{osxphotos_version}|The osxphotos version, e.g. '0.42.22'|
|{osxphotos_cmd_line}|The full command line used to run osxphotos|
|{album}|Album(s) photo is contained in| |{album}|Album(s) photo is contained in|
|{folder_album}|Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder| |{folder_album}|Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder|
|{keyword}|Keyword(s) assigned to photo| |{keyword}|Keyword(s) assigned to photo|