🗂️ mimedy

Range un dossier en désordre selon le vrai type de chaque fichier, pas selon son extension.
Tidies up a messy folder by each file's real type, not by its extension.

mimedy = MIME + tidy (ranger) : le type MIME de chaque fichier décide de sa place.
mimedy = MIME + tidy: each file's MIME type decides where it belongs.

Français · English

🇫🇷 Français

Pourquoi ?

Un dossier Téléchargements finit toujours par ressembler à ça : des PDF, des captures d'écran, des archives, un .json exporté un jour, un fichier sans extension dont personne ne se souvient…

La plupart des outils de rangement se fient à l'extension. Or une extension peut mentir, manquer ou être fausse. mimedy utilise Magika, le modèle de deep learning de Google qui identifie un fichier à partir de son contenu, pour décider où il doit aller.

$ mimedy ~/Downloads
[INFO] Loaded config from /Users/me/.config/mimedy/config.yaml
[INFO] Organizing /Users/me/Downloads
[INFO] 'export.csv' → Data/
[INFO] 'holidays.jpg' → Photos/
[INFO] 'invoice' → PDF/
[INFO] 'report.pdf' → PDF/report (1).pdf
[INFO] 'script.py' → Python/
[WARNING] Skipped 'locked.txt': Magika could not read the file (permission_error)
[INFO] 5 files to move into 4 folders, 1 skipped
Move 5 files? [y/N]: y
[INFO] Done: 5 moved, 0 failed

Fonctionnalités

• 🧠 Détection par le contenu : Magika reconnaît plus de 200 types de fichiers, même renommés ou sans extension.
• 🪜 Règles en cascade : fichiers cachés, fichiers volumineux, extensions, types MIME, puis le groupe Magika en dernier recours.
• 📋 Plan puis confirmation : tous les déplacements sont affichés avant d'être effectués, et rien ne bouge sans votre accord. --dry-run s'arrête au plan.
• 🧯 Robuste : un fichier illisible ou verrouillé est signalé et ignoré, sans interrompre le rangement.
• 🛡️ Aucun écrasement : si photo.jpg existe déjà, le nouveau fichier devient photo (1).jpg.
• 🐛 Mode --verbose : indique pour chaque fichier la règle qui a décidé de sa destination.
• ⚙️ Configuration YAML simple, entièrement facultative.

Installation

Prérequis : Python 3.10+ et uv.

git clone https://github.com/ochapeau/mimedy.git
cd mimedy
uv sync

Utilisation

💡 mimedy affiche toujours le plan complet et demande confirmation avant de déplacer quoi que ce soit.

# Afficher le plan, puis confirmer
uv run mimedy ~/Downloads

# Afficher le plan seulement
uv run mimedy ~/Downloads --dry-run

# Sans confirmation, par exemple dans un script
uv run mimedy ~/Downloads --yes --config my-config.yaml

# Comprendre pourquoi un fichier va à tel endroit
uv run mimedy ~/Downloads --dry-run --verbose

Seuls les fichiers situés directement dans le dossier sont traités. Les sous-dossiers existants ne sont pas touchés, ce qui permet de relancer l'outil sans risque.

Configuration

Sans --config, mimedy lit le fichier de configuration personnel, s'il existe :

S'il n'existe pas, les valeurs par défaut sont utilisées. Un fichier passé avec --config doit en revanche exister. mimedy --help affiche l'emplacement exact sur votre machine.

Pour démarrer, créez une configuration d'exemple commentée, puis adaptez-la :

mimedy --init-config
# Created config file: /Users/me/.config/mimedy/config.yaml

hidden: "Hidden"            # fichiers commençant par '.'

large_files:
  threshold_mb: 500         # en Mo décimaux, comme le Finder ou l'Explorateur
  target_dir: "Large"

extensions:                 # correspondance exacte sur l'extension
  .blend: "Blender"
  .csv: "Data"

mimetypes:                  # type MIME détecté par Magika
  application/pdf: "PDF"
  image/jpeg: "Photos"

Toutes les clés sont facultatives : celles qui manquent reprennent leur valeur par défaut. Les destinations peuvent contenir des sous-dossiers ("Code/Python"). config.example.yaml, le fichier copié par --init-config, contient un exemple complet et commenté.

Comment un fichier est-il classé ?

Les règles sont évaluées dans cet ordre ; la première qui correspond l'emporte :

Les règles 1 à 3 ne lisent pas le contenu des fichiers : elles sont instantanées. Magika n'est appelé que si elles ne suffisent pas.

Structure du projet

mimedy/
├── pyproject.toml
├── src/mimedy/
│   ├── main.py              # Point d'entrée de la CLI (Typer)
│   ├── config.py            # Chargement et validation de la configuration
│   ├── config.example.yaml  # Configuration d'exemple commentée
│   ├── organizer.py         # Règles de classement, planification et déplacements
│   └── errors.py            # Exceptions du projet
└── tests/                   # Tests pytest (configuration, règles, plan, CLI)

Développement

Le code est vérifié par Ruff (lint et formatage) à chaque commit, et testé avec pytest. L'intégration continue lance les deux à chaque push, sur Python 3.10 à 3.13.

uv run pre-commit install   # vérifications automatiques à chaque commit
uv run pytest               # lancer les tests

Feuille de route

• Configuration typée et validée
• Configuration globale dans ~/.config/mimedy/
• Tests automatisés et intégration continue
• Publication sur PyPI (uv tool install mimedy)
• Interface en terminal (TUI), en option

Licence

Distribué sous licence MIT. Voir LICENSE.

🇬🇧 English

Why?

A Downloads folder always ends up looking the same: PDFs, screenshots, archives, a .json exported at some point, a file with no extension that nobody remembers…

Most organizing tools trust file extensions. But an extension can lie, be missing, or simply be wrong. mimedy uses Magika, Google's deep learning model that identifies a file from its content, to decide where it belongs.

$ mimedy ~/Downloads
[INFO] Loaded config from /Users/me/.config/mimedy/config.yaml
[INFO] Organizing /Users/me/Downloads
[INFO] 'export.csv' → Data/
[INFO] 'holidays.jpg' → Photos/
[INFO] 'invoice' → PDF/
[INFO] 'report.pdf' → PDF/report (1).pdf
[INFO] 'script.py' → Python/
[WARNING] Skipped 'locked.txt': Magika could not read the file (permission_error)
[INFO] 5 files to move into 4 folders, 1 skipped
Move 5 files? [y/N]: y
[INFO] Done: 5 moved, 0 failed

Features

• 🧠 Content-based detection: Magika recognizes over 200 file types, even when renamed or missing an extension.
• 🪜 Cascading rules: hidden files, large files, extensions, MIME types, then the Magika group as a fallback.
• 📋 Plan, then confirm: every move is shown before it happens, and nothing moves without your approval. --dry-run stops at the plan.
• 🧯 Robust: an unreadable or locked file is reported and skipped, without stopping the run.
• 🛡️ Never overwrites: if photo.jpg already exists, the new file becomes photo (1).jpg.
• 🐛 --verbose mode: shows which rule decided each file's destination.
• ⚙️ Simple YAML configuration, entirely optional.

Installation

Requirements: Python 3.10+ and uv.

git clone https://github.com/ochapeau/mimedy.git
cd mimedy
uv sync

Usage

💡 mimedy always shows the full plan and asks for confirmation before moving anything.

# Show the plan, then confirm
uv run mimedy ~/Downloads

# Only show the plan
uv run mimedy ~/Downloads --dry-run

# No confirmation, e.g. in a script
uv run mimedy ~/Downloads --yes --config my-config.yaml

# Understand why a file goes where it goes
uv run mimedy ~/Downloads --dry-run --verbose

Only files directly inside the folder are processed. Existing subfolders are left untouched, so the tool can safely be run again.

Configuration

Without --config, mimedy reads your personal configuration file, if it exists:

If it doesn't exist, the defaults are used. A file passed with --config, however, must exist. mimedy --help shows the exact location on your machine.

To get started, create a commented example config, then adapt it:

mimedy --init-config
# Created config file: /Users/me/.config/mimedy/config.yaml

hidden: "Hidden"            # files starting with '.'

large_files:
  threshold_mb: 500         # decimal MB, like Finder or Explorer
  target_dir: "Large"

extensions:                 # exact extension match
  .blend: "Blender"
  .csv: "Data"

mimetypes:                  # MIME type detected by Magika
  application/pdf: "PDF"
  image/jpeg: "Photos"

Every key is optional: missing ones fall back to their default value. Destinations may include subfolders ("Code/Python"). See config.example.yaml, the file copied by --init-config, for a complete, commented example.

How is a file classified?

Rules are evaluated in this order; the first match wins:

Rules 1 to 3 don't read file contents, so they are instant. Magika only runs when they aren't enough.

Project structure

mimedy/
├── pyproject.toml
├── src/mimedy/
│   ├── main.py              # CLI entry point (Typer)
│   ├── config.py            # Configuration loading and validation
│   ├── config.example.yaml  # Commented example configuration
│   ├── organizer.py         # Classification rules, planning and moves
│   └── errors.py            # Project exceptions
└── tests/                   # pytest tests (configuration, rules, plan, CLI)

Development

Code is checked by Ruff (linting and formatting) on every commit, and tested with pytest. Continuous integration runs both on every push, on Python 3.10 to 3.13.

uv run pre-commit install   # automatic checks on every commit
uv run pytest               # run the tests

Roadmap

• Typed, validated configuration
• Global configuration in ~/.config/mimedy/
• Automated tests and continuous integration
• Publish on PyPI (uv tool install mimedy)
• Optional terminal interface (TUI)

License

Released under the MIT License. See LICENSE.