📦 Dumped It!

Automatic, zero-dependency, cross-platform file dumper that organizes incoming downloads into customizable date-formatted subfolders.

---

⚡ What is Dumped It!?

Dumped It! is an ultra-lightweight background automation daemon for macOS, Linux, and Windows.

Unlike traditional file sorters that fragment your downloads into confusing extension categories (PDFs/, Videos/, Images/), Dumped It! preserves your raw files exactly as they are—dumping them directly into clean, chronologically formatted date subfolders inside your preferred target directory.

📥 ~/Downloads/ (Watch Directory)
       │
       └── 📦 ~/Downloads/Dumped-It/ (Target Directory)
              ├── 📁 23-Aug-2026/
              │      ├── contract.pdf
              │      └── image.png
              ├── 📁 22-Aug-2026/
              │      └── archive.zip
              └── 📁 01-Jan-1980/

---

⚡ One-Liner Fast Install

Install Dumped It! in seconds using your terminal:

🍏 macOS & 🐧 Linux

curl -sSL https://raw.githubusercontent.com/zaryif/dumped-it/main/install.sh | bash

🪟 Windows (PowerShell)

irm https://raw.githubusercontent.com/zaryif/dumped-it/main/install.ps1 | iex

---

🚀 Key Features

• 🚀 Zero External Dependencies: Standard Python 3 library only. No pip install required!
• 📅 Flexible Date/Time Formatting: Supports presets (DD-Mon-YYYY, YYYY-MM-DD, DD-MM-YYYY, MM-DD-YYYY, YYYY-MM, hourly) or any custom strftime pattern.
• 🛡️ In-Progress Download Protection: Detects and ignores .crdownload, .part, .tmp, and incomplete browser writes.
• 💥 Collision Prevention: Automatically appends (1), (2) if identical filenames exist in the date folder.
• ⚡ Cross-Platform Background Daemons: Native integration with macOS launchd, Linux systemd, and Windows Startup.
• 🔧 CLI & Config Modes: Customize watch folders, dump targets, and polling intervals via JSON config or command-line flags.

---

🛠️ Usage & CLI Reference

Run a single pass or start the background monitoring daemon:

# Run a single organizing pass and exit
dumped-it --once

# Run as a continuous background daemon
dumped-it --daemon

# Dry-run mode (preview changes without moving files)
dumped-it --dry-run

# Custom watch folder, dump target, and ISO date format (2026-08-23)
dumped-it --watch-dir ~/Desktop --dump-dir ~/Desktop/Dump --date-format iso

🗓️ Available Date Format Presets

Preset	Output Format Example	Description
default	23-Aug-2026	Day-AbbreviatedMonth-Year
iso	2026-08-23	ISO Standard YYYY-MM-DD
eu	23-08-2026	European DD-MM-YYYY
us	08-23-2026	US standard MM-DD-YYYY
month	2026-08	Monthly folder grouping
hourly	2026-08-23_14-00	Hourly snapshot folders
Custom	%Y/%m/%d	Any custom Python strftime string

---

⚙️ Configuration (config.json)

The default configuration file is created automatically at:

• macOS/Linux: ~/.config/dumped-it/config.json
• Windows: %APPDATA%\dumped-it\config.json

{
  "watch_dir": "~/Downloads",
  "dump_dir": "~/Downloads/Dumped-It",
  "date_format": "default",
  "poll_interval": 2.0,
  "date_source": "mtime",
  "ignored_files": [
    ".DS_Store",
    ".localized",
    "desktop.ini",
    "thumbs.db"
  ]
}

---

🖥️ Background Service Setup

🍏 macOS (launchd)

To run automatically on login:

# Load daemon
launchctl load ~/Library/LaunchAgents/com.zaryif.dumpedit.plist

# Unload / Stop daemon
launchctl unload ~/Library/LaunchAgents/com.zaryif.dumpedit.plist

🐧 Linux (systemd)

# Enable & start user service
systemctl --user enable --now dumped-it.service

# Check service status
systemctl --user status dumped-it.service

🪟 Windows (Startup Folder)

The PowerShell installer automatically places a shortcut in your Startup folder (shell:startup). To manage manually:

• Open Run (Win + R), type shell:startup, and manage the DumpedIt.lnk shortcut.

---

📜 License

Distributed under the MIT License. See LICENSE for details.

---

⭐ Support the Project

If Dumped It! saved you hours of manual file cleanup, consider giving this repository a ⭐ Star on GitHub!