Skip to content

README.md

Latest commit

 

History

History
131 lines (90 loc) · 3.69 KB

README.md

File metadata and controls

131 lines (90 loc) · 3.69 KB

FilesWatch

The filesystem Night's Watch — standing guard so nothing slips past unnoticed.

FilesWatch is a small, cross-platform filesystem watcher built to catch every file and folder an installer, uninstaller, updater, or test cycle leaves behind.

Why it exists

When you're rapidly installing, uninstalling, and re-testing software, "uninstall" rarely means clean. Over time a program can leave behind:

  • config files that get silently reused on the next install
  • caches that change startup behaviour in ways you didn't expect
  • temp and log folders that mask fresh failures with stale data
  • state directories that make a broken reinstall look healthy
  • migration leftovers that only surface after several install/remove cycles

Tracking these down manually is tedious. FilesWatch solves it by standing watch before the activity starts and giving you a precise, timestamped record of everything that changed while it ran.

Requirements

Python 3.12+ and the watchdog library.

pip install watchdog

Usage

# Watch a directory in the foreground
python fileswatch.py /path/to/watch

# Watch multiple paths
python fileswatch.py ~/test-app ~/.config/myapp --log-dir ./fw-logs

# Run in the background
python fileswatch.py ~/test-app --log-dir ./fw-logs --daemon

# Query what changed in the last hour
python fileswatch.py -q -1h --log-dir ./fw-logs

# Query what changed in the last 10 minutes
python fileswatch.py -q -10m --log-dir ./fw-logs

# Query what changed in the last day
python fileswatch.py -q -1day --log-dir ./fw-logs

# Query from an absolute ISO timestamp
python fileswatch.py -q 2025-01-01T00:00:00 --log-dir ./fw-logs

# Grep the text log for a pattern
python fileswatch.py -g settings --log-dir ./fw-logs

Typical workflow

Start FilesWatch before you run the installer:

python fileswatch.py ~/.config/myapp ~/.cache/myapp /tmp --log-dir ./fw-logs

Run the installer. Uninstall it. Reproduce the issue. Then inspect what changed:

# Everything from the last test run
python fileswatch.py -q -30m --log-dir ./fw-logs

# Find any settings files that were touched
python fileswatch.py -g settings --log-dir ./fw-logs

Output

FilesWatch writes two log files into the log directory:

File Format Best for
changes.jsonl One JSON object per line Scripting, filtering with jq
changes.txt Plain timestamped text Quick grep in the terminal

Example JSONL entry:

{"timestamp": "2026-05-21T15:42:10.123", "event_type": "CREATE", "path": "/home/dan/.config/myapp/settings.json"}

Relative query values

The -q / --query flag accepts either an ISO timestamp or a relative offset from now.

Input Meaning
-30s last 30 seconds
-10m last 10 minutes
-1h last hour
-1day last 24 hours
-2hrs last 2 hours
2025-01-01T12:00:00 after an absolute timestamp

Config file

Place a config.ini next to the script to set persistent defaults.

[monitor]
paths = /path/one /path/two
log_dir = ./fw-logs
daemon_mode = false
ignore_paths = /path/to/ignore

[logging]
service_name = fileswatch
log_level = INFO

Platform notes

Platform Observer used
Windows (native) WinAPI via watchdog
Linux (native) inotify via watchdog
WSL2 — Linux paths inotify via watchdog
WSL2 — Windows mounts (/mnt/c/...) PollingObserver (inotify does not work on NTFS mounts)
Network shares (cifs/nfs) PollingObserver

FilesWatch auto-detects the filesystem type and chooses the right observer without any configuration.

License

This project is licensed under the MIT License. See LICENSE for details.