Specs

cp_r(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  {:ok, [binary()]} | {:error, posix(), binary()}

Copies the contents in source to destination recursively, maintaining the source directory structure and modes.

If source is a file or a symbolic link to it, destination must be a path to an existent file, a symbolic link to one, or a path to a non-existent file.

If source is a directory, or a symbolic link to it, then destination must be an existent directory or a symbolic link to one, or a path to a non-existent directory.

If the source is a file, it copies source to destination. If the source is a directory, it copies the contents inside source into the destination directory.

If a file already exists in the destination, it invokes callback. callback must be a function that takes two arguments: source and destination. The callback should return true if the existing file should be overwritten and false otherwise.

This function may fail while copying files, in such cases, it will leave the destination directory in a dirty state, where file which have already been copied won't be removed.

The function returns {:ok, files_and_directories} in case of success, files_and_directories lists all files and directories copied in no specific order. It returns {:error, reason, file} otherwise.

Note: The command cp in Unix-like systems behaves differently depending on whether destination is an existing directory or not. We have chosen to explicitly disallow this behaviour. If source is a file and destination is a directory, {:error, :eisdir} will be returned.

Examples

# Copies file "a.txt" to "b.txt"
File.cp_r("a.txt", "b.txt")

# Copies all files in "samples" to "tmp"
File.cp_r("samples", "tmp")

# Same as before, but asks the user how to proceed in case of conflicts
File.cp_r("samples", "tmp", fn source, destination ->
  IO.gets("Overwriting #{destination} by #{source}. Type y to confirm. ") == "y\n"
end)