Dirganise

A CLI tool written in Python that organizes a messy folder by file type.

Features

• Automatic sorting — moves files into categories: Images, Videos, Audio, Documents, Code, Compressed, Installers, Fonts, and Others
• Custom rules — define your own extension-to-folder mappings via a JSON file
• Dry-run mode — preview what would happen without touching the filesystem
• Undo — revert the last organization with a single command
• Conflict handling — appends a timestamp automatically if a file with the same name already exists

Installation

[!TIP] Compatibility: This program can run in every platform that supports Python 3.10+

pip install dirganise

Or clone and install locally:

git clone https://github.com/yourusername/dirganise.git
cd dirganise
pip install -e .

Usage

# Organize a folder
dirganise /path/to/folder

# Preview changes without moving anything
dirganise --dry-run

# Undo the last organization
dirganise --undo

# Use custom rules from a JSON file
dirganise --rules custom_rules.json

Options

Default Organization Rules

Custom Rules

Create a .json file mapping extensions to folder names:

{
  ".psd": "Design",
  ".ai": "Design",
  ".blend": "3D",
  ".csv": "Data"
}

Custom rules override the defaults for any matching extension. All other defaults remain active.

dirganise ~/Downloads --rules my_rules.json

Undo

After every organization, dirganise saves a log file (.dirganise_op.json) in the target folder. Use it to restore the original state:

dirganise /path/to/folder --undo

The log file is automatically deleted after a successful undo.

Example

$ dirganise ~/Downloads --dry-run

 dirganise  >  /home/user/Downloads

Images/
  photo_2024.jpg
  screenshot.png

Documents/
  report.pdf
  notes.txt

Code/
  script.py

Total files to move: 5

[Preview] No changes have been made to the file system.

Development

git clone https://github.com/yourusername/dirganise.git
cd dirganise
pip install -e .

Contributions, issues, and feature requests are highly welcome. Feel free to open an issue or submit a pull request.

License

MIT © 2026