Fix symlink copy failing when source and dest symlinks point to same target

[PazerOP]

I couldn't see anything immediately obvious banning AI PRs, hope this isn't a bother. I had Claude create this fix for part of the build process of https://neutralino.js.org/.

When copying a directory containing symlinks, if the destination already contains symlinks pointing to the same target as the source symlinks, the operation would incorrectly fail with "Cannot copy X to a subdirectory of itself" error.

This happened because the isSrcSubdir() check returns true when two paths are identical. However, two different symlinks that happen to point to the same target are distinct filesystem entries that should be copyable.

The fix adds a check to ensure the resolved paths are actually different before applying the subdirectory constraints. When both symlinks resolve to the same target (resolvedSrc === resolvedDest), we skip the subdirectory checks and allow the copy to proceed, which correctly replaces the destination symlink with the source symlink.

Fixes issue where:

• Source: ./src/link → symlink to /tmp/target
• Dest: ./dest/link → symlink to /tmp/target
• copySync('./src', './dest') would fail

Added comprehensive test cases for:

• Copy symlink when dest has no existing symlink
• Overwrite symlink when dest has symlink pointing to SAME target
• Overwrite symlink when dest has symlink pointing to DIFFERENT target
• File symlinks with same target
• Edge case: copying symlink to itself still fails
• Edge case: copying symlink into subdirectory of its target works

[RyanZim]

Nevermind the macOS CI failures; unrelated to this PR.

[RyanZim]

macOS CI fixed in #1061; feel free to rebase.

[RyanZim]

LGTM; just might be good to have a little more test completeness. This is a fix for #1019, right?

[RyanZim]

I couldn't see anything immediately obvious banning AI PRs, hope this isn't a bother. I had Claude create this fix

@PazerOP Not a bother at all, this PR is in better shape than a lot of human-created PRs I see. OOI, what was your prompt?

[PazerOP]

I couldn't see anything immediately obvious banning AI PRs, hope this isn't a bother. I had Claude create this fix

@PazerOP Not a bother at all, this PR is in better shape than a lot of human-created PRs I see. OOI, what was your prompt?

It's a bit of a stretch to call this a prompt IMO, basically handed it the answer. This is the result of debugging the problem in Claude Code CLI, then saying "just describe in detail the issue and how to fix it, i'll delegate it to another coding agent". Then I stuck this in the web edition of Claude Code Opus 4.5. It took 8.5 minutes.

Issue: fs-extra incorrectly fails when copying symlinks that point to the same target

Problem Description

When using fs-extra's copy() or copySync() functions to copy a directory containing symlinks, if the destination already contains symlinks pointing to the same target as the source symlinks, the operation fails with:

Error: Source and destination must not be the same.

This is incorrect behavior. Two different symlinks that happen to point to the same target are not the same file - they are distinct filesystem entries that should be copyable/overwritable.

Root Cause

In /node_modules/fs-extra/lib/util/stat.js, lines 9-10:

const stat = (file) => nodeSupportsBigInt ? fs.stat(file, { bigint: true }) : fs.stat(file)
const statSync = (file) => nodeSupportsBigInt ? fs.statSync(file, { bigint: true }) : fs.statSync(file)

The fs.stat() function follows symlinks and returns the stat of the target file. When checkPaths() (line 34-46) compares source and destination using areIdentical(), it compares the resolved target's inode, not the symlink's inode.

So when you have:

Source: ./extensions/bin → symlink to /tmp/build/bin
Dest: ./dist/extensions/bin → symlink to /tmp/build/bin

Both fs.stat() calls return the stat of /tmp/build/bin, making areIdentical() return true (same inode), triggering the error.

Proposed Fix

Change fs.stat to fs.lstat so it compares the symlinks themselves, not their targets:

// Use lstat to not follow symlinks - two different symlinks pointing to the same target are NOT the same file
const stat = (file) => nodeSupportsBigInt ? fs.lstat(file, { bigint: true }) : fs.lstat(file)
const statSync = (file) => nodeSupportsBigInt ? fs.lstatSync(file, { bigint: true }) : fs.lstatSync(file)

Affected Versions

fs-extra: At least version 9.x-11.x (current in neutralino-cli)
This affects any OS with symlink support: macOS, Linux, Windows (with developer mode)

Test Cases Needed

Basic symlink copy: Copy directory with symlink, no existing dest → should work
Overwrite symlink with same target: Copy symlink over existing symlink pointing to same target → should work (currently fails)
Overwrite symlink with different target: Copy symlink over existing symlink pointing to different target → should work
Copy regular files: Ensure the change doesn't break regular file identity checks
Prevent actual same-file copy: cp file file should still fail (same actual path)
Cross-device symlink copy: Symlinks on different volumes pointing to same target

Files to Modify

fs-extra (lib/util/stat.js):

Line 9: fs.stat → fs.lstat
Line 10: fs.statSync → fs.lstatSync

Reproduction Steps
Setup

mkdir -p /tmp/target /tmp/src /tmp/dest
echo "content" > /tmp/target/file.txt
ln -s /tmp/target /tmp/src/link
ln -s /tmp/target /tmp/dest/link
This fails with current fs-extra

node -e "require('fs-extra').copySync('/tmp/src', '/tmp/dest')"
Error: Source and destination must not be the same.

Related Issues

https://github.com/jprichardson/node-fs-extra/issues/657
https://github.com/jprichardson/node-fs-extra/issues/792

[PazerOP]

I believe this fixes #639, #1019, #1027, and #1043.

[JPeer264]

LGTM. Amazing that you added so many tests for it

[PazerOP]

Thanks. I think someone needs to approve the Github Actions workflow to run before this can be merged.

[manidlou]

LGTM

[RyanZim]

Will release tomorrow.

BTW, unless things have changed since then, as per #1019 (comment), this is also a bug in Node core fs.cp. We should report this and explore if backporting this fix is feasible.

[RyanZim]

Published as v11.3.3 🎉