FolderContentsLogger

FolderContentsLogger is a Python utility for generating directory inventory snapshots and detecting when expected directories are missing or empty.

It is designed for homelab / server environments where you want:

• repeatable directory audits
• clear, timestamped inventory files
• centralized logging
• email alerts only when something is wrong
• separation between data collection and retention / cleanup

This repository contains both a legacy implementation (V1) and the current, actively maintained implementation (V2).

---

Repository Structure

FolderContentsLogger/
├── V1/
│   ├── FolderContentsLogger.py
│   └── directories.txt
│
├── V2/
│   ├── FolderContentsLogger_2.py
│   ├── FolderContentsLogger_2.1.py
│   ├── folder_contents_logger.config
│   └── folder_contents_lists/   (generated output, gitignored)
│
├── .gitignore
└── README.md

---

V1 (Legacy)

V1/ contains the original implementation and is retained for reference.

Characteristics:

• static input file (directories.txt)
• basic directory listing
• no email alerts
• no centralized logging
• no configuration system

V1 is not under active development.

---

V2 (Current)

V2/ is the current, production-ready version.

Key Features

• INI-based job configuration
• Multiple independent directory jobs per run
• Per-job validation (missing or empty directories)
• Timestamped folder inventory snapshots
• Centralized logging
• Email alerts only on failure
• Safe for cron and automation
• No deletion logic (read-only inventory)

What Triggers an Alert

An email alert is sent if any job:

• points to a path that does not exist
• points to a directory that exists but is completely empty

A single alert email summarizes:

• failed jobs
• successful jobs
• host information
• IP addresses
• log file location

---

Configuration

Jobs are defined in:

V2/folder_contents_logger.config

Each job specifies:

• a root directory
• whether to list directories and/or files
• depth limits

Example:

[job:plex_tv_shows]
root_dir = /mnt/plex_tv/tv_shows
include_dirs = true
dirs_max_depth = 1
include_files = false

---

Output

Folder Inventory Lists

For each job, FolderContentsLogger writes a timestamped inventory file to:

V2/folder_contents_lists/

File naming format:

folder_inventory_<job>_<hostname>_<timestamp>.txt

This directory is generated output and is intentionally excluded from git.

Logs

Execution logs are written to a centralized log directory (configured per-host). Retention of logs is handled externally.

---

Email Notifications

FolderContentsLogger sends alert emails using a system-installed Python package:

from python_email_notify import EmailSender

That functionality is provided by: https://github.com/killermelon1458/PythonEmailNotify

Email credentials and SMTP settings are loaded from a shared environment file:

~/.config/obtuse/env

Credentials are never stored in this repository.

---

Retention

FolderContentsLogger never deletes files.

Retention and cleanup of:

• logs
• inventory files

is handled by a separate project:

https://github.com/killermelon1458/retention_engine

This separation is intentional and keeps FolderContentsLogger strictly read-only.

---

Running Manually

source ~/.config/obtuse/env
python3 FolderContentsLogger_2.1.py --config folder_contents_logger.config

---

Running via cron

cron does not load shell startup files. Use a wrapper script that explicitly sources the environment file.

Example wrapper:

#!/bin/bash
source "$HOME/.config/obtuse/env"
python3 /full/path/to/FolderContentsLogger_2.1.py --config folder_contents_logger.config

Example cron entry:

0 2 * * * /home/obtuse/bin/run_folder_contents_logger_v2.sh

---

Design Philosophy

• Read-only by design – no destructive operations
• Explicit configuration – no hidden defaults
• Failure-focused alerts – silence on success
• Composable tooling – integrates cleanly with other automation

---

Status

V2 is considered stable and production-ready. Future development will continue in the V2/ directory.