Reny

Reny is a lightweight but powerful filesystem visualizer, batch renamer and organization CLI tool. It visualizes complex directory structures and generates virtual views, alongside handling standard renaming tasks (regex replace, padding, appending text/dates) and advanced operations like multi-level indexing and folder flattening. By default, Reny safely visualizes all targeted changes and requires confirmation before modifying the filesystem.

Background

reny was originally created as the renamer component inside the larger batchmp suite. It was spun off to provide a pure-filesystem organizing tool without media dependencies.

Blogs

• The Next Chapter in File Organization: Introducing Reny

Installation

Homebrew:

brew tap akpw/tap
brew install reny

Alternatively, install from the PyPI package using standard pip:

pip install reny

Or for a clean pip installation with isolated dependencies via pipx:

pipx install reny

Features

• Filesystem Visualization: Clean, customizable views of files and folders
• Recursion & Leveling: Precise recursion control with end_level / start_level parameters
• Filtering: Pinpoint targeting using include/exclude patterns and .renyignore integration
• Color Outputs: Rich terminal highlighting for different file types, grouping extensions visually
• Virtual Views: Preview how a directory structure would look when reorganised by type or date without moving or changing anything
• Organization: Safely re-organizes directory structure based on type or date attributes
• Git Integration: Automatically detects and displays file and directory modification statuses using --git (-g), filters to show only modified files (-go), tracked files (-gt), untracked files (-ngt), or explicitly ignored files (-gi).
• Dry-Run by Default: reny always visualizes targeted changes and asks for confirmation before actually touching files / folders
• 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

Usage & Examples

1. Configuration File (config.toml)

Since reny comes with many options, it supports setting default configurations via a TOML file to make organizing and using them much easier.

The global configuration file is located at ~/.config/reny/config.toml, but you can also use a local ./.reny.toml on a per-directory basis.

Generate a fully-commented default configuration template (or open an existing one in your $EDITOR):

reny config            # Generates or opens ~/.config/reny/config.toml
reny config --local    # Generates or opens ./.reny.toml in current directory

Any options specified on the command line automatically override settings in the config file.

2. Ignore File Management (reny ignore)

reny supports generating and managing ignore template files to exclude unwanted files or directories from operations:

reny ignore            # Generates or opens ./.renyignore in current directory
reny ignore -gl        # Generates or opens ~/.renyignore globally

3. Basic Visualization (No flags)

Print the current directory structure:

reny

/../_Dev/reny
  |- LICENSE
  |- pyproject.toml
  |- README.md
  |-/reny
  |-/tests
3 files, 2 folders

4. Recursion Control (-r/--recursive, -sl/--start-level, -el/--end-level)

Easily adjust how deep reny prints or operates. For example, to view files and directories exactly 1 level deep:

reny -el 1

/../_Dev/reny
  |- LICENSE
  |- pyproject.toml
  |- README.md
  |->/reny
    |-/cli
    |-/commons
    |-/fstools
  |->/tests
    |-/base
    |-/commons
    |-/fs
3 files, 8 folders

5. Filtering & Ignore Files (-in/--include, -ex/--exclude, -ig/--ignore-file)

By default, reny automatically excludes hidden files and directories (like .git and .venv). Additional filters can be set via -in / -ex parameters, or via a .renyignore file in the target directory or globally in ~/.renyignore. reny also supports custom ignore files, like a standard .gitignore:

reny -el 1 -ig .gitignore 

/../_Dev/reny
  |- LICENSE
  |- pyproject.toml
  |- README.md 
  |->/reny
    |- __init__.py
    |-/cli
    |-/commons
    |-/fstools
  |->/tests
    |- __init__.py
    |-/base
    |-/commons
    |-/fs
5 files, 8 folders

6. Virtual Views & Organization (-b/--by, -ss/--show-size, -s/--sort)

Preview how a chaotic downloads folder would look if organized by file type, sorted by size descending (you can also sort by date with da/dd), without actually moving anything:

reny -b type -s sd -ss

Virtual view by type:
~/Downloads
  |->/mp4
    |-  1.2GB vacation_movie.mp4
  |->/mov
    |-  450MB screen_recording.mov
  |->/pdf
    |-  2.1MB tax_return.pdf
    |-  450KB receipt.pdf
  |->/png
    |-  1.2MB screenshot.png
5 files, 4 folders
Total selected entries size: 1.6GB

To actually commit this organization and move the files, simply use the organize command. As always, reny will show a preview and ask for confirmation before actually making any changes:

reny organize -b type

7. Git Integration (-g/--git, -go/--git-only, -gt/--git-tracked, -ngt/--not-git-tracked, -gi/--git-ignored)

Visually inspect changes in a repository. reny automatically bubbles up file modifications to their parent directories.

reny -el 1 -ig .gitignore --git

/../_Dev/reny
  |- LICENSE
  |- pyproject.toml
  |- README.md [ M]
  |->/reny [* ]
    |- __init__.py
    |-/cli [* ]
    |-/commons
    |-/fstools
  |->/tests
    |- __init__.py
    |-/base
    |-/commons
    |-/fs
5 files, 8 folders

To exclusively view files with git modifications (and their parent directories), hiding all unmodified clutter (similar to git status), use the --git-only (or -go) flag:

reny -el 1 -ig .gitignore -go

/../_Dev/reny
  |- README.md [ M]
  |->/reny [* ]
    |-/cli [* ]
1 file, 2 folders

Similarly, you can use the --git-tracked (or -gt) flag to filter the view so it exclusively shows files that are already tracked by Git, completely ignoring untracked files and directories.

Complementary to this, the --not-git-tracked (-ngt) flag displays only files that are currently untracked, and --git-ignored (-gi) reveals all explicitly ignored files (e.g., build artifacts, __pycache__, or .DS_Store hidden by .gitignore). Note that both -ngt and -gi bypass reny's internal .renyignore to ensure you see the true, unvarnished state of your Git repository.

8. Advanced Batch Renaming (Commands)

When you are ready to modify your files, reny operates purely as a dry-run by default. It safely visualizes all targeted changes and asks for confirmation before any files are moved or renamed.

reny supports a variety of targeted commands for bulk renaming:

Indexing (index, -sq/--sequential, -bd/--by-directory)

Add an index to all .txt files recursively. By default, reny performs multi-level indexing (restarting the count inside each respective directory):

reny -r -in '*.txt' index

To index files continuously across all nested directories, use the -sq flag. Alternatively, use -bd to append the directory's index instead of the file's index:

reny -r -in '*.txt' index -sq

Zero-Padding (pad, -md/--min-digits)

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

reny pad -md 2

Flattening (flatten, -tl/--target-level)

Safely collapse nested directory structures into a single folder (target level 1):

reny flatten -tl 1

Delete (delete)

Safely batch-delete files. When combined with filters, it can e.g. clean up a messy downloads folder or prepare a project for a clean build (e.g., deleting dist, __pycache__, and .egg-info directories). Paired with -gi, you can preview and instantly wipe all git-ignored files:

reny -gi -ex .venv delete -id

The following files / folders will be deleted
/reny
  |-  6KB .DS_Store
  |->/ 3.4MB .mypy_cache
    |-  0KB .gitignore
    |-  0KB CACHEDIR.TAG
    |-/ 3.4MB 3.14
  |->/ 5KB .pytest_cache
    |-  0KB .gitignore
    |-  0KB CACHEDIR.TAG
    |-  0KB README.md
  |->/ 103KB dist
    |-  56KB reny-1.0.12-py3-none-any.whl
    |-  47KB reny-1.0.12.tar.gz
  |->/ 13KB reny.egg-info
    |-  0KB dependency_links.txt
    |-  0KB entry_points.txt
    |-  11KB PKG-INFO
    |-  0KB requires.txt
    |-  1KB SOURCES.txt
    |-  0KB top_level.txt
14 files, 5 folders
Total selected entries size: 3.5MB

Regex Replace (replace, -fs/--find-string, -rs/--replace-string)

Change spaces to underscores in all filenames:

reny replace -fs ' ' -rs '_'

Manually pad single-digit filenames with a leading zero (an alternative to the pad command using capture groups):

reny replace -fs '^(\d)$' -rs '0\1'

Delete the first 3 characters from every filename:

reny replace -fs '^.{1,3}' -rs ''

Documentation

For a deep dive:

• The Next Chapter in File Organization: Introducing Reny

While reny is standalone, its core logic inherits from batchmp. You can find historical context and tutorials in the original blog posts:

• Renamer Organize & Virtual Views
• BatchMP Tools Tutorial

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

To run the full test suite (which dynamically creates and cleans up temporary sandboxes):

pytest -v --tb=short tests/