MinIO Implicit Prefix Trimming on Removal of Last Object (see minio/mc issue#3621)

source/includes/common-admonitions.rst

@@ -15,4 +15,52 @@
    a maintenance period to minimize interruption of services while performing
    this procedure.
 
-.. end-restart-downtime
+.. 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

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

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

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