tidyup 0.0.4

Help keep your files and folders tidy by file type or date

Tidyup 🧹

Sweep up your files into organized folders by date and/or extension.

Description

tidyup helps organize messy directories by moving eligible files into a predictable folder structure.

Install

pip install tidyup

Usage

tidyup [-h] [-e] [-d] [-r] [-L DEPTH] directory

Options

• -e: organize by extension
• -d: organize by file modified date (year/month)
• -r, --rearrange: traverse subdirectories recursively
• -L, --depth: recursion depth (valid only with -r)

Ordering Behavior

Order is preserved:

• -de => year/month/extension/file
• -ed => extension/year/month/file

Recursive Behavior

• -r without -L defaults to depth 2
• -L without -r is invalid

Exclusion Behavior

By default, tidyup excludes:

• hidden files (dotfiles)
• names/suffixes in the internal exclusion list (for example requirements.txt, config.json)
• files without an extension
• multi-extension files are grouped by their final suffix (for example archive.tar.gz goes to gz/)

Collision Behavior

• tidyup never overwrites an existing destination file
• if a destination filename already exists, that move is skipped and a message is printed
• when multiple source files would target the same destination in one run, tidyup processes them in a stable path order so the outcome stays deterministic

Examples

# Organize top-level files by extension
tidyup -e /path/to/dir

# Organize top-level files by date
tidyup -d /path/to/dir

# Organize by extension then date
tidyup -ed /path/to/dir

# Organize by date then extension
tidyup -de /path/to/dir

# Recursive organize by date, default depth=2
tidyup -r -d /path/to/dir

# Recursive organize by extension, default depth=2
tidyup -r -e /path/to/dir

# Recursive organize by extension at depth 3
tidyup -r -L 3 -e /path/to/dir

# Recursive organize by date at depth 3
tidyup -r -L 3 -d /path/to/dir

Quality Gate

Run the same baseline checks locally that CI uses before release or publishing:

python3 -m pip install -e .[test] || python3 -m pip install -e . pytest
python3 -m pytest -q
python3 -m tidyup -h