From be53dcc9c97737b524bd3144364d9b2f74113fda Mon Sep 17 00:00:00 2001 From: Nick Craig-Wood Date: Mon, 12 Sep 2022 11:54:35 +0100 Subject: [PATCH] docs: add more information about --track-renames See: https://forum.rclone.org/t/feature-question-how-does-rclone-track-renames-and-moves/32911/4 --- docs/content/docs.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/content/docs.md b/docs/content/docs.md index 95609d757..47757d431 100644 --- a/docs/content/docs.md +++ b/docs/content/docs.md @@ -1868,13 +1868,22 @@ By default, rclone doesn't keep track of renamed files, so if you rename a file locally then sync it to a remote, rclone will delete the old file on the remote and upload a new copy. -If you use this flag, and the remote supports server-side copy or -server-side move, and the source and destination have a compatible -hash, then this will track renames during `sync` -operations and perform renaming server-side. +An rclone sync with `--track-renames` runs like a normal sync, but keeps +track of objects which exist in the destination but not in the source +(which would normally be deleted), and which objects exist in the +source but not the destination (which would normally be transferred). +These objects are then candidates for renaming. -Files will be matched by size and hash - if both match then a rename -will be considered. +After the sync, rclone matches up the source only and destination only +objects using the `--track-renames-strategy` specified and either +renames the destination object or transfers the source and deletes the +destination object. `--track-renames` is stateless like all of +rclone's syncs. + +To use this flag the destination must support server-side copy or +server-side move, and to use a hash based `--track-renames-strategy` +(the default) the source and the destination must have a compatible +hash. If the destination does not support server-side copy or move, rclone will fall back to the default behaviour and log an error level message @@ -1892,7 +1901,7 @@ Note also that `--track-renames` is incompatible with ### --track-renames-strategy (hash,modtime,leaf,size) ### -This option changes the matching criteria for `--track-renames`. +This option changes the file matching criteria for `--track-renames`. The matching is controlled by a comma separated selection of these tokens: @@ -1901,15 +1910,15 @@ The matching is controlled by a comma separated selection of these tokens: - `leaf` - the name of the file not including its directory name - `size` - the size of the file (this is always enabled) -So using `--track-renames-strategy modtime,leaf` would match files +The default option is `hash`. + +Using `--track-renames-strategy modtime,leaf` would match files based on modification time, the leaf of the file name and the size only. Using `--track-renames-strategy modtime` or `leaf` can enable `--track-renames` support for encrypted destinations. -If nothing is specified, the default option is matching by `hash`es. - Note that the `hash` strategy is not supported with encrypted destinations. ### --delete-(before,during,after) ###