FileIV - File Integrity Validator

A tool for verifying file integrity by scanning directories and comparing file hashes against previous records to detect changes. By generating diff report, users can review changes and manually restore data from backups in the event of corruption or with the purpose of restoring changes.

---

Installation

1. Go to the project’s Releases page.
2. Download the latest .zip file for your platform.
3. Unzip it to a directory of your choice and you're good to go!

---

Supported Features

Name	Description	Version	Status
Scan	Scan directory and generates a diff report.
Apply	Apply diff report to database.
Duplicate Scan	Scan for duplicate files based on directories and databases provided.
Search	Search files by name or file hashes.

---

Code Documentations

The documentation for the code is provided at maythaswang.github.io/documentations/fileiv

---

Cli Manual

scan(1)

NAME

scan - Scan directory and generates a diff report for post-processing.

SYNOPSIS

fileiv scan [OPTIONS]

DESCRIPTION

scan - Iterates through all subdirectories under the provided --root directory and generates a diff report. If --database is provided, the scan will reference the existing database and check discrepancies between the current filesystem and the previous records. By default, it creates a new diff file in the current directory named diff_untitled_yyyyMMdd_HHmmss.csv using the current time. This default behaviour can be overridden using other options.

OPTIONS

Option	Aliases	Optional	Description
--root <path>	-r	No (Required)	Root directory to scan for generating hashes for diffs.
--database <path>	-d	Yes	Path to the SQLite database used for referencing file changes.
--out <path>	-o	Yes	Path for the new diff report file. By default, overwrites existing file.
--name <string>	-n	Yes	Name for the output file, e.g., diff_{name}_yyyyMMdd_HHmmss.csv.
--no-write	-	Yes	Write the diff report to stdout instead of to a file.
--ignore	-i	Yes	List of path-independent files to read for ignore configuration. Follows .gitignore standard. The path provided must be comma separated file_1,file_2,file_3,...,file_n.

EXAMPLES

Scanning directory without existing database.

fileiv scan -r ./

Scanning directory with an existing database

fileiv scan -d ./database.db -r ./

Output diff report to stdout

fileiv scan -r ./ --no-write

Naming output file explicitly

fileiv scan -r ./directory/ -o ./out.csv

Naming output file using the default naming convention

fileiv scan -r ./scandir/ -o ./outdir/ -n not_untitled

EXIT CODES

Code	Description
0	Successful
1	General error
2	Invalid arguments or Missing files

---

apply(1)

NAME

apply - Apply changes using diff and database inputs to SQLite database.

SYNOPSIS

fileiv apply [OPTIONS]

DESCRIPTION

apply - Reads a diff file and applies the changes to the specified SQLite database. By default, it creates a new database file in the current directory named db_untitled_yyyyMMdd_HHmmss.db using the current time. This default behaviour can be overridden using other options.

OPTIONS

Option	Aliases	Optional	Description
--diff <path>	-f	No (Required)	Path to the diff file to apply updates.
--database <path>	-d	Yes	Path to the SQLite database used for referencing updates. Updated if --update-db is set.
--out <path>	-o	Yes	Path for the new database file. By default, overwrites existing file. Ignored if --update-db is set.
--name <string>	-n	Yes	Name for the output file, e.g., db_{name}_yyyyMMdd_HHmmss.db.
--update-db	-	Yes	Update the database provided by --database in place instead of creating a new file.

EXAMPLES

Applying diff without existing database.

fileiv apply -f changes.diff

Apply diff using an existing database.

fileiv apply -f changes.diff -d old_db.db -o new_db.db

Apply diff to the same database.

fileiv apply -f changes.diff -d database.db --update-db

Naming output file explicitly

fileiv apply -f changes.diff -d database.db -o ./newfile.db

Naming output file using the default naming convention

fileiv apply -f changes.diff -d database.db -o ./dir/ -n not_untitled

EXIT CODES

Code	Description
0	Successful
1	General error
2	Invalid arguments or Missing files

---

dup-scan(1)

NAME

dup-scan - Scan directories and load databases to generate a duplicate report.

SYNOPSIS

fileiv dup-scan [OPTIONS]

DESCRIPTION

dup-scan - Iterates through all subdirectories under the specified --roots directories and loads all databases provided via --databases. The command will then generate a report of duplicates based on file hashes. Either --roots or --databases must be present. By default, it creates a new report file in the current directory named dupe_untitled_yyyyMMdd_HHmmss.json using the current time. This default behaviour can be overridden using other options.

OPTIONS

Option	Aliases	Optional	Description
--roots <paths>	-r	Conditionally	Root directories to scan for duplicate checks. The path provided must be comma separated file_1,file_2,file_3,...,file_n. Required if --databases not provided.
--databases <paths>	-d	Conditionally	Path to the SQLite database for referencing file changes. The path provided must be comma separated file_1,file_2,file_3,...,file_n. Required if --roots is not provided.
--out <path>	-o	Yes	Path for the new duplicate report file. By default, overwrites existing file.
--name <string>	-n	Yes	Name for the output file, e.g., dupe_{name}_yyyyMMdd_HHmmss.json.
--no-write	-	Yes	Write the diff report to stdout instead of to a file.
--ignore	-i	Yes	List of path-independent files to read for ignore configuration. Follows .gitignore standard. The path provided must be comma separated file_1,file_2,file_3,...,file_n.

EXAMPLES

Scanning directories only

fileiv dup-scan -r "./,./directory1,/usr/something/"

Scanning directories and databases

fileiv dup-scan -d "./file.db,file2.db" -r "./,./directory1,/usr/something/"

Output diff report to stdout

fileiv dup-scan -r ./ --no-write

Naming output file explicitly

fileiv dup-scan -r ./directory/ -o ./out.json

Naming output file using the default naming convention

fileiv dup-scan -r ./scandir/ -o ./outdir/ -n not_untitled

EXIT CODES

Code	Description
0	Successful
1	General error
2	Invalid arguments or Missing files

---

search(1)

NAME

search - search file record in databases by filehash or filename.

SYNOPSIS

fileiv search [OPTIONS]

DESCRIPTION

search - Reads the file record from the one or more SQLite databases and return a report containing all entries matching the provided filenames or filehashes. By default, it creates a new report file in the current directory named search_untitled_yyyyMMdd_HHmmss.json using the current time. This default behaviour can be overridden using other options.

OPTIONS

Option	Aliases	Optional	Description
--databases <paths>	-d	No	Path to the SQLite database for searching records. The path provided must be comma separated file_1,file_2,file_3,...,file_n.
--out <path>	-o	Yes	Path for the new search report file. By default, overwrites existing file.
--name <string>	-n	Yes	Name for the output file, e.g., search_{name}_yyyyMMdd_HHmmss.json.
--filenames <list>	-f	Yes	List of path-independent filenames to search for. The path provided must be comma separated file_1,file_2,file_3,...,file_n.
--filehashes <list>	-h	Yes	List of file hashes to search for. The path provided must be comma separated hash_1,hash_2,hash_3,...,hash_n.
--fileinputs <path>	-i	Yes	Path to input files to be parsed to search for records. The path provided must be comma separated file_1,file_2,file_3,...,file_n.
--no-write	-	Yes	Write the search report to stdout instead of to a file.

FILE INPUT FORMAT A file passed using --fileinput must follow the section-based format below.

• [FILENAMES] - list of path-independent file names.
• [FILEHASHES] = list of file hashes.
• Lines beginning with # are treated as comments.

# Search by file names
[FILENAMES]
test.txt
file.csv
README.md

# Search by file hashes
[FILEHASHES]
df7c9f1ed0c518add7dc290e55df6d3ef2f856acf05a93cf0f77fdcef788af15

EXAMPLES

EXIT CODES

Code	Description
0	Successful
1	General error
2	Invalid arguments or Missing files

---

AUTHOR

Maythas Wangcharoenwong

LICENSE

This project is licensed under the GNU General Public License v3.0. See the full license at: https://www.gnu.org/licenses/gpl-3.0.html

---