new__cp_function: inclusive documentation, tests and entry in NEWS.md.

NEWS.md

@@ -243,6 +243,12 @@ Library improvements
 
     * The `randexp` and `randexp!` functions are exported ([#9144])
 
+  * File
+
+    * Added function `readlink` which returns the value of a symbolic link "path" ([#10714]).
+
+    * The `cp` function now accepts keyword arguments `remove_destination` and `follow_symlinks` ([#10888]).
+
   * Other improvements
 
     * You can now tab-complete Emoji characters via their [short names](http://www.emoji-cheat-sheet.com/), using `\:name:<tab>` ([#10709]).
@@ -1374,9 +1380,11 @@ Too numerous to mention.
 [#10659]: https://github.com/JuliaLang/julia/issues/10659
 [#10679]: https://github.com/JuliaLang/julia/issues/10679
 [#10709]: https://github.com/JuliaLang/julia/issues/10709
+[#10714]: https://github.com/JuliaLang/julia/pull/10714
 [#10747]: https://github.com/JuliaLang/julia/issues/10747
 [#10844]: https://github.com/JuliaLang/julia/issues/10844
 [#10870]: https://github.com/JuliaLang/julia/issues/10870
 [#10885]: https://github.com/JuliaLang/julia/issues/10885
+[#10888]: https://github.com/JuliaLang/julia/pull/10888
 [#10893]: https://github.com/JuliaLang/julia/pull/10893
 [#10914]: https://github.com/JuliaLang/julia/issues/10914

base/file.jl

@@ -70,18 +70,47 @@ end
 
 # The following use Unix command line facilites
 
-function cp(src::AbstractString, dst::AbstractString; recursive::Bool=false)
-    if islink(src) || !isdir(src)
-        FS.sendfile(src, dst)
-    elseif recursive
-        mkdir(dst)
-        for p in readdir(src)
-            cp(joinpath(src, p), joinpath(dst, p), recursive=recursive)
+function cptree(src::AbstractString, dst::AbstractString; remove_destination::Bool=false,
+                                                             follow_symlinks::Bool=false)
+    isdir(src) || throw(ArgumentError("'$src' is not a directory. Use `cp(src, dst)`"))
+    if ispath(dst)
+        if remove_destination
+            rm(dst; recursive=true)
+        else
+            throw(ArgumentError(string("'$dst' exists. `remove_destination=true` ",
+                                       "is required to remove '$dst' before copying.")))
+        end
+    end
+    mkdir(dst)
+    for name in readdir(src)
+        srcname = joinpath(src, name)
+        if !follow_symlinks && islink(srcname)
+            symlink(readlink(srcname), joinpath(dst, name))
+        elseif isdir(srcname)
+            cptree(srcname, joinpath(dst, name); remove_destination=remove_destination,
+                                                 follow_symlinks=follow_symlinks)
+        else
+            FS.sendfile(srcname, joinpath(dst, name))
         end
+    end
+end
+
+function cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false,
+                                                         follow_symlinks::Bool=false)
+    if ispath(dst)
+        if remove_destination
+            rm(dst; recursive=true)
+        else
+            throw(ArgumentError(string("'$dst' exists. `remove_destination=true` ",
+                                       "is required to remove '$dst' before copying.")))
+        end
+    end
+    if !follow_symlinks && islink(src)
+        symlink(readlink(src), dst)
+    elseif isdir(src)
+        cptree(src, dst; remove_destination=remove_destination, follow_symlinks=follow_symlinks)
     else
-        throw(ArgumentError(string("'$src' is a directory. ",
-            "Use `cp(src, dst, recursive=true)` ",
-            "to copy directories recursively.")))
+        FS.sendfile(src, dst)
     end
 end
 mv(src::AbstractString, dst::AbstractString) = FS.rename(src, dst)

doc/helpdb.jl

@@ -5172,10 +5172,14 @@ Millisecond(v)
 
 "),
 
-("Base","cp","cp(src::AbstractString, dst::AbstractString; recursive=false)
+("Base","cp","cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false)
 
-   Copy a file from *src* to *dest*. Passing \"recursive=true\" will
-   enable recursive copying of directories.
+   Copy the file, link, or directory from *src* to *dest*.
+   \"remove_destination=true\" will first remove an existing `dst`.
+
+   If `follow_symlinks=false`, and src is a symbolic link, dst will be created as a symbolic link.
+   If `follow_symlinks=true` and src is a symbolic link, dst will be a copy of the file or directory
+   `src` refers to.
 
 "),
 

doc/stdlib/file.rst

@@ -109,10 +109,14 @@
    Like uperm but gets the permissions for people who neither own the file nor are a
    member of the group owning the file
 
-.. function:: cp(src::AbstractString,dst::AbstractString; recursive=false)
+.. function:: cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false)
 
-   Copy a file from `src` to `dest`. Passing ``recursive=true`` will enable
-   recursive copying of directories.
+   Copy the file, link, or directory from *src* to *dest*.
+   \"remove_destination=true\" will first remove an existing `dst`.
+
+   If `follow_symlinks=false`, and src is a symbolic link, dst will be created as a symbolic link.
+   If `follow_symlinks=true` and src is a symbolic link, dst will be a copy of the file or directory
+   `src` refers to.
 
 .. function:: download(url,[localfile])