A small Java CLI that tidies a folder by moving files into category folders
(Documents, Images, Videos…) based on their extension — with a safe dry-run by default.

Install · Usage · Docs · Security

	One JDK, no install Run a self-contained jar, or use the launchers.		Safe by default Dry-run preview, full undo, repo-aware.
	Scriptable Flags, JSON output, exit codes.		Tested everywhere CI on Linux, macOS & Windows.

---

What it does

Point Neatify at a messy folder and it sorts every file into a tidy set of category folders, driven by simple extension rules. It previews changes by default (dry-run), journals every run so you can undo it, and refuses to touch Git repos or system directories.

Before — a messy ~/Downloads:

~/Downloads/
├── report.pdf
├── invoice.docx
├── photo.png
├── screenshot.png
├── song.mp3
├── movie.mkv
└── archive.zip

After — neatify --source ~/Downloads --use-default-rules --apply:

~/Downloads/
├── Documents/
│   ├── report.pdf
│   └── invoice.docx
├── Images/
│   ├── photo.png
│   └── screenshot.png
├── Music/
│   └── song.mp3
├── Videos/
│   └── movie.mkv
└── Archives/
    └── archive.zip

---

Quick start

Requires Java 21+ (a JDK). That's the only thing you need — the jar is self-contained.

Install (download the release)

Grab the latest neatify-<version>.jar from the releases page and run it:

# Download
curl -LO https://github.com/Baylox/neatify/releases/latest/download/neatify-1.0.1.jar

# Optional: verify the checksum
curl -LO https://github.com/Baylox/neatify/releases/latest/download/neatify-1.0.1.jar.sha256
sha256sum -c neatify-1.0.1.jar.sha256

# Run it
java -jar neatify-1.0.1.jar                                          # interactive menu
java -jar neatify-1.0.1.jar --source ~/Downloads --use-default-rules # preview (dry-run)

Build from source

git clone https://github.com/Baylox/neatify.git
cd neatify
./mvnw package        # build target/neatify.jar  (.\mvnw.cmd on Windows)

Building also gives you the launchers — ./neatify (Linux/macOS/WSL) and .\neatify.cmd (Windows) — which run the jar so you never type java -jar again.

---

Usage

./neatify                                                   # interactive menu
./neatify --source ~/Downloads --use-default-rules          # preview (dry-run)
./neatify --source ~/Downloads --use-default-rules --apply  # actually move files
./neatify --source ~/Downloads --undo                       # revert the last run

_{On Windows, use .\neatify.cmd (or java -jar neatify-1.0.1.jar).}

Shortcuts (Linux/macOS/WSL) — a Makefile wraps the common flows:

make run                      # interactive mode
make preview DIR=~/Downloads  # dry-run on DIR
make apply   DIR=~/Downloads  # organize DIR for real
make help                     # list all targets and variables

---

Documentation

Full docs live in docs/:

Guide	What's inside
Getting started	Install, build, first run
Interactive mode	The menu-driven flow
Rules	Map extensions to folders (+ built-in defaults)
Undo	Reverse a run
CLI reference	Every option (generated from the code)
JSON output	Machine-readable results
Architecture	How it works
Security	Protections and rationale
API (Javadoc)	Generated from the source

---

Safety by default

Dry-run first	Nothing moves until you pass --apply.
Undo any run	Every run is journaled under .neatify/runs/.
Repo-aware	Refuses --apply inside Git/VCS worktrees.
Path-safe	Blocks system dirs, path traversal and symlink escapes.
Atomic moves	Collision strategy (rename / skip / overwrite), no silent overwrite.

---

Quality gate

./mvnw verify runs the full gate: Enforcer (JDK 21+), JUnit 5, JaCoCo (≥ 55% line coverage), Spotless, SpotBugs and PMD — and the CI runs it on Linux, macOS and Windows, plus CodeQL scanning.

./mvnw spotless:apply           # auto-format
./mvnw verify -Psecurity-scan   # OWASP CVE scan (set NVD_API_KEY)

_{On a network share without file locking (e.g. \\wsl.localhost from Windows), redirect the build dir: ./mvnw verify -Dneatify.buildDirectory=C:\tmp\neatify-target.}

---

License

MIT © Baylox