Reny

A lightweight, fast, and safe batch renaming and filesystem organization tool.

Background

reny was originally created as the renamer component inside the larger batchmp (Batch Media Processing) suite. It was spun off into its own standalone package to provide for a lightweight, safe, pure-filesystem organizing tool without FFmpeg / Mutagen media dependencies.

If you need advanced media operations (like denoising, cover-art extraction, or format transcoding), check out the original batchmp project. If you just need to safely organize your files with surgical precision, reny is all you need.

Installation

You can safely install reny from the PyPI package using pipx:

pipx install reny

(Note: If this is your first time using pipx, you may need to run pipx ensurepath once to ensure the installed tools are available in your terminal).

Features

• Dry-Run by Default: reny will always visualize targeted changes and ask for confirmation before it ever touches your files
• Virtual Views: Preview how a directory structure would look when reorganised by type, size, or date without moving or changing anything
• Filtering & Leveling: Precise targeting using include/exclude patterns and recursion control with end_level / start_level parameters
• Indexing: Multi-level indexing across nested directories, supporting multiple indexing schemes
• Padding: Automatically pad existing numbers in filenames with leading zeros to fix sorting orders
• Flattening: Safely collapse nested directory structures into a single folder
• Regex Replacement: Powerful batch renaming using standard regular expressions
• Git Integration: Automatically detects and displays file and directory modification statuses using --git
• Color Outputs: Rich terminal highlighting for different file types using --color, grouping extensions visually

Examples

Basic Operations

Print current directory structure:

reny

(Without arguments, reny defaults to the print command)

Limit Recursion Depth (-el):

Use -el (end level) to control exactly how deep reny recurses. For example, to add an index only to files inside immediate subdirectories (depth 1), while ignoring deeper nested folders:

reny -r -el 1 index

Visualize with Git info (--git):

To visually inspect changes in a repository, reny will automatically bubble up file modifications to their parent directories, even with shallow directory levels.

Add a sequential index to all .txt files recursively:

reny -r -in '*.txt' index

Pad existing numbers with leading zeros (e.g., 2 kms.png becomes 02 kms.png):

reny pad -md 2

Regex Replace: Change spaces to underscores in all filenames:

reny replace -fs ' ' -rs '_'

Advanced Operations & Virtual Views

Flattening nested directories: Collapse all sub-directories and bring their files up to the current folder level:

reny flatten

Organize by File Type: Move files into sub-directories grouped by their file extension (e.g., png/, pdf/):

reny organize -b type

Virtual Views (Dry-Run Preview): Preview how files would look if organized by year and month, without actually moving any files on your drive:

reny --color 0 print -b date --date-format "%Y/%m"

Virtual view by date:
~/Downloads
  |- 2025/
    |- 01/
      |- document.pdf
    |- 02/
      |- image.png

^💡 The --color 0 parameter is used to disable terminal colors

Ignore Files (.renyignore)

By default, reny will automatically detect a .renyignore file in your target directory (falling back to a global ~/.renyignore if none is found) to cleanly exclude specific directories from processing.

You can also explicitly pass any file, like a standard .gitignore, to automatically parse and exclude those paths from the output.

reny -r -el 2 -ig .gitignore --color 0

~/Desktop/_Dev/reny
  |- LICENSE
  |- pyproject.toml
  |- README.md
  |- setup.py
  |->/reny
    |- __init__.py
    |->/cli
      |- __init__.py
      |-/base
      |-/renamer
    |->/commons
      |- __init__.py
      |- chainedhandler.py
      |- descriptors.py
      |- progressbar.py
      |- taskprocessor.py
      |- utils.py
    |->/fstools
      |- __init__.py
      |- dirtools.py
      |- fsutils.py
      |- rename.py
      |- virtual_organizer.py
      |- walker.py
      |-/builders
  |->/tests
    |- __init__.py
    |->/base
      |- __init__.py
      |- test_base.py
    |->/commons
      |- __init__.py
      |- test_commons.py
      |- test_ignore.py
    |->/fs
      |- __init__.py
      |- test_fs_base.py
      |- test_fs_organize.py
      |- test_fsutils.py
      |-/data
28 files, 12 folders

Real-World Scenario: Downloads Cleanup

A safe, two-step workflow to tame a chaotic downloads folder by grouping files by their extension and sorting them by size to see what's eating up your disk space.

Step 1: Preview the cleanup with size statistics (Shows you the largest file categories first, without moving any files)

reny -s sd print -b type -ss

Step 2: Commit the organization (Actually moves the files into their respective subdirectories)

reny organize -b type

Documentation & Tutorials

Although reny is a standalone project, its core organizing logic is inherited directly from batchmp. You can find detailed tutorials and deep-dives on how to master its capabilities in the original blog posts:

• Renamer Organize & Virtual Views – Highly recommended reading for mastering virtual directory views
• BatchMP Tools Tutorial, Part II: renaming files with renamer
• Practical BatchMP Series

Usage

Run reny --help to see all available filesystem operations!

Development

To set up the project for development:

1. Clone the repository and navigate into it:

   git clone https://github.com/akpw/reny.git
   cd reny
   

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install the project in editable mode along with testing dependencies:

   pip install -e ".[test]"
   

Running Tests

The project uses pytest for its test suite. Because reny performs real filesystem operations, the tests are designed to dynamically create and clean up safe temporary sandbox folders during execution.

To run the full test suite:

pytest -v --tb=short tests/

To run a specific test file:

pytest tests/fs/test_fs_organize.py