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 truncate_keep_extension=N Truncates the file name to a maximum of N characters while preserving the original file extension.
--name-transform truncate_bytes=N Truncates the file name to a maximum of N bytes (not characters).
--name-transform truncate_bytes_keep_extension=N Truncates the file name to a maximum of N bytes (not characters) while preserving the original file extension.
--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
truncate_keep_extension
truncate_bytes
truncate_bytes_keep_extension
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 Café!.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!-20250830

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

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

The regex command generally accepts Perl-style regular expressions, the exact syntax is defined in the Go regular expression reference. The replacement string may contain capturing group variables, referencing capturing groups using the syntax $name or ${name}, where the name can refer to a named capturing group or it can simply be the index as a number. To insert a literal $, use $$.

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)

Filter Options

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

See Also

  • rclone - Show help for rclone commands, flags and backends.
Contents
Gold Sponsor

Gold Sponsor

Gold Sponsor

Share and Enjoy
Twitter
Facebook
Reddit
Links
Rclone forum
GitHub project
Rclone Wiki
Sponsor
@njcw