mc find

The mc find command supports searching for objects on a AIStor deployment. You can also use the command to search for files on a filesystem.

Syntax

Example Syntax

The command has the following syntax:

mc [GLOBALFLAGS] find                    \
                 [--exec "string"]       \
                 [--ignore "string"]     \
                 [--larger "string"]     \
                 [--maxdepth "string"]   \
                 [--metadata "string"]   \
                 [--name "string"]       \
                 [--newer-than "string"] \
                 [--older-than "string"] \
                 [--path "string"]       \
                 [--print "string"]      \
                 [--regex "string"]      \
                 [--smaller "string"]    \
                 [--tags "string"]`      \
                 [--versions]            \
                 [--watch]               \
                 ALIAS

Brackets [] indicate optional parameters.
Parameters sharing a line are mutually dependent.
Parameters separated using the pipe | operator are mutually exclusive.

Copy the example to a text editor and modify as-needed before running the command in the terminal/shell.

Parameters

ALIAS

Required

For objects on AIStor or an S3-compatible host, specify the alias and the full path to search (e.g. bucket and prefixes). For example:

mc find play/mydata/

For objects on a filesystem, specify the full path to search. For example:

mc find ~/mydata/

Issuing mc find ALIAS with no other arguments returns a list of all objects or files at the specified path, similar to mc ls.

--exec

Optional

Spawns an external process for each object returned by mc find. Supports substitution formatting of the output.

--ignore

Optional

Exclude objects whose names match the specified wildcard pattern.

--larger

Optional

Match all objects larger than the specified size in units.

--maxdepth

Optional

Limits directory navigation to the specified depth.

--metadata

Optional

For use with AIStor deployments only.

Return objects with metadata that matches a specified key=value. Use the format --metadata="KEY=value".

You can pass a key with an empty value. In that case, mc find matches objects that do not have the metadata key or where the metadata key’s value is empty.

You can use the flag multiple times to match objects for additional metadata keys. To return, an object must have matching values for all metadata keys.

--name

Optional

Return objects whose names match the specified wildcard pattern.

--newer-than

Optional

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

The datetime may also be specified in absolute time of YYYY-MM-DD HH:MM:SS TMZ format. For example, mc find --newer-than="2025-01-22 09:57:00 CET" minioalias/mybucket.

--older-than

Optional

Mirror object(s) older than the specified timelimit. Specify a string in #d#hh#mm#ss format. For example: --older-than 1d2hh3mm4ss

Defaults to 0 (all objects).

The timestamp may also be specified in absolute time of YYYY-MM-DD HH:MM:SS TMZ format. For example, mc find --older-than="2025-01-22 09:57:00 CET" minioalias/mybucket.

--path

Optional

Return the contents of directories whose names match the specified wildcard pattern.

--print

Optional

Prints results to STDOUT. Supports substitution formatting of the output.

--regex

Optional

Returns objects or the contents of directories whose names match the specified PCRE regex pattern.

--tags

Optional

For use with AIStor deployments only.

Return objects with a tag that matches a specified RE2 RegEx pattern. Use the format --tag="KEY=regexValue".

You can pass a key with an empty value. In that case, mc find matches objects that do not have the metadata key or where the metadata key’s value is empty.

You can use the flag multiple times to match objects for additional tags. To return, an object must have matching values for all tags.

--smaller

Optional

Match all objects smaller than the specified size in units.

--versions

Optional

Include all object versions in the results.

--watch

Optional

Continuously monitor the ALIAS and return any new objects which match the specified criteria.

Global Flags

This command supports any of the global flags.

Examples

Find a Specific Object in a Bucket

mc find ALIAS/PATH --name NAME

Replace ALIAS with the alias of the S3-compatible host.
Replace PATH with the path to a bucket on the S3-compatiblehost. Omit the path to search from the root of the S3 host.
Replace NAME with the object.

Find Objects with File Extension in Bucket

mc find ALIAS/PATH --name *.EXTENSION

Replace ALIAS with the alias of the S3-compatible host.
Replace PATH with the path to a bucket on the S3-compatible host.
Replace EXTENSION with the file extension of the object.

Find All Matching Files and Copy To S3 Service

Use mc find with the --exec option to find files on a local filesystem and pass them to an mc command for further processing. The following example uses mc cp to copy the output of mc find to an S3-compatible host.

mc find FILEPATH --name "*.EXTENSION" --exec "mc cp {} ALIAS/PATH"

Replace FILEPATH with the full file path to the directory to search.
Replace EXTENSION with the file extension of the object.
Replace ALIAS with the alias of the S3-compatible host.
Replace PATH with the path to a bucket on the S3-compatible host.

To continuously watch the specified directory and copy new objects, include the --watch argument:

mc find --watch FILEPATH --name "*.EXTENSION" --exec "mc cp {} ALIAS/PATH"

Find Objects with a Matching Tag

Tag matching is only available for use on AIStor deployments.

mc find --tags="key=v*" ALIAS/BUCKET/

Replace key with the name of a tag key to match.
Replace v* with the RE2 Regular Expression to evaluate against.
Replace ALIAS with the alias of the AIStor deployment.
Replace BUCKET with the bucket or prefix to search.

You can add additional --tags="key=RegExpression" flags to match. Matching objects must match all included tags.

Find Objects with Matching Metadata

Metadata matching is only available for use on AIStor deployments.

mc find --json --metadata="content-type=text/csv" ALIAS/BUCKET/

Replace content-type=text/csv with the a key-value pair of the metadata field and value to match.
Replace ALIAS with the alias of the AIStor deployment.
Replace BUCKET with the bucket or prefix to search.

You can add additional --tags="metadata=value" flags to match. Matching objects must match all included metadata fields.

Behavior

Units of Measurement

The mc find --smaller and mc find --larger flags accept the following case-insensitive suffixes to represent the unit of the specified size value:

Suffix	Unit Size
`k`	KB (Kilobyte, 1000 Bytes)
`m`	MB (Megabyte, 1000 Kilobytes)
`g`	GB (Gigabyte, 1000 Megabytes)
`t`	TB (Terabyte, 1000 Gigabytes)
`ki`	KiB (Kibibyte, 1024 Bites)
`mi`	MiB (Mebibyte, 1024 Kibibytes)
`gi`	GiB (Gibibyte, 1024 Mebibytes)
`ti`	TiB (Tebibyte, 1024 Gibibytes)

Omitting the suffix defaults to bytes.

Substitution Format

The mc find --exec and mc find --print commands support string substitutions with special interpretations for following keywords.

The following keywords are supported for both filesystem and S3 service targets:

{} - Substitutes to full path.
{base} - Substitutes to basename of path.
{dir} - Substitutes to dirname of the path.
{size} - Substitutes to object size of the path.
{time} - Substitutes to object modified time of the path.

The following keyword is supported only for S3 service targets:

{url} - Substitutes to a shareable URL of the path.

S3 Compatibility

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.

AIStor 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.