Home

Awesome

Note: This library is being superseded by CoW support now built into the Windows 11 24H2 release, as well as Windows Server 2025. Use of CoW is automatic for Dev Drive and ReFS volumes starting in these OS versions. See related notes in our blog entry and linked earlier articles. We will continue to accept bug fixes for this library, and updates for the related Microsoft.Build.CopyOnWrite and Microsoft.Build.Artifacts SDKs to use newer versions.

The CopyOnWrite library provides a .NET layer on top of Windows OS-specific logic that provides copy-on-write linking for files (a.k.a. CoW, file cloning, or reflinking). CoW linking provides the ability to copy a file without actually copying the original file's bytes from one disk location to another. The filesystem is in charge of ensuring that if the original file is modified or deleted, the CoW linked files remain unmodified by lazily copying the original file's bytes into each link. Unlike symlinks or hardlinks, writes to CoW links do not write through to the original file, as the filesystem breaks the link and copies in a lazy fashion. This enables scenarios like file caches where a single copy of a file held in a content-addressable or other store is safely linked to many locations in a filesystem with low I/O overhead.

*NOTE: Only Windows functionality is implemented. On Linux and Mac using File.Copy is sufficient as it automatically uses CoW for Linux (starting in .NET 7, and as long as a CoW compatible filesystem like btrfs is in use) and Mac (.NET 8). A similar PR for Windows did not make it into .NET, however there is work underway to integrate CoW into the Windows API in a possible future release.

This library allows a .NET developer to:

Discovery is important, as different operating systems and different filesystems available for those operating systems provide varying levels of CoW link support:

When using this library you may need to create a wrapper that copies the file if CoW is not available.

Example

using Microsoft.CopyOnWrite;

ICopyOnWriteFilesystem cow = CopyOnWriteFilesystemFactory.GetInstance();
bool canCloneInCurrentDirectory = cow.CopyOnWriteLinkSupportedInDirectoryTree(Environment.CurrentDirectory);
if (canCloneInCurrentDirectory)
{
    cow.CloneFile(existingFile, cowLinkFilePath);
}

OS-specific caveats

Windows

File clones on Windows do not actually allocate space on-drive for the clone. This has a good and a possibly bad implication:

Release History

NuGet version (CopyOnWrite)

Related Works

Contributing

This project welcomes contributions and suggestions. See CONTRIBUTING.md.

Running Unit Tests on Windows

If you have a local ReFS drive volume on which to run ReFS related tests, set the following user or system level environment variable:

CoW_Test_ReFS_Drive=D:\

(You may need to exit and restart VS, VSCode, or consoles after setting this.) When this env var is not available, unit tests create and mount a local ReFS VHD for testing and must be run elevated (as admin), e.g. by opening Visual Studio as an admin before opening the solution.

Performance Comparisons

See benchmark data.