From 60230d939ce23f9d09312e069170b164f4608ff8 Mon Sep 17 00:00:00 2001 From: pacoorozco Date: Tue, 15 Oct 2024 17:47:34 +0200 Subject: [PATCH] Improve documentation about option Signed-off-by: pacoorozco --- docs/configuration.md | 115 ++++++++++++++++++++++++------------------ 1 file changed, 66 insertions(+), 49 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index f7d0d80..7f5155b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -82,7 +82,8 @@ The folder to upload from. Must be an absolute path. Can expand the home folder > The application will follow any symlink it finds, it does not terminate if there are any non-terminating loops in the file structure. ### Album -It controls how uploaded files will be organized into albums in Google Photos. + +The `Album` parameter controls how uploaded files will be organized into albums in Google Photos. If omitted, files will be uploaded directly to Google Photos without being placed in an album. Given the local tree of folders and files: @@ -101,70 +102,43 @@ Given the local tree of folders and files: └── image-album3-03.jpg ``` -These are several options: `name:`, `auto:`, `template:`: +You can set the `Album` parameter using one of the following options: -#### Fixed name: `name:` +* **Omit the `Album` parameter**: If you do not include the `Album` parameter in a job configuration, files will be uploaded without creating or adding to an album. The files will be available in your Google Photos library but not grouped into any specific album. -The `name:` option followed by an album's name, will upload objects to an album with the specified name. +* **[Fixed Album Name: `name:`](#fixed-album-name-name)** -The album name in Google Photos is not unique, so the first to match to the name will be selected. +* **[Template-Based Album Names: `template:`](#template-based-album-names-template)** -Setting `Album: name:fooBar` will create and upload objects to an album named `fooBar`: +* **[Deprecated `auto:` Option](#deprecated-auto-option)** -```shell -Google Photos -└── fooBar - ├── image-album1-01.jpg - ├── image-album1-02.jpeg - ├── image-album2-01.jpg - ├── image-album2-02.jpg - ├── image-album3-01.jpg - ├── image-album3-02.jpg - └── image-album3-03.jpg -``` +#### Fixed Album Name: `name:` -#### Calculated name from a file path: `auto:` (deprecated) +Specify `name:` followed by an album's name to upload objects to an album with the specified name. The album name in Google Photos is not unique, so the first match will be used, or a new album will be created if none exists. -This configuration option is deprecated and will be removed in future versions. Use `template:` instead. +##### Example -##### From parent folder: `auto:folderName` (deprecated) + ```hjson + Album: name:fooBar + ``` -Setting `auto:folderName` and `SourceFolder: /home/my-user/pictures` will use the name of the folder (within `SourceFolder`), where the item is uploaded from, to set the album name. +will create and upload objects to an album named `fooBar`: ```shell Google Photos -├── album-1 -│ ├── image-album1-01.jpg -│ ├── image-album1-02.jpeg -├── album-2 -│ ├── image-album2-01.jpg -│ └── image-album2-02.jpg -└── album-3 - ├── image-album3-01.jpg - ├── image-album3-02.jpg - └── image-album3-03.jpg -``` -##### From full path: `auto:folderPath` (deprectated) - -Setting `auto:folderPath` and `SourceFolder: /home/my-user/pictures` will use the full path of the folder (relative to `SourceFolder`), where the item is uploaded from, to set the album name. - -```shell -Google Photos -├── upload_album-1 -│ ├── image-album1-01.jpg -│ ├── image-album1-02.jpeg -├── upload_album-2 -│ ├── image-album2-01.jpg -│ └── image-album2-02.jpg -└── upload_album-3 +└── fooBar + ├── image-album1-01.jpg + ├── image-album1-02.jpeg + ├── image-album2-01.jpg + ├── image-album2-02.jpg ├── image-album3-01.jpg ├── image-album3-02.jpg └── image-album3-03.jpg ``` -#### Customized template: `template:` +#### Template-Based Album Names: `template:` -Using `template:` followed by a template string that can contain the following predefined tokens and functions: +Use `template:` followed by a template string with placeholders to dynamically generate album names based on file properties like date or folder names. ##### Tokens @@ -191,9 +165,13 @@ Using `template:` followed by a template string that can contain the following p | $upper(x) | Converts the given string to upper case. | | $lower(x) | Converts the given string to lower case. | -##### Examples +##### Example + + ```hjson + Album: template:%_directory% - %_month%.%_day%.$cutLeft(%_year%,2) + ``` -Setting `template:%_directory% - %_month%.%_day%.$cutLeft(%_year%,2)` will calculate the album name based on the template for each file. +will calculate the album name based on the template for each file. ```shell Google Photos @@ -210,6 +188,45 @@ Google Photos └── image-album3-03.jpg ``` +#### Deprecated `auto:` Option + +For legacy support, the `auto:` options `auto:folderName` and `auto:folderPath` are available but will be removed in future versions. It is recommended to use `template:` instead. + +##### From parent folder: `auto:folderName` (deprecated) + +Setting `auto:folderName` and `SourceFolder: /home/my-user/pictures` will use the name of the folder (within `SourceFolder`), where the item is uploaded from, to set the album name. + +```shell +Google Photos +├── album-1 +│ ├── image-album1-01.jpg +│ ├── image-album1-02.jpeg +├── album-2 +│ ├── image-album2-01.jpg +│ └── image-album2-02.jpg +└── album-3 + ├── image-album3-01.jpg + ├── image-album3-02.jpg + └── image-album3-03.jpg +``` +##### From full path: `auto:folderPath` (deprectated) + +Setting `auto:folderPath` and `SourceFolder: /home/my-user/pictures` will use the full path of the folder (relative to `SourceFolder`), where the item is uploaded from, to set the album name. + +```shell +Google Photos +├── upload_album-1 +│ ├── image-album1-01.jpg +│ ├── image-album1-02.jpeg +├── upload_album-2 +│ ├── image-album2-01.jpg +│ └── image-album2-02.jpg +└── upload_album-3 + ├── image-album3-01.jpg + ├── image-album3-02.jpg + └── image-album3-03.jpg +``` + ### DeleteAfterUpload If set to true, media will be deleted from the local disk after completing the upload.