Setting Up the Tool Properly the First Time
I keep seeing people download this thing and then immediately hit a wall because they don't set up their input path correctly. I spent about three hours debugging a failed batch run on my own machine before realizing the issue was just a trailing backslash in the directory string. The program reads it literally and treats your entire C drive as a single filename. Once I stripped the trailing slash and pointed it at a clean subdirectory, the first pass ran in roughly 20 minutes across about 14,000 files. The installation is straightforward enough, but the configuration file is where things get tricky. You're editing a JSON structure, not clicking through a wizard. If you're coming from a GUI background, this part feels unnecessarily opaque. Here's what actually matters: the scan_depth parameter, the exclusion list, and the conflict_resolution mode. Most people leave conflict_resolution at its default value, which is append_with_timestamp. That creates duplicates like report_final_v2_20260715 instead of actually deciding what stays. I switched mine to overwrite_larger and it cut my output folder size by nearly 60 percent.
Decluttering Tutorial Comprehensive
This is the full walkthrough. I'm not going to reorganize my notes by topic. I'm going to write it in the order I actually use the tool. Step one is getting the package. It's hosted on GitHub under the name "declutter-tutorial-comprehensive" — yes, the repo name is verbose, but that's what shows up when you search for it. Clone it or download the latest release. The release version comes with pre-built binaries for Windows, macOS, and Linux. I run it on Ubuntu 22.04 inside a WSL2 instance. There are no dependencies beyond Python 3.10 or later. No pip install mess, no virtual environment required unless you want one. Step two is the config file. Create a file called declutter_config.json in the project root. Here's a minimal working version:
{
"source_path": "/home/youruser/documents/projects/",
"output_path": "/home/youruser/documents/decluttered/",
"scan_depth": 3,
"conflict_resolution": "overwrite_newer",
"exclude_patterns": ["*.tmp", "*~", ".DS_Store", "node_modules/", "__pycache__/"],
"max_file_age_days": 90,
"log_level": "info"
} The scan_depth setting controls how many directory levels the tool traverses from your source_path. A value of 3 means it looks three folders deep. I usually set mine to 2 because deeper scans hit diminishing returns and significantly longer runtime. With scan_depth at 5 on a typical project folder, the first pass took about 45 minutes. At scan_depth 2, it takes roughly eight minutes. Pick based on your actual structure, not your hope for what the structure might become. Step three is running it. Open a terminal, navigate to the project directory, and execute:
Get the Full Details
python main.py --config declutter_config.json That's it. The tool will scan the source, identify conflicts and stale files, apply your conflict_resolution strategy, and write cleaned results to the output path. You'll see progress logged to stdout and also written to declutter_log.txt in the project root. There's a dry-run mode I strongly recommend using before your first real execution. Add --dry-run to the command and nothing gets moved or deleted. It just prints what it would do. I run this on every new folder I point the tool at, because the output of the dry run tells you whether your exclusion patterns are too broad or too narrow. On one project I accidentally excluded *.log which was meant to catch just application logs but ended up skipping dozens of legitimate text-based log files that were actually useful references. I caught it in the dry run before any files were affected.
One thing the documentation doesn't emphasize enough is how the tool handles symlinks. By default, it follows them. If your source directory has symbolic links pointing to external drives or network shares, the tool will traverse into them and process everything underneath. This turned a 10-minute scan into a 47-minute one when I had an old symlink to a Time Machine backup lying around. The workaround is setting follow_symlinks to false in your config. I wish I'd known that before burning through an evening trying to figure out why the runtime exploded. The edge case I mentioned earlier — the one that cost me actual time — involved files with identical names but different extensions sitting in the same directory. The tool's default behavior for name conflicts within the same depth level is to create a subfolder named after the base filename and place all variants inside it. So report.pdf and report.docx both land in a folder called report/. That sounds reasonable until you realize it breaks any script or workflow that expects those files to be at the top level of your output directory. I wrote a post-processing shell script that flattens the output tree while deduplicating by hash, and it runs automatically after each declutter pass. It adds about 30 seconds to the total workflow but saves me from having to manually reorganize afterward. There are real limitations to this approach. The tool does not handle binary files intelligently. It treats a PDF the same way it treats a WAV file — by extension and metadata alone. If you have thousands of image files with mismatched or missing EXIF data, the deduplication by content hash helps, but the tool will still struggle to decide which version of a slightly corrupted image is the "winner." I've seen it consistently pick a lower-resolution copy over a higher-resolution one when both had the same filename, because it was comparing file timestamps rather than image dimensions. There's no built-in quality comparison. You'd need to pipe the output through something like ImageMagick or exiftool for post-processing if that matters to you.
Another bottleneck is memory usage on large source trees. The tool loads file metadata into memory before processing. I ran it against a folder with roughly 200,000 files and it consumed about 1.2 GB of RAM during the scan phase. Not catastrophic, but noticeable if you're running this on a machine with limited resources or alongside other heavy processes. Splitting your source into smaller batches and running separate passes is the practical workaround, and it actually completes faster because each individual scan finishes sooner and you can monitor progress between runs. A counter-intuitive thing I learned is that running the tool more frequently on smaller chunks produces cleaner results than running it once a month on a massive accumulation. The conflict resolution logic works best when the delta between scans is small. When you let files pile up for weeks, the tool encounters more ambiguous cases and makes more conservative choices, which means more files end up in quarantine or duplicate folders rather than being cleanly resolved. I switched from monthly runs to weekly runs and my output folder has been consistently 30-40 percent smaller on each pass since making that change. If you're dealing with a truly messy directory — say, a folder that's been accumulating files for years with no structure at all — this tool will help but it won't fix everything. It's designed for ongoing maintenance, not emergency cleanup of a decade's worth of ignored downloads. For that situation, I'd recommend running a one-time manual sort first, maybe with a different tool like fslint or just a well-written find command, and then switching to this tool for regular upkeep. The combination gets you further than either approach alone.
The GitHub repo is at github.com/declutter-tutorial-comprehensive. The README has a few examples but they're brief. The real understanding comes from running it yourself and watching the log output. Pay attention to the conflict warnings in the log file. Those lines tell you exactly which files the tool was unsure about and what decision it made. If you see a pattern of the same type of file being mishandled repeatedly, you can adjust your exclusion patterns or conflict resolution strategy accordingly. That iterative tuning is where the actual skill lies, not in memorizing the config syntax. Bottom line: it works if you configure it carefully, run it often, and accept that it will never be fully automatic for messy inputs. Set up a cron job or a simple launchd timer, point it at your active project directories, and let it run weekly. The manual intervention drops to almost nothing after the first month or two of consistent use.
