fs: Change the default value of `mode` argument of `fs.copyFile()` to `fs.constants.COPYFILE_FICLONE`

What is the problem this feature will solve?

Today's operating systems and some file systems supports copy-on-write operation for copying a file (e.g. btrfs on Linux, APFS on Apple's Darwins).

fs.copyFile() has already supported them as opt-in behavior if the underlying platform support such operations and libuv support them.

• https://nodejs.org/api/fs.html#fspromisescopyfilesrc-dest-mode
• https://github.com/libuv/libuv/blob/3f331e97da5b1cc2e24765dcb6d26c9dd313418f/src/unix/fs.c#L1309-L1490

However, it's still opt-in behavior.

The default value of mode argument. of fs.copyFile() is 0. This mean that fs.copyFile() does not use copy-on-write and use traditional copying mechanism operation even if the underlying platform and libuv supports such operation.

An user can use copy-on-write operation by passingfs.constants.COPYFILE_FICLONE to mode argument.

But if we forget to pass it, fs.copyFile() does not use an enhancement underlying mechanism. We (all programmers) tend to forget to supply a such optional flag to API and to lose a chance to improve a performance. I think this is a bug for API egonomics and having a value we should fix.

What is the feature you are proposing to solve the problem?

My proposal is changing the default value of mode argument of fs.copyFile() to fs.constants.COPYFILE_FICLONE from 0.

By this change, all exist programs using fs.copyFile() in all over the world can get a chance to improve their throughput without any code change.

If the underlying platform does not support copy-on-write behavior, then fs.constants.COPYFILE_FICLONE flag fallback into the traditional approach. I think this change is painless approach.

fs.constants.COPYFILE_FICLONE: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then a fallback copy mechanism is used.

https://nodejs.org/api/fs.html#fspromisescopyfilesrc-dest-mode

What alternatives have you considered?

1. This change might be a "breaking change" if we think it strictly. If there is a user program expect fs.copyFile() copy a file without copy-on-write, this change would be problematic.
   • I think it's not be a problem to change a file copying mechanism for user program. It's an abstracted problem by a platform (Node.js, operation system, and file system). An user program should be agnostic about it.
   • But I'm not sure about the Node.js' committee's breaking change policy, I note about this point as a consideration.
2. This also affects the behavior of other APIs that uses fs.copyFile() internally (e.g. fs.cp()).

Review the fs.copyFile() API and the fs.constants.COPYFILE_FICLONE behavior, then inspect libuv's src/unix/fs.c implementation. Consider the related fs.cp() behavior and compatibility implications before deciding what tests and documentation would define completion.