General Topics

IntegrityCheckerJava

DiskTester

MemoryTester

IntegrityChecker

dgl

Tips and How-To

Troubleshooting

IntegrityChecker java (icj): Preferences/Configuration

This refererence page discusses the preference file and all its settings. It is divided into sections (namespaces):

Use the prefs command to show preferences.

#include

Additional preference files can be included in the main preference file in any location via the #include directive. Paths for include directives are relative to the prefs file which includes it, e.g. home directory for .icj_prefs. Including configuration is a clean way to add/modify preferences without modifying the default .icj_prefs file, e.g. for the purposes of experimenting with different settings or globbing patterns.

The contents of the included file replace the #include line. This facility is not recursive (valid only in the main .icj_prefs file). After all the include directives are processed, the result is parsed as if it has all been in a single file to begin with.

# incorporates the file ".icj_prefs_myStuff"
#include ".icj_prefs_myStuff"

# incorporates the file ".icj_prefs_override"
#include "../icj_prefs_override"

Preferences — [preferences]

The [preferences] section contains name/value pairs that control the behavior of IntegrityChecker Java (icj).

In the following, the "|" character means "or" — e.g., choose one item from the given options.

Underlined values are the default setting.

ICJ_FILES_MODE = icjh | both

Controls the type of hash files are used.

HIERARCHY_FILES_MODE = auto | explicit

Controls whether hierarchy files are created automatically or only explicitly.

HIERARCHY_FILES_MIN = <number>

Number of files in a folder (total, recursively) beyond which icj automatically writes a hierarchy file into the folder (when ICJ_FILES_MODE = AUTO).

HIERARCHY_GB_MIN = <number>

Number of gigabytes in a folder (total, recursively) beyond which icj automatically writes a hierarchy file into the folder (when ICJ_FILES_MODE = AUTO).

VERBOSITY = normal | verbose | debug

Controls the wordiness of the output.

AUTO_OPEN_PREFS = true | false

Controls whether icj attempts to open the main preference file with a text editor.

AUTO_OPEN_HELP = true | false

Controls whether icj attempts to open the appropriate web page for help when help is invoked, e.g. 'icj help' and certain other situations.

warn.ILLEGAL_FILENAME = true | false

Illegal filenames vary by operating system platform. The only ones icj considers “illegal” are those containing a forward slash "/" or a backslash "\", because they cause inherent problems. For example, Java sees a "/" in a filename as a ":".

warn.FILENAME_COMPATIBILITY = true | false

Most unix systems allow most all characters. Windows is more restrictive. If cross-platform file-interchange is anticipated, enable this warning to flag files with problematic characters. For example, Windows has issues with all of these characters: / \ : * ? < > | \ ". Unix systems allow most anything; macOS even allows a "/" which Java passes in a a ":". But macOS disallows a ":", turning it into a 16-bit character. It all makes for a mess if interchanging files.

warn.DEAD_SYMLINKS = true | false

Warn if symbolic links (symlinks) are “dead” eg they point to a non-existent file. While icj generally ignores symlinks, this could be useful for finding useless files you might think you have.

warn.FILE_CHANGED_IN_FLIGHT = true | false

Hashing while a file is actively being written can issue this warning.

warn.MISSING_SUBFOLDERS = true | false

Whether subfolders that have disappeared are flagged. Subfolders often disappear when moved.

warn.DAYLIGHT_SAVINGS_TIME_BUG = true | false

Certain file dates that occur in the one-hour window at a daylight savings time boundary can result in a comparison of dates failing. Controls whether this is flagged or not.

warn.CREATION_DATE_CHANGED = true | false

Warns when a creation date has changed, but the modification date has not changed.

warn.CONFLICTING_CREATION_MODIFICATION_DATES = true | false

Warns when a file was modified before it was created.

Globbing sections

The following sections use globbing for file and folder matching. Use (or not) of auto-globbing is indicated and the default matching patterns are shown.

See Excluding Folders and Files or further details and Excluding Folders and Files — Examples for additional examples of globbing patterns.

Preferences — [folders.ignore]

Auto-globbing: yes (because it greatly simplifies configuration and minimizes need technical understanding)

The folders.ignore section contains all folder paths to be ignored for all hashing purposes. These are in addition to certain built-in folder paths.

[folders.ignore]

# excludes all folders with 'cache' in the name in user Library; comment out to use the more conservative pattern below
**/Users/*/Library/[Cc]ache{e,es}**

# more conservative excludes only ~/Library/Caches; uncomment to use instead of above
#Users/*/Library/Caches

# problematic areas (frequent changes)
**/Library/Developer/CoreSimulator**
**/com.apple.internetaccounts**
**/Data/DataVaults**
**/Application Support/CrashReporter**

Preferences — [filenames.ignore]

Auto-globbing: no (only the filename is being matched, no path involved)

Files whose name matches an expression from this section will be ignored for all hashing purposes. Matching is applied only to the filename portion (no path/folder portion).

[filenames.ignore]

# 'nasty' macOS files; can change without modification dates changing. Comment-in if an issue.
#*-shm
#*-wal

Preferences — [filepaths.ignore]

Auto-globbing: no (intended usage for files makes suffixing with ** inappropriate)

These patterns match against the entire file path, as compared to just the filename, with the same rules as folders.ignore. No auto-globbing is used for filepaths.ignore

[filepaths.ignore]
# macOS: nuisance files that change a lot
**/Users/*Library/**/*-shm
**/Users/*Library/**/*-wal
**/Users/*Library/**/*.log

Patterns can be used which match all files in folder(s), which can leave “hollowed-out” folders. If the goal is to exclude a folder, use folders.ignore.

Preferences — [dupes.ignore]

Auto-globbing: yes (as with [folders.ignore], ease of configuration is desired)

Folders that match an expression from this section will be ignored for the purposes of the dupes command.

Preferences — [hierarchy.auto-write]

Auto-globbing: no (because typically the desire is only for a top-level folder matching a pattern, not all its subfolders)

A hierarchy file will be written in any folder that matches an expression from this section, even if the folder(s) would otherwise not qualify based on HIERARCHY_FILES_MIN and HIERARCHY_GB_MIN.

Note that, unlike with other folder-related sections, expressions in hierarchy.auto-write are NOT expanded automatically (other than prefixing "glob:"), so as to ensure hierarchy files will only be written where actually intended.

Preferences — [hierarchy.no-auto-write]

Auto-globbing: yes (because a folder and all its subfolders usually should be treated the same by default)

Hierarchy files will not be written automatically in folders matching an expression in this section.

Explicit update of a folder at the command line will still always write a hierarchy file, even if [hierarchy.no-auto-write] would otherwise exclude it.

Preferences — [output.suppressInnocuousChanges]

Auto-globbing: no (conservative approach to not suppressing too much, applies to both files and folders)

Reduces output “noise”: patterns in this section specify folders or files to match such that when innocuous routine changes occur , they will not be listed when running it. Specifically, the following changes will not be flagged when there is a match:

The order of evaluation is as follows:

  1. A match is attempted for the filename (just the name).
  2. A match is atempted for the folder containing the file (without the name, without the trailing path separator).

If either match succeeds, then the output is suppressed.

Previous page: icj pref
Next page: Excluding Folders and Files — Reference