mc mv

The mc mv command moves an object from source to the target, such as between AIStor deployments or between buckets on the same AIStor deployment. mc mv also supports moving objects between a local filesystem and AIStor.

You can also use mc mv against the local filesystem to produce similar results to the mv commandline tool.

mc mv --recursive myaistor/mydata myaistor/archive

mc [GLOBALFLAGS] mv                          \
                 [--attr "string"]           \
                 [--checksum "string"]       \
                 [--disable-multipart]       \
                 [--enc-kms "string"]        \
                 [--enc-s3 "string"]         \
                 [--enc-c "string"]          \
                 [--limit-download string]   \
                 [--limit-upload string]     \
                 [--newer-than "string"]     \
                 [--older-than "string"]     \
                 [--preserve]                \
                 [--recursive]               \
                 [--storage-class "string"]  \
                 [--tags "string"]           \
                 SOURCE [SOURCE...]          \
                 TARGET

Required

The object or objects to move.

For moving an object from an AIStor bucket, specify the alias and the full path to the object(s) (that is, the bucket and path to objects). For example:

mc mv myaistor/mybucket/object.txt myaistor/myotherbucket/object.txt

For moving an object from a local filesystem, specify the full path to that object. For example:

mc mv ~/mydata/object.txt myaistor/mybucket/object.txt

Specify multiple SOURCE paths to move multiple objects to the specified TARGET. mc rm treats the last specified alias or filesystem path as the TARGET. For example:

mc mv ~/mydata/object.txt myaistor/mydata/otherobject.txt myaistor/mydata

If you specify a directory or bucket to SOURCE, you must also specify --recursive to recursively move the contents of that directory. If you omit --recursive, the command only moves objects in the top level of the specified directory or bucket.

Required

The full path to the bucket to which the command moves the object(s) at the specified SOURCE. Specify the alias of a configured S3 service as the prefix to the TARGET path.

For moving an object from AIStor, specify the alias and the full path to the object(s) (that is, the bucket and path to objects). For example:

mc mv myaistor/mybucket/object.txt myaistor/myotherbucket/object.txt

For moving an object from a local filesystem, specify the full path to that object. For example:

mc mv ~/mydata/object.txt myaistor/mybucket/object.txt

The TARGET object name can differ from the SOURCE to “rename” the object as part of the move operation.

For --recursive operations, mc mv treats the TARGET as the bucket prefix for all objects at the SOURCE.

Optional

Add custom metadata for the object. Specify key-value pairs as KEY=VALUE\;, where each pair is separated by an escaped semi-colon.

For example, --attr key1=value1\;key2=value2\;key3=value3.

Add a checksum to the uploaded object. Only valid for AIStor, MinIO, or S3 targets.

Valid checksum types are:

• CRC64NVME
• CRC32
• CRC32C
• SHA1
• SHA256

Optional

Disables the multipart upload feature.

Multipart upload breaks an object into a set of separate parts. Each part uploads individually and in any order. If any individual part upload fails, AIStor retries that part without affecting the other parts. After upload completes, the parts combine to restore the original object.

MinIO recommends using multipart upload for any object larger than 100 MB. For more information on multipart upload, refer to the Amazon S3 documentation

Encrypt or decrypt objects using server-side SSE-KMS encryption with client-managed keys.

The parameter accepts a key-value pair formatted as KEY=VALUE

• KEY - The full path to the object as alias/bucket/path/object.ext. You can specify only the top-level path to use a single encryption key for all operations in that path.
• VALUE - Specify an existing data key on the external KMS. See the mc admin kms key create reference for creating data keys.

For example:

--enc-kms "myaistor/mybucket/prefix/object.obj=mybucketencryptionkey"

You can specify multiple encryption keys by repeating the parameter.

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-kms "myaistor/mybucket/prefix/=mybucketencryptionkey"

Optional

Encrypt or decrypt objects using server-side SSE-S3 encryption with KMS-managed keys. Specify the full path to the object as alias/bucket/prefix/object.

For example:

--enc-s3 "myaistor/mybucket/prefix/object.obj"

You can specify the parameter multiple times to denote different object(s) to encrypt:

--enc-s3 "myaistor/mybucket/foo/fooobject.obj" --enc-s3 "myaistor/mybucket/bar/barobject.obj"

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-s3 "myaistor/mybucket/foo"

Optional

Encrypt or decrypt objects using server-side SSE-C encryption with client-managed keys.

The parameter accepts a key-value pair formatted as KEY=VALUE

• KEY - The full path to the object as alias/bucket/path/object.ext. You can specify only the top-level path to use a single encryption key for all operations in that path.
• VALUE - Specify either a 32-byte RawBase64-encoded key or a 64-byte hex-encoded key for use with SSE-C encryption. Raw Base64 encoding rejects =-padded keys. Omit the padding or use a Base64 encoder that supports RAW formatting.

For example:

# RawBase64-Encoded string "mybucket32byteencryptionkeyssec"
--enc-c "myaistor/mybucket/prefix/object.obj=bXlidWNrZXQzMmJ5dGVlbmNyeXB0aW9ua2V5c3NlYwo"

You can specify multiple encryption keys by repeating the parameter.

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-c "myaistor/mybucket/prefix/=bXlidWNrZXQzMmJ5dGVlbmNyeXB0aW9ua2V5c3NlYwo"

Optional

Limit client-side download rates to no more than a specified rate in KiB/s, MiB/s, or GiB/s. This affects only the download to the local device running the AIStor client. Valid units include:

• B for bytes
• K for kilobytes
• M for megabytes
• G for gigabytes
• T for terabytes
• Ki for kibibytes
• Mi for mibibytes
• Gi for gibibytes
• Ti for tebibytes

For example, to limit download rates to no more than 1 GiB/s, use the following:

--limit-download 1G

If not specified, AIStor uses an unlimited download rate.

Optional

Limit client-side upload rates to no more than the specified rate in KiB/s, MiB/s, or GiB/s. This affects only the upload from the local device running the AIStor client. Valid units include:

• B for bytes
• K for kilobytes
• M for megabytes
• G for gigabytes
• T for terabytes
• Ki for kibibytes
• Mi for mibibytes
• Gi for gibibytes
• Ti for tebibytes

For example, to limit upload rates to no more than 1 GiB/s, use the following:

--limit-upload 1G

If not specified, AIStor uses an unlimited upload rate.

Optional

Remove object(s) newer than the specified number of days.
Specify a string in ##d#hh#mm#ss format. For example: --newer-than 1d2hh3mm4ss.

Defaults to 0 (all objects).

Optional

Remove object(s) older than the specified time limit. Specify a string in #d#hh#mm#ssformat.

For example: --older-than 1d2hh3mm4ss.

Defaults to 0 (all objects).

Alias: -a

Optional

Preserve file system attributes and bucket policy rules of the SOURCE directories, buckets, and objects on the TARGET bucket(s).

Alias: -r

Optional

Recursively move the contents of each bucket or directory SOURCE to the TARGET bucket.

Optional

Set the storage class for the new object(s) on the TARGET.

See Erasure Coding settings for more about storage classes.

Apply one or more tags to the uploaded object. Add tags as a comma-separated list of key=value pairs.

This command supports any of the global flags.

mc mv [--recursive] FILEPATH ALIAS/PATH

• Replace FILEPATH with the full file path to the file to move.

  If specifying the path to a directory, include the --recursive flag.

  mc mv removes the files from the source after successfully moving it to the destination.

• Replace ALIAS with the alias of a configured S3-compatible host.

• Replace PATH with the destination bucket.

Use mc mv with the --attr option to set custom attributes on file(s).

mc mv --attr "ATTRIBUTES" FILEPATH ALIAS/PATH

• Replace FILEPATH with the full file path to the file to move. mc mv removes the file from the source after successfully moving it to the destination.
• Replace ALIAS with the alias of a configured S3-compatible host.
• Replace PATH with the destination bucket.
• Replace ATTRIBUTES with one or more comma-separated key-value pairs KEY=VALUE. Each pair represents one attribute key and value.

 mc mv --recursive SRCALIAS/SRCPATH TGTALIAS/TGTPATH

• Replace SRCALIAS with the alias of a configured S3-compatible host.
• Replace SRCPATH with the path to the bucket. mc mv removes the bucket and its contents from the source after successfully moving it to the destination.
• Replace TGTALIAS with the alias of a configured S3-compatible host.
• Replace TGTPATH with the path to the bucket.

Use mc mv with the --storage-class option to set the storage class on the destination S3-compatible host.

mc mv --storage-class CLASS FILEPATH ALIAS/PATH

• Replace CLASS with the storage class to associate to the files.
• Replace FILEPATH with the full file path to the file to move. mc mv removes the file from the source after successfully moving it to the destination.
• Replace ALIAS with the alias of a configured S3-compatible host.
• Replace PATH with the destination bucket.
• Replace ATTRIBUTES with one or more comma-separated key-value pairs KEY=VALUE. Each pair represents one attribute key and value.

Use mc mv with the [--tags][#--tags] option to upload objects to an AIStor server at the alias myaistor and apply a tag to the uploaded objects. The command only uploads objects with the file extension of .pdf.

mc mv --tag "key1=value1" ~/mydata/*.pdf myaistor/mybucket/

Use mc mv with the --checksum option to upload an object and add a checksum of the specified type. This example adds an SHA256 checksum as part of the object headers.

mc mv --checksum SHA256 ~/mydata/myobject.txt myaistor/mybucket

## Behavior

### Object names on move

AIStor uses the [`SOURCE`](#SOURCE) object name when moving the object to the [`TARGET`](#TARGET) if no explicit target object name is specified.

You can specify a different object name for the [`TARGET`](#TARGET) with the same object path to “rename” an object. 

For example:

```shell {.copy}
mc mv myaistor/mybucket/object.txt myaistor/mybucket/myobject.txt

For recursive move operations (mc mv --recursive), AIStor treats the TARGET path as a prefix for objects on the SOURCE.

mc mv verifies all move operations to object storage using MD5SUM checksums.

This verification of the operation is distinct from the --checksum option that adds a checksum value to the object headers on upload. The verification is a check that the data uploaded as expected from the SOURCE, but does not add anything to the object metadata.

mc mv relies on the mc removal API for deleting objects. As part of removing the last object in a bucket prefix, mc also recursively removes each empty part of the prefix up to the bucket root. mc only applies the recursive removal to prefixes created implicitly as part of object write operations - that is, the prefix was not created using an explicit directory creation command such as mc mb.

For example, consider a bucket photos with the following object prefixes:

• photos/2021/january/myphoto.jpg
• photos/2021/february/myotherphoto.jpg
• photos/NYE21/NewYears.jpg

photos/NYE21 is the only prefix explicitly created using mc mb. All other prefixes were implicitly created as part of writing the object located at that prefix.

If an mc command removes myphoto.jpg, the removal API automatically trims the empty /january prefix. If a subsequent mc command removes myotherphoto.jpg, the removal API automatically trims both the /february prefix and the now-empty /2021 prefix. If an mc command removes NewYears.jpg, the /NYE21 prefix remains in place since it was explicitly created.

If using mc mv for operations on a filesystem, mc applies this same behavior by recursively trimming empty directory paths up to the root. However, the mc remove API cannot distinguish between an explicitly created directory path and an implicitly created one. If mc mv deletes the last object at a filesystem path, mc recursively deletes all empty directories within that path up to the root as part of the removal operation.

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with AIStor and AWS S3 for expected functionality and behavior.

MinIO provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported.

While mc commands may work as documented, any such usage is at your own risk.