Documentation

(edited)

The PR 119058 and 122369 added pathlib.Path.copy(), with Copy-on-Write support. CoW should be documented, because it has distinctive, user-requested properties on huge files.

• Copying is instantaneous, does negligible I/O, requires no disk space for the data and negligible disk space for the metadata.
• Reading the original and the copy does half the I/O and requires half the RAM (page cache) than a traditional copy (think booting VM images)

In the context of a Linux VM manager, CoW is an explicit desired property. Disk image copying is the slowest part of snapshotting a VM. Users expect CoW snapshots nowadays, and intentionally set up a CoW filesystem for the disk image directory.

For clarity, I'm not asking to mention FICLONE specifically. I'm not asking to mention copy_file_range, a micro-optimization on the traditional copy algorithm. Instead, my point is that switching from O(file size) to zero is a user-visible feature.

Keywords: reflink copy

Linked PRs

• GH-124985: Document that pathlib.Path.copy() uses copy-on-write. #125861