- version
- 2.0.0
- name
- tidyfiles
- description
- Sort and organize files into folders by type, date, or rules. Use when decluttering dirs, checking structure, running cleanup, generating reports.
Tidyfiles
A versatile utility toolkit for recording, tracking, and managing file organization tasks from the command line. Each command logs timestamped entries to its own dedicated log file, with built-in statistics, multi-format export, search, and health-check capabilities.
Why Tidyfiles?
- Works entirely offline — your data stays on your machine
- Each command type maintains its own log file for clean data separation
- Built-in multi-format export (JSON, CSV, plain text)
- Full activity history with timestamped audit trail
- Search across all log files instantly
- Summary statistics with entry counts and disk usage
- Zero external dependencies — pure bash
Commands
Core Operations
| Command | Description |
|---|---|
tidyfiles run <input> | Record a run entry (no args: show recent entries) |
tidyfiles check <input> | Record a check entry (no args: show recent entries) |
tidyfiles convert <input> | Record a convert entry (no args: show recent entries) |
tidyfiles analyze <input> | Record an analyze entry (no args: show recent entries) |
tidyfiles generate <input> | Record a generate entry (no args: show recent entries) |
tidyfiles preview <input> | Record a preview entry (no args: show recent entries) |
tidyfiles batch <input> | Record a batch entry (no args: show recent entries) |
tidyfiles compare <input> | Record a compare entry (no args: show recent entries) |
tidyfiles export <input> | Record an export entry (no args: show recent entries) |
tidyfiles config <input> | Record a config entry (no args: show recent entries) |
tidyfiles status <input> | Record a status entry (no args: show recent entries) |
tidyfiles report <input> | Record a report entry (no args: show recent entries) |
Utility Commands
| Command | Description |
|---|---|
tidyfiles stats | Show summary statistics (entry counts per type, total, disk usage) |
tidyfiles export <fmt> | Export all data in json, csv, or txt format |
tidyfiles search <term> | Search across all log files (case-insensitive) |
tidyfiles recent | Show the 20 most recent activity log entries |
tidyfiles status | Health check (version, entries, disk, last activity) |
tidyfiles help | Display all available commands |
tidyfiles version | Print version string |
Each core command works in two modes:
- With arguments: Saves a timestamped entry to
<command>.logand logs tohistory.log - Without arguments: Displays the 20 most recent entries from that command's log
Data Storage
All data is stored locally in ~/.local/share/tidyfiles/. The directory contains:
run.log,check.log,convert.log,analyze.log, etc. — One log file per command type, storingYYYY-MM-DD HH:MM|inputentrieshistory.log— Unified activity log with timestamped records of every command executedexport.json/export.csv/export.txt— Generated export files
Requirements
- Bash 4.0+ with
set -euo pipefailstrict mode - Standard Unix utilities:
grep,cat,tail,wc,du,date,sed - No external dependencies or network access required
When to Use
- Tracking file organization tasks — Use
tidyfiles run "sorted ~/Downloads by file type"to log cleanup activities with timestamps - Checking directory structure — Record structure checks with
tidyfiles check "~/projects: 45 dirs, 230 files, no empty dirs" - Analyzing disk usage patterns — Log analysis results with
tidyfiles analyze "Documents folder: 12GB, 40% PDFs"and review withtidyfiles search "Documents" - Batch file operations — Track batch processing with
tidyfiles batch "renamed 150 photos with date prefix"and review past batches - Generating cleanup reports — Use
tidyfiles report "weekly cleanup: freed 3.2GB"thentidyfiles export csvfor spreadsheet analysis
Examples
# Record file organization activities
tidyfiles run "organized Downloads into subfolders"
tidyfiles check "verified backup integrity: 100% match"
tidyfiles analyze "home directory: 85GB used, 15GB free"
# Track conversions and batch operations
tidyfiles convert "batch converted 200 PNGs to WebP"
tidyfiles batch "moved archived projects to cold storage"
tidyfiles generate "created folder structure for new project"
# Preview and compare
tidyfiles preview "dry-run sort of ~/Desktop: 45 files to move"
tidyfiles compare "before/after cleanup: 12GB freed"
# Search, review, and export
tidyfiles search "backup"
tidyfiles recent
tidyfiles stats
tidyfiles export json
tidyfiles export csv
# Configuration and reporting
tidyfiles config "default sort: by extension"
tidyfiles report "monthly cleanup summary: 25GB reclaimed"
tidyfiles statusConfiguration
The data directory defaults to ~/.local/share/tidyfiles/. All log files are plain text with pipe-delimited fields (timestamp|value), making them easy to parse with standard Unix tools or import into spreadsheets.
Powered by BytesAgain | bytesagain.com | hello@bytesagain.com