The behavior of File.rename, Link.rename, and Directory.rename differs on different platforms, and is not specified correctly in the documentation.

The underlying rename provided by the OS differs on Windows and Linux, so Linux is atomic in some cases, and Windows is never guaranteed to be atomic. Overwriting an existing file system object has different behavior, depending on the type of the object overwritten.

To make a uniform specification, we should implement .replace that overwrites the target no matter what it is, but this would use non-atomic delete, rename sequences for some cases.

The fact that rename is atomic in some cases on some platforms would be an additional piece of information, not part of the basic behavior of rename.

When renaming a directory, we need to be careful of cases where the source and target have a parent-child relationship, and in all cases we want x.rename(x) to be a no-op.