# precizer configuration file
#
# Saved settings for a scan or comparison. Running precizer without arguments
# reads precizer.conf from the current folder. A different file can be selected
# with precizer --config=/path/to/task.conf
#
# Settings come from either this file or the command line. A command with its
# own scan or comparison options ignores this file. When --config selects a
# file, the settings for that run must all be written in that file
#
# All example settings below are commented out. Removing the # directly before
# a setting makes that line take effect. The examples show default values where
# possible; paths and filtering rules are examples to adapt to the actual files
#
# Setting names and CLI option names are case-sensitive. Named values are
# case-insensitive. Paths, file names, and regular expressions retain their case
#
# For true/false settings, true enables the feature and false disables it.
# The alternatives yes/no, on/off, y/n, and 1/0 also work in any letter case
#
# Paths are relative to the folder where precizer is launched, even when the
# configuration file is stored elsewhere. A full path such as /mnt/storage
# avoids depending on the launch folder
#
# Quotation marks are optional, including for names with spaces. For example,
# ignore = "^cache/" and ignore = ^cache/ mean the same thing. Spaces and
# backslashes inside matching quotes are kept. Variables such as $HOME are
# treated as ordinary text
#
# Comments begin with # at the start of a line or after a space:
# value # note has a comment; value#name keeps the # as part of the value.
# The same rule applies inside quotation marks

# path: folders to scan
# Values: one folder path per entry. Default: no folders selected
# Scans this folder and its subfolders. It saves a checksum for each file,
# which helps detect changes to its contents. At least one folder is needed
# for a scan. Several folders can be listed by repeating path
# Example: scan /mnt/storage and its subfolders
#path = /mnt/storage

# Example: scan two folders
#path = /mnt/storage
#path = /mnt/backup

# The same list with the second folder on an indented line.
# Removing # from both lines keeps the spaces before the second path
#path = /mnt/storage
#     /mnt/backup

# database: where to save the scan results
# Values: a database file path. Default: the computer name followed by .db
# Keeps file names, sizes, timestamps, and checksums for later checks or
# comparisons. The database stores information about files, not their contents
#
# Without this setting, results are saved in the current folder under the
# computer's name: for example, host1.db on host1. A separate database name
# for each collection keeps its scan results together
# Example: save the results in a chosen database
#database = /mnt/databases/storage.db

# check-level: check the database for damage before using it
# Values: FULL or QUICK (case-insensitive). Default: FULL
# FULL performs a thorough check of the saved database. QUICK checks its
# basic structure and can reduce the wait before a large database is used
#check-level = FULL

# update: save changes since the previous scan
# Values: true or false. Default: false
# Enables updates to an existing database: new files are added, changed files
# are checked again, and records for deleted files are removed. This is useful
# after expected changes that should become the new saved scan results
#
# The first scan can create a database with update = false. Later changes to
# that database require update = true. The files being scanned stay untouched.
# Updating normally uses the same starting folders as the original scan;
# changing those folders also requires force = true
#update = false

# force: allow an update after moving the scanned folders
# Values: true or false. Default: false
# Allows the starting paths saved in the database to be replaced. This is
# useful when the same collection has moved to another folder or drive.
# The path settings must point to the new location, with update = true
#
# Choosing unrelated folders can replace or remove the previous file records
# and checksums. After the move, force = false restores the check that the
# selected folders match those saved in the database
#force = false

# progress: show how much of the scan is complete
# Values: true or false. Default: false
# Displays the number of files and amount of data processed. Before scanning,
# precizer counts the files and their total size so it can estimate progress.
# This extra walk through the folders can take time on large collections
#
# Useful when watching a scan in a terminal. Automatic runs can leave this
# off to avoid the counting pass. With progress enabled, warnings and errors
# are shown again at the end so they remain visible after the progress display
#progress = false

# maxdepth: limit how far the scan goes into subfolders
# Values: a whole number from 0 to 32767. Default: no limit (setting omitted)
# A value of 0 scans only files directly in the starting folder. A value of 1
# also scans its immediate subfolders; larger values reach deeper levels.
# Leaving this setting commented out scans all levels
# Example: scan down to level 3
#maxdepth = 3

# ignore: skip files that do not need to be recorded
# Values: a PCRE2 regular expression per entry. Default: no ignore rules
# Useful for caches, temporary files, and logs. Rules match the part of a path
# below the starting folder. With path = /mnt/storage, ^cache/ selects files
# under /mnt/storage/cache. The ^ means the path must start with cache/
#
# Rules use regular expressions (PCRE2). In the example below, the backslash
# makes the dot a literal dot, and $ marks the end of the name
# Example: skip files whose names end in .log
#ignore = \.log$

# Example: skip files matching any of these five rules
#ignore = ^cache/
#ignore = ^tmp/
#ignore = ^something_eles/
#ignore = ^other/
#ignore = ^things/

# The same five rules using indented lines. Removing # from the example
# lines keeps the spaces that make each line continue the preceding rule list
#ignore = ^cache/
#    ^tmp/
#    ^something_eles/

#ignore = ^other/
#    ^things/

# Skipped files stay on disk, and their existing database records are kept.
# Removing those records during an update requires db-drop-ignored = true.
# During comparison, ignore hides matching paths from the report. Any message
# that the databases are equal then applies only to the remaining paths

# include: make exceptions to ignore rules
# Values: a PCRE2 regular expression per entry. Default: no include rules
# Brings selected files back into the scan or comparison after ignore has
# excluded them. For example, a cache folder may contain files worth keeping
# Example: skip cache files except those under cache/keep
#ignore = ^cache/
#include = ^cache/keep/

# Rules use the same relative paths and regular expressions as ignore.
# Files outside the ignore rules are still included; an include rule does
# not limit the whole scan to just its matches
# Example: keep files from two otherwise ignored folders
#include = ^cache/keep/
#include = ^tmp/keep/

# The same exceptions with an indented continuation line
#include = ^cache/keep/
#    ^tmp/keep/

# watch-timestamps: recheck files after changes to their attributes
# Values: true or false. Default: false
# During an update, a changed size or last modification time normally causes
# a file's checksum to be calculated again. This setting also reacts to
# changes in permissions, ownership, or the amount of disk space used
#
# Useful when those changes should prompt another check of file contents.
# Even a permissions change can cause a large file to be read again, so
# updates may take longer. Updating an existing database requires update = true
#watch-timestamps = false

# db-drop-ignored: forget previously recorded files that are now ignored
# Values: true or false. Default: false
# Adding an ignore rule normally keeps the files' existing database records.
# With update = true, this setting removes those records and their checksums.
# Useful when caches or other unwanted files should no longer appear in the
# saved scan. The files themselves stay on disk
#
# Files brought back by include follow the normal update rules. Records
# protected by lock-checksum are kept
#db-drop-ignored = false

# quiet-ignored: hide messages about skipped files
# Values: true or false. Default: false
# Hides the message for each file excluded by the ignore and include rules.
# Useful once the rules work as intended and long lists of skipped files
# make the output harder to read. Other warnings and errors remain visible
#quiet-ignored = false

# db-drop-inaccessible: forget files that can no longer be read
# Values: true or false. Default: false
# A permissions problem can temporarily make a file unreadable. Normally,
# its saved information is kept so a temporary problem does not erase it.
# With update = true, this setting removes the record and saved checksum
#
# Useful when information about inaccessible files is no longer needed.
# The files themselves stay on disk. Records protected by lock-checksum
# are kept even when a file cannot be read
#db-drop-inaccessible = false

# lock-checksum: keep an original checksum for files that should not change
# Values: a PCRE2 regular expression per entry. Default: no protected paths
# Useful for finished archives and snapshots. The first scan records their
# checksums normally. Later updates keep those original checksums so an
# unwanted change does not silently become the new reference
#
# A changed size, missing file, or loss of read access produces a warning
# while the saved record is kept. watch-timestamps also checks changes to
# file timestamps and disk space used. Checking the actual contents again
# requires rehash-locked = true
#
# Rules use paths relative to the starting folder, just like ignore.
# With path = /mnt/storage, ^archive/2024/.* protects files inside
# /mnt/storage/archive/2024. The same rules must be present on later updates
#
# Protected records are kept even when ignore or database cleanup rules
# match them. This preserves the saved checksums; other programs can still
# change the files on disk
# Example: protect two archive folders
#lock-checksum = ^archive/2024/.*
#lock-checksum = ^snapshots/monthly/.*

# rehash-locked: check archive contents against their original checksums
# Values: true or false. Default: false
# Useful for periodic checks of files protected by lock-checksum. Their
# contents are checked again even when the size and timestamps look unchanged.
# This can detect damage that a quick check of file attributes would miss
#
# Requires update = true and at least one lock-checksum rule. A mismatch
# produces a warning and preserves the original checksum. If the content and
# size still match, changed timestamps are saved without replacing that checksum
#
# These checks also cover protected files matched by ignore and do not depend
# on watch-timestamps. Reading large archives again can take considerable time
#rehash-locked = false

# dry-run: preview a scan without changing the database
# Values: true, false, or with-checksums. Default: false
# dry-run = true shows what would be added, updated, or removed. Useful for
# checking folder paths and ignore rules before saving a scan. No checksums
# are calculated, no database is created, and existing results stay unchanged
#
# The with-checksums mode also reads files and calculates their checksums
# without saving the results. Useful for measuring the time needed to read
# and check files. Previewing an update still requires update = true
#dry-run = false

# one-file-system: keep the scan from entering other mounted filesystems
# Values: true or false. Default: false
# A folder may lead to another disk or a network share mounted inside it.
# With true, those filesystems are skipped so they can be scanned separately.
# With false, the scan continues into them
#one-file-system = false

# silent: hide routine messages
# Values: true or false. Default: false
# Useful for automatic runs where a report of each step is unnecessary.
# Comparison results remain visible
#silent = false

# verbose: show details that help explain the result
# Values: true or false. Default: false
# Shows the selected settings and details about the checks being performed.
# Useful for understanding an unexpected result or investigating a problem
#verbose = false

# output: choose how scan and comparison results are presented
# Values: full, compact, or machine. Default: full
# Full includes headings and routine diagnostics. Compact and machine show
# concise event records without progress, statistics, or repeated warnings.
# Compact uses automatic color; machine defaults to no color. An explicit
# color setting takes priority in every output format
#output = full

# color: choose when to use colors and bold text
# Values: auto, always, or never. Default: auto
# With auto, terminal output uses colors and bold text, while saved output
# stays plain. The always setting keeps styling even when saving to a file
# or sending output to another program. The never setting uses plain text
# everywhere
#
# In auto mode, NO_COLOR or TERM=dumb also disables styling. An explicit
# always or never setting takes precedence over those environment variables
#color = auto

# compare: compare two saved scans
# Values: two database paths, one per line. Default: no comparison
# Shows which files are missing from either scan and which have different
# checksums. Only the databases are needed; the original files can be offline
#
# Example: compare scans saved on two computers
#compare = /mnt/databases/host1.db
#compare = /mnt/databases/host2.db

# The same comparison using an indented second line
#compare = /mnt/databases/host1.db
#    /mnt/databases/host2.db
#
# File names can contain spaces, for example: compare = my database.db

# compare-filter: show only selected kinds of differences
# Values: checksum-mismatch, first-source, or second-source
# Default: all three categories
# This setting requires two database paths specified with compare
#
# checksum-mismatch shows files found in both databases with different checksums.
# first-source shows files in the first database that are missing from the second.
# second-source shows files in the second database that are missing from the first
#
# Repeating compare-filter combines the selected categories. Leaving this
# setting commented out shows all differences
# Example: show only files with different checksums
#compare-filter = checksum-mismatch
# Example: show files missing from either database
#compare-filter = first-source
#compare-filter = second-source