From bc8d563e9636f3e81ac2bd4cd83f59ef42682ed7 Mon Sep 17 00:00:00 2001 From: ravindk89 Date: Wed, 31 Mar 2021 21:41:32 -0400 Subject: [PATCH] MinIO Implicit Prefix Trimming on Removal of Last Object (see minio/mc issue#3621) --- source/includes/common-admonitions.rst | 50 ++++++++++++++++++- .../minio-cli/minio-mc/mc-mirror.rst | 17 +++++++ source/reference/minio-cli/minio-mc/mc-mv.rst | 13 +++++ source/reference/minio-cli/minio-mc/mc-rm.rst | 11 ++++ 4 files changed, 90 insertions(+), 1 deletion(-) diff --git a/source/includes/common-admonitions.rst b/source/includes/common-admonitions.rst index 411014e9..f1c8cbea 100644 --- a/source/includes/common-admonitions.rst +++ b/source/includes/common-admonitions.rst @@ -15,4 +15,52 @@ a maintenance period to minimize interruption of services while performing this procedure. -.. end-restart-downtime \ No newline at end of file +.. end-restart-downtime + + +.. Used in the following pages: + + /reference/minio-cli/minio-mc/mc-rm.rst + /reference/minio-cli/minio-mc/mc-mv.rst + /reference/minio-cli/minio-mc/mc-mirror.rst + +.. start-remove-api-trims-prefixes + +|command| relies on the :mc:`mc` removal API for deleting objects. As part of +removing the last object in a bucket prefix, :mc:`mc` also recursively removes +each empty part of the prefix up to the bucket root. :mc:`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:`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:`mc mb`. +All other prefixes were *implicitly* created as part of writing the object +located at that prefix. + +If an :mc:`mc` command removes ``myphoto.jpg``, the removal API automatically +trims the empty ``/january`` prefix. If a subsequent :mc:`mc` command removes +``myotherphoto.jpg``, the removal API automatically trims both the ``/february`` +prefix *and* the now-empty ``/2021`` prefix. If an :mc:`mc` command removes +``NewYears.jpg``, the ``/NYE21`` prefix remains in place since it was +*explicitly* created. + +.. end-remove-api-trims-prefixes + +.. Following is linked topically to the remove-api-trims-prefixes core + +.. start-remove-api-trims-prefixes-fs + +If using |command| for operations on a filesystem, :mc:`mc` applies this same +behavior by recursively trimming empty directory paths up to the root. However, +the :mc:`mc` remove API cannot distinguish between an explicitly created +directory path and an implicitly created one. If |command| deletes the last +object at a filesystem path, :mc:`mc` recursively deletes all empty directories +within that path up to the root as part of the removal operation. + +.. end-remove-api-trims-prefixes-fs \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-mirror.rst b/source/reference/minio-cli/minio-mc/mc-mirror.rst index 08c044bb..86b6ff0b 100644 --- a/source/reference/minio-cli/minio-mc/mc-mirror.rst +++ b/source/reference/minio-cli/minio-mc/mc-mirror.rst @@ -21,6 +21,23 @@ S3-compatible hosts as the synchronization source. .. end-mc-mirror-desc +MinIO Trims Empty Prefixes on Object Removal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :mc-cmd-option:`mc mirror watch` command continuously synchronizes the +source and destination targets. This includes automatically removing objects +on the destination if they are removed on the source. + +.. |command| replace:: :mc-cmd-option:`mc mirror watch` + +.. include:: /includes/common-admonitions.rst + :start-after: start-remove-api-trims-prefixes + :end-before: end-remove-api-trims-prefixes + +.. include:: /includes/common-admonitions.rst + :start-after: start-remove-api-trims-prefixes-fs + :end-before: end-remove-api-trims-prefixes-fs + Examples -------- diff --git a/source/reference/minio-cli/minio-mc/mc-mv.rst b/source/reference/minio-cli/minio-mc/mc-mv.rst index 73de4453..c7eaa83a 100644 --- a/source/reference/minio-cli/minio-mc/mc-mv.rst +++ b/source/reference/minio-cli/minio-mc/mc-mv.rst @@ -32,6 +32,19 @@ Resume Move Operations Use :mc-cmd-option:`mc mv continue` to resume an interrupted or failed move operation from the point of failure. +MinIO Trims Empty Prefixes on Object Removal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. |command| replace:: :mc-cmd:`mc mv` + +.. include:: /includes/common-admonitions.rst + :start-after: start-remove-api-trims-prefixes + :end-before: end-remove-api-trims-prefixes + +.. include:: /includes/common-admonitions.rst + :start-after: start-remove-api-trims-prefixes-fs + :end-before: end-remove-api-trims-prefixes-fs + Examples -------- diff --git a/source/reference/minio-cli/minio-mc/mc-rm.rst b/source/reference/minio-cli/minio-mc/mc-rm.rst index dd5d0164..4aa7daa9 100644 --- a/source/reference/minio-cli/minio-mc/mc-rm.rst +++ b/source/reference/minio-cli/minio-mc/mc-rm.rst @@ -29,6 +29,17 @@ itself. Any configurations associated to the bucket remain in place, such as To completely remove a bucket, use :mc:`mc rb` instead of :mc:`mc rm`. +MinIO Trims Empty Prefixes on Object Removal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-admonitions.rst + :start-after: start-remove-api-trims-prefixes + :end-before: end-remove-api-trims-prefixes + +.. include:: /includes/common-admonitions.rst + :start-after: start-remove-api-trims-prefixes-fs + :end-before: end-remove-api-trims-prefixes-fs + Examples --------