1HARDLINK(1) User Commands HARDLINK(1)
2
6 hardlink - link multiple copies of a file
7
9 hardlink [options] [directory|file]...
10
12 hardlink is a tool that replaces copies of a file with either hardlinks
13 or copy-on-write clones, thus saving space.
14 hardlink first creates a binary tree of file sizes and then compares
16 the content of files that have the same size. There are two basic
17 content comparison methods. The memcmp method directly reads data
18 blocks from files and compares them. The other method is based on
19 checksums (like SHA256); in this case for each data block a checksum is
20 calculated by the Linux kernel crypto API, and this checksum is stored
21 in userspace and used for file comparisons.
22 For each file also an "intro" buffer (32 bytes) is cached. This buffer
24 is used independently from the comparison method and requested
25 cache-size and io-size. The "intro" buffer dramatically reduces
26 operations with data content as files are very often different from the
27 beginning.
28
30 -h, --help
31 Display help text and exit.
32 -V, --version
34 Print version and exit. If specified once, every hardlinked file is
35 displayed, if specified twice, it also shows every comparison.
36 -q, --quiet
38 Quiet mode, don’t print anything.
39 -n, --dry-run
41 Do not act, just print what would happen.
42 -y, --method name
44 Set the file content comparison method. The currently supported
45 methods are sha256, sha1, crc32c and memcmp. The default is sha256,
46 or memcmp if Linux Crypto API is not available. The methods based
47 on checksums are implemented in zero-copy way, in this case file
48 contents are not copied to the userspace and all calculation is
49 done in kernel.
50 --reflink[=when]
52 Create copy-on-write clones (aka reflinks) rather than hardlinks.
53 The reflinked files share only on-disk data, but the file mode and
54 owner can be different. It’s recommended to use it with
55 --ignore-owner and --ignore-mode options. This option implies
56 --skip-reflinks to ignore already cloned files.
57 The optional argument when can be never, always, or auto. If the
59 when argument is omitted, it defaults to auto, in this case,
60 hardlink checks filesystem type and uses reflinks on BTRFS and XFS
61 only, and fallback to hardlinks when creating reflink is
62 impossible. The argument always disables filesystem type detection
63 and fallback to hardlinks, in this case, only reflinks are allowed.
64 --skip-reflinks
66 Ignore already cloned files. This option may be used without
67 --reflink when creating classic hardlinks.
68 -f, --respect-name
70 Only try to link files with the same (base)name. It’s strongly
71 recommended to use long options rather than -f which is interpreted
72 in a different way by other hardlink implementations.
73 -p, --ignore-mode
75 Link and compare files even if their mode is different. Results may
76 be slightly unpredictable.
77 -o, --ignore-owner
79 Link and compare files even if their owner information (user and
80 group) differs. Results may be unpredictable.
81 -t, --ignore-time
83 Link and compare files even if their time of modification is
84 different. This is usually a good choice.
85 -X, --respect-xattrs
87 Only try to link files with the same extended attributes.
88 -m, --maximize
90 Among equal files, keep the file with the highest link count.
91 -M, --minimize
93 Among equal files, keep the file with the lowest link count.
94 -O, --keep-oldest
96 Among equal files, keep the oldest file (least recent modification
97 time). By default, the newest file is kept. If --maximize or
98 --minimize is specified, the link count has a higher precedence
99 than the time of modification.
100 -x, --exclude regex
102 A regular expression which excludes files from being compared and
103 linked.
104 -i, --include regex
106 A regular expression to include files. If the option --exclude has
107 been given, this option re-includes files which would otherwise be
108 excluded. If the option is used without --exclude, only files
109 matched by the pattern are included.
110 -s, --minimum-size size
112 The minimum size to consider. By default this is 1, so empty files
113 will not be linked. The size argument may be followed by the
114 multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on
115 for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g.,
116 "K" has the same meaning as "KiB").
117 -S, --maximum-size size
119 The maximum size to consider. By default this is 0 and 0 has the
120 special meaning of unlimited. The size argument may be followed by
121 the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so
122 on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g.,
123 "K" has the same meaning as "KiB").
124 -b, --io-size size
126 The size of the read(2) or sendfile(2) buffer used when comparing
127 file contents. The size argument may be followed by the
128 multiplicative suffixes KiB, MiB, etc. The "iB" is optional, e.g.,
129 "K" has the same meaning as "KiB". The default is 8KiB for memcmp
130 method and 1MiB for the other methods. The only memcmp method uses
131 process memory for the buffer, other methods use zero-copy way and
132 I/O operation is done in the kernel. The size may be altered on the
133 fly to fit a number of cached content checksums.
134 -r, --cache-size size
136 The size of the cache for content checksums. All non-memcmp methods
137 calculate checksum for each file content block (see --io-size),
138 these checksums are cached for the next comparison. The size is
139 important for large files or a large sets of files of the same
140 size. The default is 10MiB.
141
143 hardlink takes one or more directories which will be searched for files
144 to be linked.
145
147 The original hardlink implementation uses the option -f to force
148 hardlinks creation between filesystem. This very rarely usable feature
149 is no more supported by the current hardlink.
150 hardlink assumes that the trees it operates on do not change during
152 operation. If a tree does change, the result is undefined and
153 potentially dangerous. For example, if a regular file is replaced by a
154 device, hardlink may start reading from the device. If a component of a
155 path is replaced by a symbolic link or file permissions change,
156 security may be compromised. Do not run hardlink on a changing tree or
157 on a tree controlled by another user.
158
160 There are multiple hardlink implementations. The very first
161 implementation is from Jakub Jelinek for Fedora distribution, this
162 implementation has been used in util-linux between versions v2.34 to
163 v2.36. The current implementations is based on Debian version from
164 Julian Andres Klode.
165
167 For bug reports, use the issue tracker at
168 https://github.com/util-linux/util-linux/issues.
169
171 The hardlink command is part of the util-linux package which can be
172 downloaded from Linux Kernel Archive
173 <https://www.kernel.org/pub/linux/utils/util-linux/>.
174util-linux 2.38 2022-03-25 HARDLINK(1)