[API Proposal]: TouchFile and SetLastWriteTimeUtc

[dennisdoomen]

Background and motivation

LastWriteTimeUtc was added as a read-only property, but there is no way to set it and no way to create an empty file or update its timestamp. Both are staples of build scripts: creating a sentinel or stamp file, marking a target as up to date, and forcing a rebuild by touching an input. Tests that verify timestamp-based logic also need to set the timestamp deterministically rather than sleeping.

API Proposal

namespace Pathy
{
    public static class ChainablePathExtensions
    {
        public static ChainablePath TouchFile(this ChainablePath path);
        public static void SetLastWriteTimeUtc(this ChainablePath path, DateTime value);
    }
}

TouchFile creates the file (and its parent directories) when it does not exist, and updates the last write time when it does. It returns the path so it can be chained.

API Usage

var stamp = (artifacts / ".build-complete").TouchFile();

// Make a test deterministic instead of sleeping
(temp / "input.txt").SetLastWriteTimeUtc(DateTime.UtcNow.AddHours(-1));

if (output.LastWriteTimeUtc < input.LastWriteTimeUtc)
{
    Rebuild();
}

Alternative Designs

• Make LastWriteTimeUtc a settable property. Not possible in the current shape without turning the readonly struct into something mutable, and a property setter that performs file system I/O is misleading anyway.
• Add CreateFile() separately from touching. Most callers want the combined behaviour that touch provides.

Risks

Whether TouchFile should create missing parent directories needs a decision; doing it silently is convenient but hides typos. Setting a timestamp on a directory should either work consistently or be documented as unsupported.