[io] copyPath/copyPathSync: add a deepCopyLinks parameter (#1267)

The original intention was to create new `Link` objects when copying
links, but the implementation left the implicit `followLinks: true`
argument which meant that in practice links were recursed into and files
and directories deeply copied. This behavior is the only behavior that
will work when there are links present and the copy is across volumes
which do not permit links, but it is not the optimal behavior for most
use cases. Add a `deepCopyLinks` argument which defaults to `true` to
keep the current behavior by default, but allow the smaller copy with
shallow links through a boolean argument.

Update the doc and add tests for the behavior around links both with and
without the argument.

Author: gmpassos

pkgs/io/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.1.0-wip
+
+* Add a `deepCopyLinks` argument to `copyPath` and `copyPathSync`.
+
 ## 1.0.5
 
 * Require Dart 3.4.

pkgs/io/lib/src/copy_path.dart

@@ -19,18 +19,23 @@ bool _doNothing(String from, String to) {
 /// Copies all of the files in the [from] directory to [to].
 ///
 /// This is similar to `cp -R <from> <to>`:
-/// * Symlinks are supported.
 /// * Existing files are over-written, if any.
 /// * If [to] is within [from], throws [ArgumentError] (an infinite operation).
 /// * If [from] and [to] are canonically the same, no operation occurs.
+/// * If [deepCopyLinks] is `true` (the default) then links are followed and
+///   the content of linked directories and files are copied entirely. If
+///   `false` then new [Link] file system entities are created linking to the
+///   same target the links under [from].
 ///
 /// Returns a future that completes when complete.
-Future<void> copyPath(String from, String to) async {
+Future<void> copyPath(String from, String to,
+    {bool deepCopyLinks = true}) async {
   if (_doNothing(from, to)) {
     return;
   }
   await Directory(to).create(recursive: true);
-  await for (final file in Directory(from).list(recursive: true)) {
+  await for (final file
+      in Directory(from).list(recursive: true, followLinks: deepCopyLinks)) {
     final copyTo = p.join(to, p.relative(file.path, from: from));
     if (file is Directory) {
       await Directory(copyTo).create(recursive: true);
@@ -45,18 +50,22 @@ Future<void> copyPath(String from, String to) async {
 /// Copies all of the files in the [from] directory to [to].
 ///
 /// This is similar to `cp -R <from> <to>`:
-/// * Symlinks are supported.
 /// * Existing files are over-written, if any.
 /// * If [to] is within [from], throws [ArgumentError] (an infinite operation).
 /// * If [from] and [to] are canonically the same, no operation occurs.
+/// * If [deepCopyLinks] is `true` (the default) then links are followed and
+///   the content of linked directories and files are copied entirely. If
+///   `false` then new [Link] file system entities are created linking to the
+///   same target the links under [from].
 ///
 /// This action is performed synchronously (blocking I/O).
-void copyPathSync(String from, String to) {
+void copyPathSync(String from, String to, {bool deepCopyLinks = true}) {
   if (_doNothing(from, to)) {
     return;
   }
   Directory(to).createSync(recursive: true);
-  for (final file in Directory(from).listSync(recursive: true)) {
+  for (final file in Directory(from)
+      .listSync(recursive: true, followLinks: deepCopyLinks)) {
     final copyTo = p.join(to, p.relative(file.path, from: from));
     if (file is Directory) {
       Directory(copyTo).createSync(recursive: true);

pkgs/io/pubspec.yaml

@@ -2,7 +2,7 @@ name: io
 description: >-
   Utilities for the Dart VM Runtime including support for ANSI colors, file
   copying, and standard exit code values.
-version: 1.0.5
+version: 1.1.0-wip
 repository: https://github.com/dart-lang/tools/tree/main/pkgs/io
 
 environment:

pkgs/io/test/copy_path_test.dart

@@ -5,6 +5,8 @@
 @TestOn('vm')
 library;
 
+import 'dart:io';
+
 import 'package:io/io.dart';
 import 'package:path/path.dart' as p;
 import 'package:test/test.dart';
@@ -33,6 +35,82 @@ void main() {
       throwsArgumentError,
     );
   });
+
+  group('links', () {
+    const linkTarget = 'link_target';
+    const linkSource = 'link_source';
+    const linkContent = 'link_content.txt';
+    late String targetPath;
+    setUp(() async {
+      await _create();
+      await d
+          .dir(linkTarget, [d.file(linkContent, 'original content')]).create();
+      targetPath = p.join(d.sandbox, linkTarget);
+      await Link(p.join(d.sandbox, _parentDir, linkSource)).create(targetPath);
+    });
+
+    test('are shallow copied with deepCopyLinks: false in copyPath', () async {
+      await copyPath(
+          deepCopyLinks: false,
+          p.join(d.sandbox, _parentDir),
+          p.join(d.sandbox, _copyDir));
+
+      final expectedLink = Link(p.join(d.sandbox, _copyDir, linkSource));
+      expect(await expectedLink.exists(), isTrue);
+      expect(await expectedLink.target(), targetPath);
+    });
+
+    test('are shallow copied with deepCopyLinks: false in copyPathSync',
+        () async {
+      copyPathSync(
+          deepCopyLinks: false,
+          p.join(d.sandbox, _parentDir),
+          p.join(d.sandbox, _copyDir));
+
+      final expectedLink = Link(p.join(d.sandbox, _copyDir, linkSource));
+      expect(await expectedLink.exists(), isTrue);
+      expect(await expectedLink.target(), targetPath);
+    });
+
+    test('are deep copied by default in copyPath', () async {
+      await copyPath(
+          p.join(d.sandbox, _parentDir), p.join(d.sandbox, _copyDir));
+
+      final expectedDir = Directory(p.join(d.sandbox, _copyDir, linkSource));
+      final expectedFile =
+          File(p.join(d.sandbox, _copyDir, linkSource, linkContent));
+      expect(await expectedDir.exists(), isTrue);
+      expect(await expectedFile.exists(), isTrue);
+
+      expect(await expectedFile.readAsString(), 'original content',
+          reason: 'The file behind the link was copied with invalid content');
+
+      await expectedFile.writeAsString('new content');
+      final originalFile =
+          File(p.join(d.sandbox, _parentDir, linkSource, linkContent));
+      expect(await originalFile.readAsString(), 'original content',
+          reason: 'The file behind the link should not change');
+    });
+
+    test('are deep copied by default in copyPathSync', () async {
+      copyPathSync(p.join(d.sandbox, _parentDir), p.join(d.sandbox, _copyDir));
+
+      final expectedDir = Directory(p.join(d.sandbox, _copyDir, linkSource));
+      final expectedFile =
+          File(p.join(d.sandbox, _copyDir, linkSource, linkContent));
+      expect(await expectedDir.exists(), isTrue);
+      expect(await expectedFile.exists(), isTrue);
+
+      expect(await expectedFile.readAsString(), 'original content',
+          reason: 'The file behind the link was copied with invalid content');
+
+      await expectedFile.writeAsString('new content');
+      final originalFile =
+          File(p.join(d.sandbox, _parentDir, linkSource, linkContent));
+      expect(await originalFile.readAsString(), 'original content',
+          reason: 'The file behind the link should not change');
+    });
+  });
 }
 
 const _parentDir = 'parent';