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 2.
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 Information about each filesystem object is written on a separate line.
138 These lines can be quite long, and consist of a number of fields:
140 For regular files, a cryptographic hash of the file's content, in
141 hexadecimal. For other kinds of filesystem object, a description of the
142 object type and any special information about it, in square brackets,
143 and padded with spaces so as to take the same width as a hash; see
146 A `virtual inode identifier': a string which will be the same in two
147 lines if and only if they represent hard links to the same underlying
148 inode. Some care is taken so that files are assigned the same
149 identifier even if other parts of the filesystem are different, so as to
150 avoid spurious differences.
152 The object's permissions and mode bits, in octal.
154 The file's owner and group, in decimal, separated by a colon.
156 The file's last-modified time, in UTC, in ISO8601 format, i.e.,
157 .IB yyyy \(en mm \(en dd T hh : mm : ss Z \fR.
159 The file's size in bytes, in decimal.
161 The file's name (relative to some appropriate parent directory).
163 would cause ambiguity are escaped: tab, linefeed and carriage return are
176 and other codes outside the range 32\(en127 are printed as hex escaped,
179 Finally, the sequence
183 so that symlink targets are presented unambiguously (see below).
185 For non-regular file objects, the first field is an information field
186 enclosed in square brackets, and some of the other fields provide other
187 information or are suppressed, follows.
190 If there was an error reading the object's metadata then the information
194 and the other fields, except the name, are printed as
196 rather than having any useful information.
199 The information field shows
203 The information field shows
207 The information field shows
209 The name is followed by
211 and the link target (or
212 .BI <E nn \~ message >
213 if there was an error reading the link destination).
216 The information field shows
218 and the size field shows
220 (since directory sizes are not consistent across filesystem
221 implementations). The name is followed by
224 .I Block and character devices
225 The information field shows
228 .BR character-device ,
229 as appropriate, followed by the major and minor device numbers in
230 decimal, and separated by a colon.
233 No attempt is made to sort filenames read in
235 format, so they're not very likely to match digests produced any other
236 way. Indeed, they're not very likely to match digests produced by
238 on other machines either.
245 Mark Wooding, <mdw@distorted.org.uk>
~mdw / rsync-backup / blob