Metadata-Version: 2.4
Name: foldertrace
Version: 0.1.0
Summary: A local-first file collection auditing tool.
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typer>=0.12
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# 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:

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

After installation:

```bash
foldertrace --help
foldertrace scan ~/Downloads
foldertrace summary
```

## Run from source

To run FolderTrace from a local clone:

```bash
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.

```text
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:

```json
{
  "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.

| Finding                | Meaning                                                                             | Confidence   |
| ---------------------- | ----------------------------------------------------------------------------------- | ------------ |
| Exact duplicate        | Files have the same SHA-256 hash.                                                   | Definitive   |
| Possible version group | Filenames suggest related releases, such as`tool-v1.0.zip` and `tool-v2.0.zip`. | Interpretive |

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:

```bash
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:

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

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

```text
*.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:

```text
Scan changes: 1 → 2

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

## Proposed architecture

```text
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](LICENSE).
