Instruction 02-hardlinks-atomic-moves-and-import-efficiency: Reading

A pathname is a human-readable route through one or more directories. For a regular file, the final directory entry refers to an inode, and the inode refers to the file's metadata and data blocks. Creating a hardlink adds another directory entry for the same inode. It does not copy the file's payload. Consequently, two hardlinked paths on the same filesystem normally report the same device number and inode number, while the inode's link count increases. Removing one name does not destroy the data while another hardlink or an open file descriptor still refers to the inode.

Hardlinks are valuable in import workflows where a downloader must retain a completed file for seeding while a library application needs its own organized pathname. A hardlink can provide both names without a second full data copy. This only works when the source and destination are on the same filesystem. Separate mountpoints may look like ordinary directories in a single directory tree, but if their device identifiers differ, the kernel cannot create a hardlink between them. Bind mounts can complicate visual inspection, so compare filesystem identity with stat or findmnt rather than relying only on path layout.

A hardlink is not an independent snapshot. Writing through either path changes the shared inode and is visible through the other path. By contrast, replacing one path with a newly created inode changes only that directory entry; other hardlinks continue to refer to the prior inode. This distinction is important when download clients, taggers, transcoders, or library managers may modify files after import. Applications should treat linked payloads as immutable or deliberately coordinate modifications.

A same-filesystem rename is an efficient metadata operation and provides atomic namespace visibility. If a completed temporary file is renamed over a destination, a process opening the destination afterward sees the replacement. A process that already had the old file open may continue reading the old inode. Atomicity prevents readers from observing a half-renamed pathname, but it does not prove that the file content was complete before publication. The producer must finish and close the temporary file first. Atomic rename also does not, by itself, guarantee crash durability; software requiring strong durability must use appropriate file and directory synchronization before acknowledging success.

The safest import pattern is to validate a completed source, create a uniquely named temporary hardlink inside the destination directory, and then rename that temporary name to the final name. Creating the temporary entry in the destination directory ensures the final publication rename remains on one filesystem. Collision policy must be explicit: fail, version, quarantine, or intentionally replace. Never assume that a command called move is always an atomic rename. When source and destination are on different filesystems, a utility may perform a copy followed by source removal, creating a longer window in which partial destination data must be managed. Import efficiency should therefore be evaluated by filesystem identity, inode identity, link count, integrity checks, and application behavior rather than by path names or elapsed-time claims.