py-treesum generate

Synopsis

py-treesum generate [--help | -h] [--accept-treesum | -A FILTER-PATTERN] [--algorithm | -a ALGORITHM] [--append-output] [--base32] [--base64] [--base85] [--bsd] [--comment TEXT] [--exclude | -X FILTER-PATTERN] [--follow-directory-symlinks | -l] [--follow-file-symlinks] [--fsencoding] [--full-mode] [--generator full | normal | none ] [--grouping-separator GROUPING-SEPARATOR] [--half | -H] [--hex] [--ignore-symlink-type] [--include | -I FILTER-PATTERN] [--logical | -L] [--minimal [TAG]] [--mmap] [--mode] [--mtime] [--no-follow-directory-symlinks] [--no-follow-file-symlinks] [--no-ignore-symlink-type] [--no-mmap] [--output | -o FILENAME] [--output-style OUTPUT-STYLE] [-p] [--physical | -P] [--print-size] [--reverse | -r] [--rfc1924] [--size-only] [--size-width SIZE-WIDTH] [--tag] [--utf8] [--with-notes] DIRECTORY …

Description

Generate “fingerprints” or “message digests” of every directory tree DIRECTORY.

Each DIRECTORY on the command line makes a block in the output.

The output is a “treesum” file.

For a description of the file format see here.

Options

--help, -h

Print the subcommand’s help message to stdout and exit.

--accept-treesum=FILTER-PATTERN, -A FILTER-PATTERN

Accept an existing treesum file that matches FILTER-PATTERN for a directory fingerprint. Implicitly this also acts as --exclude option.

All patterns are evaluated in given order, the first match wins.

This option can be given more than once.

For help on FILTER-PATTERN use py-treesum patterns.

--algorithm=ALGORITHM, -a ALGORITHM

1 (aka sha1), 2 (alias for sha256), 224, 256 (aka sha256), 384, 512 (aka sha512), 3 (alias for sha3-512), 3-224, 3-256, 3-384, 3-512, blake2b, blake2b-256, blake2s, blake2 (alias for blake2b), blake2-256 (alias for blake2b-256), md5.

The default depends on the availability in hashlib. Tested are blake2b-256, sha256 or sha1 – in this order.

--append-output

Append to the output file instead of overwriting it.

--base32

Output digest values in base32 notation, not hexadecimal.

--base64

Output digest values in base64 notation, not hexadecimal.

--base85

Output digest values in base85 notation, not hexadecimal. This encoding is compatible to the encodings used in Git or Mercurial.

--bsd

Alias for option --output-style=tagged .

--comment=TEXT

Put given text TEXT into the output as COMMENT record.

Can be given more than once.

This option is only effective if --minimal is not given.

--exclude=FILTER-PATTERN, -X FILTER-PATTERN

Exclude names matching the given FILTER-PATTERN.

For help on FILTER-PATTERN use py-treesum patterns.

Can be given more than once.

Follow symbolic links to directories when walking a directory tree.

This option does not apply to symbolic links given on the command line.

This option typically augments --physical, --half and -p.

Follow symbolic links to files when walking a directory tree.

This is an aspect of the default behaviour.

This option typically augments --physical and --half.

--fsencoding, --fs-encoding

Use native filesystem encoding from the current locale when writing paths and texts into the output.

This option has no effect on digest values.

The default is to use UTF-8.

--full-mode

Consider all mode bits as returned from stat(2) when computing directory message digests.

Note that mode bits on symbolic links itself are ignored. Message digests for non-directories are not affected likewise.

All the bits of os.stat_result.st_mode are taken into account. This option most probably makes affected message digests OS dependent.

--generator=GENERATOR

GENERATOR may have the values normal, full or none.

Control the GENERATOR record in the output.

full prints full Python and OS/platform version information, normal prints just the version of py-treesum and whether Python 2 or Python 3 is used, and none suppresses the output completely.

The default is normal.

--grouping-separator=GROUPING-SEPARATOR

Use the given GROUPING-SEPARATOR as thousands separator when printing sizes.

The default grouping separator depends on the output style given in --output-style: for tagged output it is the single quote ', for tabbed output it is the dot . .

Use an empty GROUPING-SEPARATOR value to disable grouping.

Note that the parser recognizes just a fixed subset of values. Currently these are ., ,, ', _ and the space ␣ .

--half, -H

Follow symbolic links given on the command line but do not follow symlinks of any type while traversing the directory tree.

Overwrites any other symlink related options (--physical, --logical, -p, --follow-directory-symlinks, --follow-file-symlinks, et al.).

--hex

Output digest values in hex notation.

This is the default.

When not folling symlinks to files and directores, also ignore the filetype of the target.

By default the target’s filetype is accounted for also. So, while not following symbolic links when traversing they must be followed temporarily to determine the type of the target. This may introduce spurious inconsistencies if e.g. absolute symlinks do not exist when the digests are created and do exist when they are checked. This flag prohibits this inconsistent behaviour.

The flag is effective only when --no-follow-directory-symlinks and --no-follow-file-symlinks are both in effect, or when not following symbolic links on the command line.

This is the default.

--include=FILTER-PATTERN, -I FILTER-PATTERN

Include names matching the given FILTER-PATTERN.

All patterns are evaluated in given order, the first match wins.

This option can be given more than once.

For help on FILTER-PATTERN use py-treesum patterns.

--logical, -L

Follow symbolic links everywhere: on command line arguments and—while walking—directory and file symbolic links.

Overwrites any other symlink related options (--physical, --half, -p, --no-follow-directory-symlinks, --no-follow-file-symlinks, et al.).

--minimal[=TAG]

Control the content of the ROOT record in the output.

By default the ROOT record contains the value of the command line argument that is handled currently; additionally start and end timestamp records are generated.

With this option the ROOT record will contain given TAG as text and no timestamp records are generated. Also any --comment options are ignored. A missing TAG counts as empty string value.

--mmap

Use mmap if available on the system.

The default depends on the size of the file that is handled.

--mode

Consider the permission bits of stat(2) using S_IMODE (i.e. all bits without the filetype bits) when computing directory digests.

Note that mode bits on symbolic links itself are not considered.

Just some bits of os.stat_result.st_mode are taken into account. This option may make affected message digests OS dependent.

--mtime

Consider the mtime of files (non-directories) when generating digests for directories. Directory entries are not considered.

Digests of files are not affected.

Don’t follow symbolic links to directories when walking a directory tree.

This is an aspect of the default behaviour.

This option does not apply to symbolic links given on the command line.

Also typically augments --logical.

Don’t follow symbolic links to files when walking a directory tree.

Disable the default behaviour of --ignore-symlink-type for phycical traversal modes.

--no-mmap

Don’t use mmap.

--output=FILENAME, -o FILENAME

Put the output into given file FILENAME.

If not given or if FILENAME is - then stdout is used.

--output-style=OUTPUT-STYLE

Select the output style or flavour:

tagged or tag select a BSD style tagged format; tabular or tab select a more GNU style (or Linux coreutils) tabular format.

Default is tagged.

-p

Do not follow any symbolic links to directories, whether they are given on the command line or when walking the directory tree, but follow symbolic links to files.

Overwrites any other symlink related options (--logical, --half, --physical, --follow-directory-symlinks, --no-follow-file-symlinks, et al.).

This is the default.

--physical, -P

Do not follow any symbolic links whether they are given on the command line or when walking the directory tree.

Overwrites any other symlink related options (--logical, --half, -p, --follow-directory-symlinks, --follow-file-symlinks, et al.).

--print-size

Print the size of a file or the accumulated sizes of directory content into the output also. The size is not considered when computing message digests.

For symbolic links the size is not printed also.

--reverse, -r

Alias for option --output-style=tabular .

--rfc1924

Output digest values in pure RFC 1924 notation.

While invented for compact representations of IPv6 addresses this encoding generates the shortest encodings of digests.

--size-only

Print only the size of files and for each directory its accumulated directory size.

--size-width=SIZE-WIDTH

Some output styles print the a filesize right-aligned in a column (e.g. tabular). SIZE-WIDTH is the (minimum) width to be used. The width includes grouping separators.

Use 0 if no alignment should be done.

Ignored for tagged output.

Default is 15.

--tag

Alias for option --output-style=tagged or --bsd .

--utf8, --utf-8

Use the UTF-8 encoding when writing paths and texts into the output.

Make the directory TAINTED if a path cannot representated in Unicode cleanly.

This is the default.

This option has no effect on digest values.

--with-notes

Also put some NOTE records with some extra data into the output.

Currently this is the information about excluded files.

--without-warnings

Deactivate the output of WARNING records. By default warnings will be generated.

Note

For symlink related options:

See Also

py-treesum, file format filter patterns