I suggest we add a 'followLinks' argument to stat/statSync, to it matches how we do it other places, where we want to differentiate between working on the path directly and working on the resolved path.

In this case it should default to 'true' for backward compatibility.

Thoughts?

cc @lrhn.

Removed Priority-Unassigned label.
Added Priority-Medium label.

We actually do what we promise, the documentation in file.dart says:

 * ## If path is a link
 *
 * If [path] is a symbolic link, rather than a file,
 * then the methods of File operate on the ultimate target of the
 * link, except for [delete] and [deleteSync], which operate on
 * the link.

so currently stat and statSync cannot return a FileStat object with type LINK. The only way to check for link is using FileSystemEntity.type and FileSystemEntity.typeSync with 'followLinks' set to true.

Adding 'followLinks' to stat/statSync fits well with this pattern already used.

Can we add a note or two to the statSync method, reminding the developer about the "if path is a link" ? That's really useful info, but it's "far away" from statSync. :)

FWIW, in POSIX, following symlinks is the normal behavior for stat. There is traditionally a separate lstat function for operating on links.

Personally I'd prefer a followLinks named parameter on the existing FileSystemEntity.stat/statSync and FileStat.stat functions, but a separate FileStat.lstat function would be acceptable too if there are compatibility concerns.

On Windows we are currently not resolving symlinks. I'll fix that and update the docs as my first step.

Adding a followLinks named parameter isn't feasible because it would break any subclasses of FileSystemEntity (of which there are many). Likewise for IOOverrides.

I think that @jamesderlin 's proposal of having a lstat method is reasonable.

Any thoughts?

lstat might have to be an extension method, because it's a breaking change to add a new instance method to a widely used class.

@eernstg Making lstat an extension method would work but how would we add it to IOOverrides?

I don't know any details about IOOverrides, but taking a look at it I would expect that the lstat method would have to use a similar technique as the existing implementation of, say, statSync:

  static FileStat statSync(String path) {
    final IOOverrides? overrides = IOOverrides.current;
    if (overrides == null) {
      return _statSyncInternal(path);
    }
    return overrides.statSync(path);
  }

IOOverrides.current is accessible from the extension method, and overrides.lstatSync(path) should work from there as well, so it looks like there is nothing that prevents using the same technique in an extension method.

Let me take a step back - I don't understand why we can't add a new method to a widely used class. Is that because a subclass might already define the same method but, for example, with a different signature?

If that is the issue, then wouldn't the same issue exist when adding lstat to IOOverrides? Or would we also implement that as an extension method?

The typical problem with adding methods is if there is a derived class that implements the interface. Adding a method to the interface would be a breaking change since all implementers would need to add the new method.

In this case, a notable implementation of dart:io's File class is the File class from package:file.

It might be OK to implement lstat/lstatSync as new instance methods on class IOOverrides, because that class is intended to have subclasses (so extends IOOverrides is OK), but not other subtypes (so implements IOOverrides does not seem to be recommended, and also does not seem to be used anywhere that I could spot right now).