FolderTrace

FolderTrace is a local-first application for scanning folders and building a structured, persistent inventory of their contents.

It helps answer practical questions about large file collections:

• What files are in this folder?
• Which files are exact duplicates?
• What is stored inside my archives?
• What has changed since a previous scan?
• Can I recreate or verify this collection later?

FolderTrace is designed for general-purpose collections such as downloads, project archives, photo backups, and datasets. Mod folders are a useful example, but not the product's primary focus.

Install

FolderTrace requires Python 3.11 or later.

Latest development version

Install the latest version directly from GitHub:

pipx install git+https://github.com/LucasPullinger/FolderTrace.git

After installation:

foldertrace --help
foldertrace scan ~/Downloads
foldertrace summary

Run from source

To run FolderTrace from a local clone:

git clone https://github.com/LucasPullinger/FolderTrace.git
cd FolderTrace
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pytest

How it works

FolderTrace recursively scans a selected directory, collects metadata for every file, calculates SHA-256 hashes, optionally inspects supported archives, and stores the resulting manifest locally. It then analyses that manifest to surface duplicates and changes over time.

Select folder
    ↓
Scan files and collect metadata
    ↓
Calculate SHA-256 hashes
    ↓
Inspect supported archives
    ↓
Store manifest locally
    ↓
Analyse duplicates and changes

A file record may contain information like this:

{
  "path": "/Users/lucas/Downloads/project-final.zip",
  "name": "project-final.zip",
  "size": 34829102,
  "sha256": "a893...",
  "modified_at": "2026-09-03T10:24:00+01:00",
  "archive": {
    "type": "zip",
    "file_count": 142
  }
}

Features

The first release provides a small, reliable auditing workflow:

1. Recursively scan a folder and record each file's path, name, extension, size, and modification date.
2. Calculate SHA-256 hashes.
3. Detect and report exact duplicate files.
4. Recognise and inspect .zip, .tar, and .tar.gz archives without extracting them.
5. Persist scan manifests locally in SQLite.
6. Compare a new scan with an earlier one to report added, removed, changed, and unchanged files.
7. Identify possible filename-based version groups.
8. Export saved scans as JSON or CSV.
9. Reuse hashes from unchanged files to speed up repeated scans.
10. Exclude unwanted files with glob patterns or a .foldertraceignore file.

Archive records can include the number of contained files, total uncompressed size, and contained extensions.

Exact duplicates vs. possible versions

FolderTrace keeps these concepts deliberately separate.

Version grouping is intentionally conservative: a group is only shown when at least one filename contains a version number or date marker. It must never be presented as equivalent to hash-based duplicate detection.

Command-line interface

The application is a CLI:

foldertrace scan ~/Downloads
foldertrace summary
foldertrace scans
foldertrace duplicates
foldertrace archives
foldertrace versions
foldertrace changes --from 1 --to 2
foldertrace export manifest.json

Each scan is stored in SQLite at ~/.local/share/foldertrace/foldertrace.db by default. Use foldertrace --help for the complete command reference.

Exclude paths from a scan with repeated glob patterns:

foldertrace scan ~/Downloads --exclude "*.tmp" --exclude ".DS_Store"

You can also create a .foldertraceignore file in the scanned folder:

*.tmp
.DS_Store
.venv/*
node_modules/*

Repeated scans reuse SHA-256 hashes for files whose path, size, and modification time are unchanged. FolderTrace displays progress and reports reused versus newly calculated hashes.

An example comparison:

Scan changes: 1 → 2

Added:       12
Removed:      4
Changed:      7
Unchanged:  261

Proposed architecture

Python
│
├── Scanner             Finds files
├── Hasher              Calculates SHA-256
├── Archive Inspector   Reads archive contents
├── Database            Stores manifests
├── Analysis            Finds duplicates and changes
└── CLI                 Provides user commands

Technology

• Python 3.11+ — application language and standard-library support for filesystem scanning.
• Typer — command-line interface and argument validation.
• Rich — readable terminal tables and scan summaries.
• SQLite — local, serverless storage for persistent scan manifests.
• SQLAlchemy — Python database models and schema creation for the scans and files tables.
• pytest — automated scanner, CLI, hashing, and database tests.

hashlib provides SHA-256 hashing, while zipfile and tarfile inspect supported archives. FolderTrace runs entirely locally and does not require cloud services.

Roadmap

1. Add optional GUI support.
2. Add specialised plugins, such as a Nexus Mods integration.
3. Expand archive-format support, including .7z and .rar.
4. Improve scan filtering and reporting.

Non-goals

FolderTrace is not a file manager, backup program, antivirus product, cloud storage system, archive replacement, or mod manager. It analyses and records a collection so that it can be understood, verified, and compared over time.

Point FolderTrace at a directory. It creates a persistent inventory of the files, detects exact duplicates, and tells you what changed between scans.

License

FolderTrace is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE.