merge from 3.2 - Fix closes issue12577 - clarify shutil.move documentation. Patch suggestion by Catalin Iacob
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 1b160d8..ed622ad 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -163,8 +163,10 @@
Recursively move a file or directory to another location.
- If the destination is on the current filesystem, then simply use rename.
- Otherwise, copy src (with :func:`copy2`) to the dst and then remove src.
+ Uses :func:`os.rename` to perform the move. If it fails, for reasons such as
+ when *src* and *dst* are on different filesystems or in case of windows where
+ rename is not supported when *dst* exists, fallback to copying *src* (with
+ :func:`copy2`) to the *dst* and then remove *src*.
.. versionadded:: 2.3