From 91f0c3c34298bc2e995b62a3bb715ff4b8a60f87 Mon Sep 17 00:00:00 2001
From: Abduqodiri Qurbonzoda <abduqodiri.qurbonzoda@jetbrains.com>
Date: Fri, 16 Jun 2023 22:40:56 +0000
Subject: [PATCH] Clarify copyToRecursively doc about symlinks #SDP-1816

This MR is the result of the security audit that was conducted for Path recursive functions:
https://youtrack.jetbrains.com/issue/SDP-1816/Security-issues-of-Path-recursive-functions-in-StdLib#focus=Comments-27-7269144.0-0
Eliminates confusions regarding symbolic links.

Merge-request: KT-MR-10245
Merged-by: Abduqodiri Qurbonzoda <abduqodiri.qurbonzoda@jetbrains.com>
---
 .../kotlin/io/path/PathRecursiveFunctions.kt   | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/libraries/stdlib/jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt b/libraries/stdlib/jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt
index 9684aa414bd..5623c8e16cb 100644
--- a/libraries/stdlib/jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt
+++ b/libraries/stdlib/jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt
@@ -40,8 +40,13 @@ import java.nio.file.attribute.BasicFileAttributes
  * and the corresponding entry in the target subtree already exists and is also a directory, it does nothing.
  * Otherwise, [overwrite] determines whether to overwrite existing destination entries.
  * Attributes of a source entry, such as creation/modification date, are not copied.
- * [followLinks] determines whether to copy a symbolic link itself or its target.
- * Symbolic links in the target subtree are not followed.
+ *
+ * [followLinks] impacts only symbolic links in the source subtree and
+ * determines whether to copy a symbolic link itself or the entry it points to.
+ * Symbolic links in the target subtree are not followed, i.e.,
+ * no entry is copied to the location a symbolic link points to.
+ * If a copy destination is a symbolic link, it is overwritten or an exception is thrown depending on [overwrite].
+ * Note that symbolic links on the way to the roots of the source and target subtrees are always followed.
  *
  * To provide a custom logic for copying use the overload that takes a `copyAction` lambda.
  *
@@ -115,8 +120,13 @@ public fun Path.copyToRecursively(
  * and the corresponding entry in the target subtree already exists and is also a directory, it does nothing.
  * Otherwise, the entry is copied using `sourcePath.copyTo(destinationPath, *followLinksOption)`,
  * which doesn't copy attributes of the source entry and throws if the destination entry already exists.
- * [followLinks] determines whether to copy a symbolic link itself or its target.
- * Symbolic links in the target subtree are not followed.
+ *
+ * [followLinks] impacts only symbolic links in the source subtree and
+ * determines whether to copy a symbolic link itself or the entry it points to.
+ * Symbolic links in the target subtree are not followed, i.e.,
+ * no entry is copied to the location a symbolic link points to.
+ * If a copy destination is a symbolic link, an exception is thrown.
+ * Note that symbolic links on the way to the roots of the source and target subtrees are always followed.
  *
  * If a custom implementation of [copyAction] is provided, consider making it consistent with [followLinks] value.
  * See [CopyActionResult] for available options.