rsync --link-dest: incremental snapshots with hard links to the previous backup
- tool
- rsync
- command
- rsync
- flag
- --link-dest=DIR
- default
- unset: every file is copied into the destination
rsync --link-dest=DIR compares each source file with the same path inside DIR (usually the previous backup) and, when the file is unchanged, creates a hard link to it in the new destination instead of copying it. Changed and new files are transferred normally. The result is a series of snapshot directories that each look like a full copy, while unchanged files take disk space only once. It is the mechanism behind many "Time Machine style" rsync backup scripts.
Syntax
rsync -a --link-dest=/backups/2026-10-23 /home/ /backups/2026-10-24/
rsync -a --link-dest=../2026-10-23 /home/ /backups/2026-10-24/ # relative: resolved from the destination
rsync -av --link-dest="$PWD/prior_dir" host:src_dir/ new_dir/A typical daily script keeps a latest symlink:
today=$(date +%F)
rsync -a --delete --link-dest=/backups/latest /home/ "/backups/$today/"
ln -sfn "/backups/$today" /backups/latestThe alternate-destination options
| Option | If an identical file exists in DIR |
|---|---|
| --compare-dest=DIR | The file is not transferred and not created in the destination (sparse backup of changes only) |
| --copy-dest=DIR | The file is copied locally from DIR into the destination |
| --link-dest=DIR | The file is hard linked from DIR into the destination |
All three accept several directories (searched in the order given; --link-dest up to 20). If a match differs only in attributes, rsync makes a local copy and updates the attributes; if no exact match exists, a file from DIR is still used as a basis to speed up the delta transfer.
Conditions for a hard link
- Identical in all preserved attributes. With
-a, permissions, times, owner and group must match. If files are not linking, check attributes first, including mount options that force ownership (removable drives with "ignore ownership", root squashing on NFS). - Same file system. Hard links cannot cross file systems, so DIR and the destination must be on the same volume.
- Not combined with -I.
--ignore-timesmakes rsync update every file, and it links only as a substitute for a transfer, so nothing is linked. - Best into an empty destination. Existing files in the destination may get their attributes adjusted, which through the hard link also changes the old snapshot. Since rsync 3.1.0 an exact match is found even when a destination file already exists.
Checking the result
The clearest check is the file system itself: a linked file has the same inode number (ls -li) in both snapshots and a link count above 1, and du -sh over both directories counts linked data once. The manual notes that --itemize-changes output "can get a bit muddled" with this option, so do not rely on it alone. If rsync ends with code 23 on some files, see some files/attrs were not transferred; the snapshot for those files may be incomplete.
FAQ
Can I delete an old snapshot made with --link-dest?
Yes. Each snapshot is a full directory tree of hard links. Removing one snapshot only removes its links; the data stays on disk as long as another snapshot still links to the same file.
Why does rsync --link-dest copy everything instead of linking?
Usually the DIR path is wrong (a relative path is resolved from the destination directory, not from where you run rsync), or the files differ in a preserved attribute such as permissions or ownership, or -I is set. Use an absolute path and compare inode numbers with ls -li.
Does --link-dest work to a remote destination?
Yes, DIR is a path on the destination machine. The hard links are created there, so the previous snapshot must be on the same file system as the new one.