From 8cfee71c77e69876a898b40605082f75a6e0420f Mon Sep 17 00:00:00 2001
From: Stefan Bodewig <bodewig@apache.org>
Date: Sun, 1 Jul 2018 10:28:10 +0200
Subject: [PATCH] document what FileUtils#normalize does in a certain edge case

---
 src/main/org/apache/tools/ant/util/FileUtils.java | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/main/org/apache/tools/ant/util/FileUtils.java b/src/main/org/apache/tools/ant/util/FileUtils.java
index 9b5ff4f9e..5e5b94611 100644
--- a/src/main/org/apache/tools/ant/util/FileUtils.java
+++ b/src/main/org/apache/tools/ant/util/FileUtils.java
@@ -723,8 +723,12 @@ public class FileUtils {
      *   <li>DOS style paths that start with a drive letter will have
      *     \ as the separator.</li>
      * </ul>
-     * Unlike {@link File#getCanonicalPath()} this method
-     * specifically does not resolve symbolic links.
+     * <p>Unlike {@link File#getCanonicalPath()} this method
+     * specifically does not resolve symbolic links.</p>
+     *
+     * <p>If the path tries to go beyond the file system root (i.e. it
+     * contains more ".." segments than can be travelled up) the
+     * method will return the original path unchanged.</p>
      *
      * @param path the path to be normalized.
      * @return the normalized version of the path.