`bm rm`

Syntax

The bm rm command removes objects from a bucket on a Buckit deployment. To completely remove a bucket, use bm rb instead.

You can also use bm rm against the local filesystem to produce similar results to the rm commandline tool.

For more information on how Buckit performs DELETE actions on objects, see Object Deletion.

Important

bm rm supports removing multiple objects or files in a single command. Consider using the --dry-run option to validate that the operation targets only the desired objects/files.

EXAMPLE

The following command removes multiple objects from the mydata bucket on the mybuckit Buckit deployment:

bm rm --recursive mybuckit/mydata

SYNTAX

The command has the following syntax:

bm [GLOBALFLAGS] rm  \
                 [--bypass]               \
                 [--dangerous]            \
                 [--dry-run]              \
                 [--force]*               \
                 [--incomplete]           \
                 [--newer-than "string"]  \
                 [--non-current]          \
                 [--older-than "string"]  \
                 [--recursive]            \
                 [--rewind "string"]      \
                 [--stdin]                \
                 [--version-id "string"]* \
                 [--versions]             \
                 ALIAS [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.

bm rm --force is required by multiple parameters. bm rm --version-id is mutually exclusive with multiple parameters. See the reference documentation for more information.

Parameters

ALIAS

Required

The alias of a Buckit deployment and the full path to the object to remove. For example:

bm rm play/mybucket/object.txt

You can specify multiple objects on the same or different Buckit deployments. For example:

bm rm play/mybucket/object.txt play/mybucket/otherobject.txt

If specifying the path to a bucket or bucket prefix, you must also specify the --recursive and --force arguments. For example:

bm rm --recursive --force play/mybucket/

bm rm --recursive --force play/mybucket/myprefix/

Consider first running the command with the --dry-run flag to validate the scope of the recursive delete operation.

For removing a file from a local filesystem, specify the full path to that file:

bm rm ~/data/myoldobject.txt

--bypass: Optional
Allows removing an object held under GOVERNANCE object locking.

--dangerous

Optional

Allows running bm rm when the ALIAS specifies the root (all buckets) on the Buckit deployment.

When combined with --versions, this flag directs bm rm to permanently remove all objects and versions from the ALIAS target.

Consider first running the command with the --dry-run to validate the scope of the site-wide delete operation.

Warning

Running bm rm --dangerous with the --versions flag is irreversible. Exercise all possible due diligence in ensuring the command applies to only the desired ALIAS targets prior to execution.

--dry-run: Optional
Outputs the results of a command without actually removing any files. Use this flag to test that your command configuration removes only the objects you wish to remove.

--force

Optional

Allows running bm rm with any of the following arguments:

--recursive
--versions
--stdin

--incomplete, I

Optional

Remove incomplete uploads for the specified object.

If any ALIAS specifies a bucket, you must also specify --recursive and --force.

--newer-than

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

--non-current

Optional

Removes all non-current object versions from the specified ALIAS.

This option has no effect on buckets without versioning enabled.

--older-than

Optional

Remove object(s) older than the specified time limit. Specify a string in #d#h#m#s format. For example: --older-than 1d2h3m4s.

Defaults to 0 (all objects).

--recursive, r

Optional

Recursively remove the contents of each ALIAS bucket or bucket prefix.

If specifying --recursive, you must also specify --force.

For buckets with versioning enabled, this option by default produces a delete marker for each removed object. Include the --versions flag to recursively remove all objects and object versions from the bucket.

Consider first running the command with the --dry-run flag to validate the scope of the recursive delete operation.

Mutually exclusive with bm rm --version-id

--rewind

Optional

Directs bm rm to operate only on the object version(s) that existed at specified point-in-time.

To rewind to a specific date in the past, specify the date as an ISO8601-formatted timestamp. For example: --rewind "2020.03.24T10:00".
To rewind a duration in time, specify the duration as a string in #d#hh#mm#ss format. For example: --rewind "1d2hh3mm4ss".

--rewind requires that the specified ALIAS be an S3-compatible service that supports Bucket Versioning. For Buckit deployments, use bm version to enable or disable bucket versioning.

--stdin: Optional
Read object names or buckets from STDIN.

--versions

Optional

Directs bm rm to operate on all object versions that exist in the bucket.

--versions requires that the specified ALIAS be an S3-compatible service that supports Bucket Versioning. For Buckit deployments, use bm version to enable or disable bucket versioning.

Use --versions and --rewind together to remove all object versions which existed at a specific point in time.

--version-id, vid

Optional

Directs bm rm to operate only on the specified object version.

--version-id requires that the specified ALIAS be an S3-compatible service that supports Bucket Versioning. For Buckit deployments, use bm version to enable or disable bucket versioning.

Mutually exclusive with any of the following flags:

--versions
--rewind
--recursive

Global Flags

This command supports any of the global flags.

Examples

Remove a Single Object

bm rm ALIAS/PATH

Replace ALIAS with the alias of a configured S3-compatible service.
Replace PATH with the path to the object.

Recursively Remove a Bucket’s Contents

Use bm rm with the --recursive and --force options to recursively remove a bucket’s contents.

bm rm --recursive --force ALIAS/PATH

Replace ALIAS with the alias of a configured S3-compatible service.
Replace PATH with the path to the bucket.

This operation does not remove the bucket. Use bm rb to remove the bucket along with all contents and associated configurations.

Remove All Incomplete Upload Files for an Object

Use bm rm with the --incomplete option to remove incomplete upload files for an object.

bm rm --incomplete --recursive --force ALIAS/PATH

Replace ALIAS with the alias of a configured S3-compatible service.
Replace PATH with the path to the object.

Roll Object Back To Previous Version

Use bm rm with --versions and --newer-than to remove all object versions newer than the specified duration of time. This effectively “rolls back” the object to its state at that time.

Important

Removing specific versions of an object is a destructive action. You cannot restore the deleted object versions.

bm rm ALIAS/PATH --versions --newer-than DURATION

Replace ALIAS with the alias of a configured S3-compatible service.
Replace PATH with the path to the object. For example, /mybucket/myobject.
Replace DURATION with the number of days in the past from the current host time from which the operation begins removing versions of the object. For example, to remove all versions of the object created in the last 30 days, specify "30d".

Behavior

Deleting Bucket Contents

Using bm rm to remove all contents in a bucket does not delete the bucket itself. Any configurations associated to the bucket remain in place, such as default object lock settings.

To completely remove a bucket, use bm rb instead of bm rm.

Buckit Trims Empty Prefixes on Object Removal

bm rm relies on the bm removal API for deleting objects. As part of removing the last object in a bucket prefix, bm also recursively removes each empty part of the prefix up to the bucket root. bm 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 bm 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 bm mb. All other prefixes were implicitly created as part of writing the object located at that prefix.

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

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

Delete Operations in Versioned Buckets

Buckit supports keeping multiple versions of an object in a single bucket. Deleting an object in a versioned bucket results in a special DeleteMarker tombstone that marks an object as deleted while retaining all previous versions of that object.

To remove a specific object version from a bucket, use bm rm --version-id
To remove all versions of an object from a bucket, use bm rm --versions
To remove all non-current versions of an object from a bucket, use bm rm --non-current

S3 Compatibility

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

Buckit provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported. While bm commands may work as documented, any such usage is at your own risk.