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.

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(because user should be explicit as to intent)

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.

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 (because 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]

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

Preferences — [filepaths.ignore]

Auto-globbing: no (because 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 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 this section 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

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