v1.70

rclone convmv

Convert file and directory names in place.

Synopsis

convmv supports advanced path name transformations for converting and renaming files and directories by applying prefixes, suffixes, and other alterations.

Command	Description
`--name-transform prefix=XXXX`	Prepends XXXX to the file name.
`--name-transform suffix=XXXX`	Appends XXXX to the file name after the extension.
`--name-transform suffix_keep_extension=XXXX`	Appends XXXX to the file name while preserving the original file extension.
`--name-transform trimprefix=XXXX`	Removes XXXX if it appears at the start of the file name.
`--name-transform trimsuffix=XXXX`	Removes XXXX if it appears at the end of the file name.
`--name-transform regex=/pattern/replacement/`	Applies a regex-based transformation.
`--name-transform replace=old:new`	Replaces occurrences of old with new in the file name.
`--name-transform date={YYYYMMDD}`	Appends or prefixes the specified date format.
`--name-transform truncate=N`	Truncates the file name to a maximum of N characters.
`--name-transform base64encode`	Encodes the file name in Base64.
`--name-transform base64decode`	Decodes a Base64-encoded file name.
`--name-transform encoder=ENCODING`	Converts the file name to the specified encoding (e.g., ISO-8859-1, Windows-1252, Macintosh).
`--name-transform decoder=ENCODING`	Decodes the file name from the specified encoding.
`--name-transform charmap=MAP`	Applies a character mapping transformation.
`--name-transform lowercase`	Converts the file name to lowercase.
`--name-transform uppercase`	Converts the file name to UPPERCASE.
`--name-transform titlecase`	Converts the file name to Title Case.
`--name-transform ascii`	Strips non-ASCII characters.
`--name-transform url`	URL-encodes the file name.
`--name-transform nfc`	Converts the file name to NFC Unicode normalization form.
`--name-transform nfd`	Converts the file name to NFD Unicode normalization form.
`--name-transform nfkc`	Converts the file name to NFKC Unicode normalization form.
`--name-transform nfkd`	Converts the file name to NFKD Unicode normalization form.
`--name-transform command=/path/to/my/programfile names.`	Executes an external program to transform

Conversion modes:

none  
nfc  
nfd  
nfkc  
nfkd  
replace  
prefix  
suffix  
suffix_keep_extension  
trimprefix  
trimsuffix  
index  
date  
truncate  
base64encode  
base64decode  
encoder  
decoder  
ISO-8859-1  
Windows-1252  
Macintosh  
charmap  
lowercase  
uppercase  
titlecase  
ascii  
url  
regex  
command

Char maps:

  
IBM-Code-Page-037  
IBM-Code-Page-437  
IBM-Code-Page-850  
IBM-Code-Page-852  
IBM-Code-Page-855  
Windows-Code-Page-858  
IBM-Code-Page-860  
IBM-Code-Page-862  
IBM-Code-Page-863  
IBM-Code-Page-865  
IBM-Code-Page-866  
IBM-Code-Page-1047  
IBM-Code-Page-1140  
ISO-8859-1  
ISO-8859-2  
ISO-8859-3  
ISO-8859-4  
ISO-8859-5  
ISO-8859-6  
ISO-8859-7  
ISO-8859-8  
ISO-8859-9  
ISO-8859-10  
ISO-8859-13  
ISO-8859-14  
ISO-8859-15  
ISO-8859-16  
KOI8-R  
KOI8-U  
Macintosh  
Macintosh-Cyrillic  
Windows-874  
Windows-1250  
Windows-1251  
Windows-1252  
Windows-1253  
Windows-1254  
Windows-1255  
Windows-1256  
Windows-1257  
Windows-1258  
X-User-Defined

Encoding masks:

Asterisk  
 BackQuote  
 BackSlash  
 Colon  
 CrLf  
 Ctl  
 Del  
 Dollar  
 Dot  
 DoubleQuote  
 Exclamation  
 Hash  
 InvalidUtf8  
 LeftCrLfHtVt  
 LeftPeriod  
 LeftSpace  
 LeftTilde  
 LtGt  
 None  
 Percent  
 Pipe  
 Question  
 Raw  
 RightCrLfHtVt  
 RightPeriod  
 RightSpace  
 Semicolon  
 SingleQuote  
 Slash  
 SquareBracket

Examples:

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,uppercase"
// Output: STORIES/THE QUICK BROWN FOX!.TXT

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,replace=Fox:Turtle" --name-transform "all,replace=Quick:Slow"
// Output: stories/The Slow Brown Turtle!.txt

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,base64encode"
// Output: c3Rvcmllcw==/VGhlIFF1aWNrIEJyb3duIEZveCEudHh0

rclone convmv "c3Rvcmllcw==/VGhlIFF1aWNrIEJyb3duIEZveCEudHh0" --name-transform "all,base64decode"
// Output: stories/The Quick Brown Fox!.txt

rclone convmv "stories/The Quick Brown 🦊 Fox Went to the Café!.txt" --name-transform "all,nfc"
// Output: stories/The Quick Brown 🦊 Fox Went to the Café!.txt

rclone convmv "stories/The Quick Brown 🦊 Fox Went to the Café!.txt" --name-transform "all,nfd"
// Output: stories/The Quick Brown 🦊 Fox Went to the Café!.txt

rclone convmv "stories/The Quick Brown 🦊 Fox!.txt" --name-transform "all,ascii"
// Output: stories/The Quick Brown  Fox!.txt

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,trimsuffix=.txt"
// Output: stories/The Quick Brown Fox!

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,prefix=OLD_"
// Output: OLD_stories/OLD_The Quick Brown Fox!.txt

rclone convmv "stories/The Quick Brown 🦊 Fox Went to the Café!.txt" --name-transform "all,charmap=ISO-8859-7"
// Output: stories/The Quick Brown _ Fox Went to the Caf_!.txt

rclone convmv "stories/The Quick Brown Fox: A Memoir [draft].txt" --name-transform "all,encoder=Colon,SquareBracket"
// Output: stories/The Quick Brown Fox： A Memoir ［draft］.txt

rclone convmv "stories/The Quick Brown 🦊 Fox Went to the Café!.txt" --name-transform "all,truncate=21"
// Output: stories/The Quick Brown 🦊 Fox

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,command=echo"
// Output: stories/The Quick Brown Fox!.txt

rclone convmv "stories/The Quick Brown Fox!" --name-transform "date=-{YYYYMMDD}"
// Output: stories/The Quick Brown Fox!-20250608

rclone convmv "stories/The Quick Brown Fox!" --name-transform "date=-{macfriendlytime}"
// Output: stories/The Quick Brown Fox!-2025-06-08 0600AM

rclone convmv "stories/The Quick Brown Fox!.txt" --name-transform "all,regex=[\\.\\w]/ab"
// Output: ababababababab/ababab ababababab ababababab ababab!abababab

Multiple transformations can be used in sequence, applied in the order they are specified on the command line.

The --name-transform flag is also available in sync, copy, and move.

Files vs Directories

By default --name-transform will only apply to file names. The means only the leaf file name will be transformed. However some of the transforms would be better applied to the whole path or just directories. To choose which which part of the file path is affected some tags can be added to the --name-transform

Tag	Effect
`file`	Only transform the leaf name of files (DEFAULT)
`dir`	Only transform name of directories - these may appear anywhere in the path
`all`	Transform the entire path for files and directories

This is used by adding the tag into the transform name like this: --name-transform file,prefix=ABC or --name-transform dir,prefix=DEF.

For some conversions using all is more likely to be useful, for example --name-transform all,nfc

Note that --name-transform may not add path separators / to the name. This will cause an error.

Ordering and Conflicts

Transformations will be applied in the order specified by the user.
- If the file tag is in use (the default) then only the leaf name of files will be transformed.
- If the dir tag is in use then directories anywhere in the path will be transformed
- If the all tag is in use then directories and files anywhere in the path will be transformed
- Each transformation will be run one path segment at a time.
- If a transformation adds a / or ends up with an empty path segment then that will be an error.
It is up to the user to put the transformations in a sensible order.
- Conflicting transformations, such as prefix followed by trimprefix or nfc followed by nfd, are possible.
- Instead of enforcing mutual exclusivity, transformations are applied in sequence as specified by the user, allowing for intentional use cases (e.g., trimming one prefix before adding another).
- Users should be aware that certain combinations may lead to unexpected results and should verify transformations using --dry-run before execution.

Race Conditions and Non-Deterministic Behavior

Some transformations, such as replace=old:new, may introduce conflicts where multiple source files map to the same destination name. This can lead to race conditions when performing concurrent transfers. It is up to the user to anticipate these.

If two files from the source are transformed into the same name at the destination, the final state may be non-deterministic.
Running rclone check after a sync using such transformations may erroneously report missing or differing files due to overwritten results.
To minimize risks, users should:
- Carefully review transformations that may introduce conflicts.
- Use --dry-run to inspect changes before executing a sync (but keep in mind that it won't show the effect of non-deterministic transformations).
- Avoid transformations that cause multiple distinct source files to map to the same destination name.
- Consider disabling concurrency with --transfers=1 if necessary.
- Certain transformations (e.g. prefix) will have a multiplying effect every time they are used. Avoid these when using bisync.

rclone convmv dest:path --name-transform XXX [flags]

Options

      --create-empty-src-dirs   Create empty source dirs on destination after move
      --delete-empty-src-dirs   Delete empty source dirs after move
  -h, --help                    help for convmv

Options shared with other commands are described next. See the global flags page for global options not listed here.

Copy Options

Flags for anything which can copy a file

      --check-first                                 Do all the checks before starting transfers
  -c, --checksum                                    Check for changes with size & checksum (if available, or fallback to size only)
      --compare-dest stringArray                    Include additional server-side paths during comparison
      --copy-dest stringArray                       Implies --compare-dest but also copies files from paths into destination
      --cutoff-mode HARD|SOFT|CAUTIOUS              Mode to stop transfers when reaching the max transfer limit HARD|SOFT|CAUTIOUS (default HARD)
      --ignore-case-sync                            Ignore case when synchronizing
      --ignore-checksum                             Skip post copy check of checksums
      --ignore-existing                             Skip all files that exist on destination
      --ignore-size                                 Ignore size when skipping use modtime or checksum
  -I, --ignore-times                                Don't skip items that match size and time - transfer all unconditionally
      --immutable                                   Do not modify files, fail if existing files have been modified
      --inplace                                     Download directly to destination file instead of atomic download to temp/rename
  -l, --links                                       Translate symlinks to/from regular files with a '.rclonelink' extension
      --max-backlog int                             Maximum number of objects in sync or check backlog (default 10000)
      --max-duration Duration                       Maximum duration rclone will transfer data for (default 0s)
      --max-transfer SizeSuffix                     Maximum size of data to transfer (default off)
  -M, --metadata                                    If set, preserve metadata when copying objects
      --modify-window Duration                      Max time diff to be considered the same (default 1ns)
      --multi-thread-chunk-size SizeSuffix          Chunk size for multi-thread downloads / uploads, if not set by filesystem (default 64Mi)
      --multi-thread-cutoff SizeSuffix              Use multi-thread downloads for files above this size (default 256Mi)
      --multi-thread-streams int                    Number of streams to use for multi-thread downloads (default 4)
      --multi-thread-write-buffer-size SizeSuffix   In memory buffer size for writing when in multi-thread mode (default 128Ki)
      --name-transform stringArray                  Transform paths during the copy process
      --no-check-dest                               Don't check the destination, copy regardless
      --no-traverse                                 Don't traverse destination file system on copy
      --no-update-dir-modtime                       Don't update directory modification times
      --no-update-modtime                           Don't update destination modtime if files identical
      --order-by string                             Instructions on how to order the transfers, e.g. 'size,descending'
      --partial-suffix string                       Add partial-suffix to temporary file name when --inplace is not used (default ".partial")
      --refresh-times                               Refresh the modtime of remote files
      --server-side-across-configs                  Allow server-side operations (e.g. copy) to work across different configs
      --size-only                                   Skip based on size only, not modtime or checksum
      --streaming-upload-cutoff SizeSuffix          Cutoff for switching to chunked upload if file size is unknown, upload starts after reaching cutoff or when file ends (default 100Ki)
  -u, --update                                      Skip files that are newer on the destination

Important Options

Important flags useful for most commands

  -n, --dry-run         Do a trial run with no permanent changes
  -i, --interactive     Enable interactive mode
  -v, --verbose count   Print lots more stuff (repeat for more)

Flags for filtering directory listings

      --delete-excluded                     Delete files on dest excluded from sync
      --exclude stringArray                 Exclude files matching pattern
      --exclude-from stringArray            Read file exclude patterns from file (use - to read from stdin)
      --exclude-if-present stringArray      Exclude directories if filename is present
      --files-from stringArray              Read list of source-file names from file (use - to read from stdin)
      --files-from-raw stringArray          Read list of source-file names from file without any processing of lines (use - to read from stdin)
  -f, --filter stringArray                  Add a file filtering rule
      --filter-from stringArray             Read file filtering patterns from a file (use - to read from stdin)
      --hash-filter string                  Partition filenames by hash k/n or randomly @/n
      --ignore-case                         Ignore case in filters (case insensitive)
      --include stringArray                 Include files matching pattern
      --include-from stringArray            Read file include patterns from file (use - to read from stdin)
      --max-age Duration                    Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off)
      --max-depth int                       If set limits the recursion depth to this (default -1)
      --max-size SizeSuffix                 Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off)
      --metadata-exclude stringArray        Exclude metadatas matching pattern
      --metadata-exclude-from stringArray   Read metadata exclude patterns from file (use - to read from stdin)
      --metadata-filter stringArray         Add a metadata filtering rule
      --metadata-filter-from stringArray    Read metadata filtering patterns from a file (use - to read from stdin)
      --metadata-include stringArray        Include metadatas matching pattern
      --metadata-include-from stringArray   Read metadata include patterns from file (use - to read from stdin)
      --min-age Duration                    Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off)
      --min-size SizeSuffix                 Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)

Listing Options

Flags for listing directories

      --default-time Time   Time to show if modtime is unknown for files and directories (default 2000-01-01T00:00:00Z)
      --fast-list           Use recursive list if available; uses more memory but fewer transactions