5 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
7 .TH fshash 1 "8 October 2012" rsync-backup
32 program generates digests of filesystems. It's similar in concept to
33 (but somewhat different from) Ian Jackson's
37 The idea is to capture everything interesting about a filesystem in a
38 file with the following properties:
41 The digest file describes everything `interesting' about the filesystem,
42 such that two filesystems which are interestingly different will have
46 If two filesystems aren't different in any interesting way, then their
47 digests should be identical.
50 Given two subtly different filesystems, it's easy for a human equipped
51 with digests for them and
53 to work out what the differences actually are.
54 .SS Command-line processing
55 The following command-line arguments are accepted.
58 Show a summary of the command-line syntax, and exit successfully.
61 Show the program's version number, and exit successfully.
64 Clear the cache of information about all files except those processed in
67 .B \-c, \-\-cache=\fIfile
68 Keep a cache of file hashes in the
70 The cache is keyed by inode and modification time: if a file has an
71 entry in the cache already then it won't be hashed again, which can
72 provide a valuable performance improvement on large filesystems. If the
74 doesn't exist, then it will be created.
76 .B \-f, \-\-files=\fIformat
77 Read a list of filenames on standard input in the given
79 and write digest lines for them. The
83 for simple null-terminated names, as produced by
84 .BR "find \-\-print0" ;
87 for file data as produced by
89 The latter is useful, since
91 has powerful file inclusion and exclusion capabilities \(en and a common
92 use case is generating a digest for a collection of files copied using
96 format doesn't work well: see
100 .B \-C, \-\-compat=\fIversion
101 Produce a manifest with the given compatibility
105 has bugs in the way it produces manifests. Fixing the bugs makes the
106 output better, but now it can't be compared with old manifests which
107 were made with the bugs. By default,
109 produces manifests in the most recent format, but this option will force
110 it to be compatible with old versions. The original version was 1; all
111 later versions print a comment reporting the version number at the start
112 of the manifest. The current version is 3.
114 .B \-H, \-\-hash=\fIhash
117 function, which can be any hash function supported by Python's
119 This option may be omitted: if it is, then the hash is read from the
120 cache file; if there is no cache file either, then an error is reported.
123 Rather than produce a manifest, read a unified
125 from standard input, and clear from the cache all files mentioned as
126 being different. Filenames in the diff are considered relative to
128 defaulting to the current working directory.
130 Positional arguments are interpreted as files and directories to be
131 processed, in order. A directory name which ends in
133 is treated specially:
135 writes filenames relative to the given directory.
137 For each filesystem object,
139 writes a summary line, followed by zero or more additional lines.
140 A summary line can be quite long, and consists of a number of
143 For regular files, a cryptographic hash of the file's content, in
144 hexadecimal. For other kinds of filesystem object, a description of the
145 object type and any special information about it, in square brackets,
146 and padded with spaces so as to take the same width as a hash; see
149 A `virtual inode identifier': a string which will be the same in two
150 lines if and only if they represent hard links to the same underlying
151 inode. Some care is taken so that files are assigned the same
152 identifier even if other parts of the filesystem are different, so as to
153 avoid spurious differences.
155 The object's permissions and mode bits, in octal.
157 The file's owner and group, in decimal, separated by a colon.
159 The file's last-modified time, in UTC, in ISO8601 format, i.e.,
160 .IB yyyy \(en mm \(en dd T hh : mm : ss Z \fR.
162 The file's size in bytes, in decimal.
164 The file's name (relative to some appropriate parent directory).
166 would cause ambiguity are escaped: tab, linefeed and carriage return are
179 and other codes outside the range 32\(en127 are printed as hex escaped,
182 Finally, the sequence
186 so that symlink targets are presented unambiguously (see below).
188 For non-regular file objects, the first field is an information field
189 enclosed in square brackets, and some of the other fields provide other
190 information or are suppressed, follows.
193 If there was an error reading the object's metadata then the information
197 and the other fields, except the name, are printed as
199 rather than having any useful information.
202 The information field shows
206 The information field shows
210 The information field shows
212 The name is followed by
214 and the link target (or
215 .BI <E nn \~ message >
216 if there was an error reading the link destination).
219 The information field shows
221 and the size field shows
223 (since directory sizes are not consistent across filesystem
224 implementations). The name is followed by
227 .I Block and character devices
228 The information field shows
231 .BR character-device ,
232 as appropriate, followed by the major and minor device numbers in
233 decimal, and separated by a colon.
235 Additional lines begin with a tab character. The possible lines are as
240 If an object has nontrivial POSIX ACLs, then they are printed as additional
243 .BI "acl posix-access " acl
247 .BI "acl posix-default " acl
249 for access and default ACLs respectively. The
251 is the ACL in short text format, with numeric IDs, and with the entries
252 sorted into a canonical order (owner, other users, mask, file group, other
254 .BI <E nn \~ message >
255 if there was an error retrieving the ACL.
257 An access ACL is nontrivial if it contains entries for
258 other users, other groups, or a mask, i.e., it is not completely described by
259 the file's traditional permissions. A default ACL is nontrivial if it is not
262 POSIX ACLs are recognized at compatibility level 3 and above. ACL
268 .I Extended attributes
270 If a file has extended attributes then they are printed as additional lines
273 .BI "xattr " name " " hash
277 is the attribute name, escaped in the same manner as filenames, and
279 is the hash of the attribute's contents. Extended attribute hashes are not
280 currently cached, because they're usually too small for it to be worthwhile.
281 If errors occur, then
282 .BI <E nn \~ message >
283 is printed in place of the
285 if the error occurred when trying to retrieve the attribute value,
290 if the error occurred when trying to list the attributes.
294 program does not print lines for extended attributes which are used to
295 implement features which
297 handles explicitly: for example, on Linux, POSIX ACLs are stored in extended
299 .B system.posix_acl_access
301 .BR system.posix_acl_default ,
302 so these attributes are ignored if ACL support is available.
304 Extended attributes are recognized at compatibility level 3 and above.
305 Extended attribute support requires the
309 library, or Python 3.3.
312 No attempt is made to sort filenames read in
314 format, so they're not very likely to match digests produced any other
315 way. Indeed, they're not very likely to match digests produced by
317 on other machines either.
324 Mark Wooding, <mdw@distorted.org.uk>
~mdw / rsync-backup / blob