Replacing a file with a hardlink means deleting a directory entry and creating another in its place. Done carelessly that is a way to lose data, so each step is gated.
Gate one: same volume. Hardlinks cannot cross filesystems. DupeDoctor compares volumes by serial number rather than by drive letter, which matters because the same volume can be reachable under more than one letter or mount point, and different volumes can look similar by path. Anything not on the keeper's volume is refused.
Gate two: byte identity, re-verified now. Even though the group came from a full-hash match, both files are hashed again immediately before anything is modified, and the operation aborts unless the digests match. This closes the window between scanning and acting: a file may have been edited, replaced, or swapped in the interval, and a hardlink created on stale information would silently discard the newer content. The re-check is the difference between trusting a scan result and confirming it.
Gate three: protected locations. Both the keeper and every target are checked against the protected system roots, and either one being inside them refuses the operation.
The atomic swap. The link is not created over the target directly. It is created beside it under a temporary name, and only then renamed into place — a rename being the operation the filesystem can perform atomically. If anything fails partway, the rollback path restores the original state, and a regression test specifically covers the case where the relink fails and asserts the target is left intact. The keeper is never removed, and an attempt to relink the keeper onto itself is refused.
What to understand before using it. Because both names point at the same data, writing through one path changes what the other sees. That is the correct and intended behaviour of a hardlink, and it is exactly what you want for immutable shared assets — but it is not what you want for two files you expect to diverge later. For those, deleting a redundant copy or moving it to quarantine is the better action. Hardlinking is also offered only for exact matches, never for perceptual ones, since replacing a file with a link to something merely similar would destroy data.
