From 942a6ec9d06ae8b564f63362ef1422b065ea285c Mon Sep 17 00:00:00 2001
From: "Gregory P. Smith" <greg@krypto.org>
Date: Thu, 22 Oct 2026 22:03:35 +0000
Subject: [PATCH] gh-160322: document shutil.rmtree("link/") symlink following
 behavior

---
 Doc/library/shutil.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 2822e979990c4de..b7e2bc3212511bf 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -316,6 +316,12 @@ Directory and files operations
    handled by calling a handler specified by *onexc* or *onerror* or, if both
    are omitted, exceptions are propagated to the caller.
 
+   If *path* is a symbolic link to a directory followed by a trailing path
+   separator, such as ``'link/'``, the operating system resolves the link, so
+   :func:`!rmtree` deletes the contents of the directory it points to and then
+   fails to remove *path* itself.  :class:`pathlib.Path` strips trailing
+   separators, so ``rmtree(Path('link/'))`` refuses the link as usual.
+
    This function can support :ref:`paths relative to directory descriptors
    <dir_fd>`.