5 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
7 .TH fshash 1 "8 October 2012" rsync-backup
22 program generates digests of filesystems. It's similar in concept (but
23 somewhat different from) Ian Jackson's
27 The idea is to capture everything interesting about a filesystem in a
28 file with the following properties:
31 The digest file describes everything `interesting' about the filesystem,
32 such that two filesystems which are interestingly different will have
36 If two filesystems aren't different in any interesting way, then their
37 digests should be identical.
40 Given two subtly different filesystems, it's easy for a human equipped
41 with digests for them and
43 to work out what the differences actually are.
44 .SS Command-line processing
45 The following command-line arguments are accepted.
48 Show a summary of the command-line syntax, and exit successfully.
51 Show the program's version number, and exit successfully.
54 Clear the cache of information about all files except those processed in
57 .B \-c, \-\-cache=\fIfile
58 Keep a cache of file hashes in the
60 The cache is keyed by inode and modification time: if a file has an
61 entry in the cache already then it won't be hashed again, which can
62 provide a valuable performance improvement on large filesystems. If the
64 doesn't exist, then it will be created.
66 .B \-f, \-\-files=\fIformat
67 Read a list of filenames on standard input in the given
69 and write digest lines for them. The
73 for simple null-terminated names, as produced by
74 .BR "find \-\-print0" ;
77 for file data as produced by
79 The latter is useful, since
81 has powerful file inclusion and exclusion capabilities \(en and a common
82 use case is generating a digest for a collection of files copied using
86 format doesn't work well: see
90 .B \-H, \-\-hash=\fIhash
93 function, which can be any hash function supported by Python's
95 If this option may be omitted then the hash is read from the cache file;
96 if there is no cache file either, then an error is reported.
98 Positional arguments are interpreted as files and directories to be
99 processed, in order. A directory name which ends in
101 is treated specially:
103 writes filenames relative to the given directory.
105 Information about each filesystem object is written on a separate line.
106 These lines can be quite long, and consist of a number of fields:
108 For regular files, a cryptographic hash of the file's content, in
109 hexadecimal. For other kinds of filesystem object, a description of the
110 object type and any special information about it, in square brackets,
111 and padded with spaces so as to take the same width as a hash; see
115 A `virtual inode identifier': a string which will be the same in two
116 lines if and only if they represent hard links to the same underlying
117 inode. Some care is taken so that files are assigned the same
118 identifier even if other parts of the filesystem are different, so as to
119 avoid spurious differences.
121 The object's permissions and mode bits, in octal.
123 The file's owner and group, in decimal, separated by a colon.
125 The file's last-modified time, in UTC, in ISO8601 format, i.e.,
126 .IB yyyy \(en mm \(en dd T hh : mm : ss Z \fR.
128 The file's size in bytes, in decimal.
130 The file's name (relative to some appropriate parent directory).
132 would cause ambiguity are escaped: tab, linefeed and carriage return are
145 and other codes outside the range 32\(en127 are printed as hex escaped,
148 Finally, the sequence
152 so that symlink targets are presented unambiguously (see below).
154 For non-regular file objects, the first field is an information field
155 enclosed in square brackets, and some of the other fields provide other
156 information or are suppressed, follows.
159 If there was an error reading the object's metadata then the information
163 and the other fields, except the name, are printed as
165 rather than having any useful information.
168 The information field shows
172 The information field shows
176 The information field shows
178 The name is followed by
180 and the link target (or by
181 .BI <E nn \~ message >
182 if there was an error reading the link destination).
185 The information field shows
187 and the size field shows
189 (since directory sizes are not consistent across filesystem
190 implementations). The name is followed by
193 .I Block and character devices
194 The information field shows
197 .BR character-device ,
198 as appropriate, followed by the major and minor device numbers in
199 decimal, and separated by a colon.
202 No attempt is made to sort filenames read in
204 format, so they're not very likely to match digests produced any other
205 way. Indeed, they're not very likely to match digests produced by
207 on other machines either.
214 Mark Wooding, <mdw@distorted.org.uk>