[API Proposal]: CopyFileOrDirectory

[dennisdoomen]

Background and motivation

ChainablePathExtensions offers CreateDirectoryRecursively, DeleteFileOrDirectory and MoveFileOrDirectory, but not copy. Copying is at least as common as moving in build scripts and tests, and a recursive directory copy is genuinely tedious to write correctly by hand (creating intermediate directories, preserving relative structure, deciding what to do about existing files). The gap is conspicuous next to the existing move support, including its collection overload.

API Proposal

namespace Pathy
{
    public static class ChainablePathExtensions
    {
        public static void CopyFileOrDirectory(
            this ChainablePath sourcePath,
            ChainablePath destinationDirectory,
            string newName = null,
            bool overwrite = false);

        public static void CopyFileOrDirectory(
            this IEnumerable<ChainablePath> sourcePaths,
            ChainablePath destinationDirectory,
            bool overwrite = false);
    }
}

The signature deliberately mirrors the existing MoveFileOrDirectory overloads.

API Usage

// Copy a single file, optionally renaming it
(ChainablePath.Current / "appsettings.json")
    .CopyFileOrDirectory(ChainablePath.Temp / "config", newName: "appsettings.local.json");

// Copy a whole directory tree
(ChainablePath.Current / "templates")
    .CopyFileOrDirectory(outputDirectory, overwrite: true);

// Copy a matched set of files
(ChainablePath.Current / "src")
    .GlobFiles("**/*.md")
    .CopyFileOrDirectory(docsDirectory);

Alternative Designs

Separate CopyFile and CopyDirectory methods. The library has already chosen the combined FileOrDirectory naming for delete and move, so following it keeps the API predictable.

Risks

Copying a directory into itself or into one of its own descendants must be detected, otherwise the operation never terminates. The default for overwrite should match whatever MoveFileOrDirectory does today, and the behaviour when the destination directory does not yet exist has to be defined (most likely: create it).