file-singlify (Fichiers uniques – Scan de déduplication)
Ce que fait ce skill
Analyse un disque / répertoire / point de montage pour trouver les fichiers en double et répertoires en double créés par des copies, sauvegardes, synchronisations ou migrations multiples. Il génère un plan de « mise en unique » : on conserve une copie canonique par groupe, les autres étant marquées comme références / à supprimer / à remplacer par un lien, avec une estimation de l’espace économisable.
Principe fondamental : lecture seule, dry-run uniquement. Aucune suppression, déplacement, écrasement, création de lien dur/symbolique n’est effectuée directement. Toute action destructive nécessite d’abord un rapport, puis une confirmation explicite de l’utilisateur. Le script lui-même reste toujours en lecture seule — --action-mode ne modifie que l’étiquette suggested_action dans le rapport, sans exécuter d’action.
Quand l’utiliser
- L’utilisateur veut scanner un disque / dossier / un ensemble de dossiers pour trouver les « fichiers identiques », « dossiers en double », « sauvegardes redondantes », « copies multiples »
- L’utilisateur souhaite conserver un fichier original, générer une table de correspondance, des suggestions de suppression, des liens durs/symboliques, un rapport de déduplication, une estimation de l’espace économisé
- Mots-clés : déduplication / mise en unique / répertoire en double / dedup / copie canonique / nettoyage de stockage
Ne convient pas : Si l’utilisateur demande une analyse de contenu de fichier, une compression, ou un classement non lié à la détection de doublons.
Flux de travail par défaut
- Vérification du chemin et des permissions — Vérifier que l’environnement peut accéder à
root_path. S’il est accessible, exécuter le script ; sinon, demander à l’utilisateur de fournir une liste des dossiers / un arborescence / une archive / un chemin monté accessible. Ne jamais inventer de résultats d’analyse. - Exécuter le script (directory-first) — Trouver les redondances d’abord par la cohérence des répertoires, puis confirmer avec le hachage des fichiers. Un répertoire entier copié en double est la plus grande source de gaspillage d’espace ; afficher d’abord les résultats au niveau des répertoires.
- Lire la sortie du script, la présenter à l’utilisateur — Prioriser les groupes de répertoires en double, puis les groupes de fichiers en double, la table de correspondance canonique, l’espace économisable, et les éléments à risque. Pour les éléments marqués
uncertain/manual_reviewpar le script, demander clarification à l’utilisateur, ne pas décider à sa place. - Donner les 4 premières commandes recommandées — Le script génère jusqu’à 4 commandes recommandées selon l’OS/shell actuel (sécurité d’abord : verify → quarantine → hardlink → delete), voir section 10 du rapport /
recommended_commandsdu JSON. Les présenter à l’utilisateur en adaptant la syntaxe à son véritable OS et shell ; le script détecte automatiquement, si nécessaire utiliser--target-os/--target-shellpour forcer. Ne donner que les commandes, ne pas les exécuter. Les commandes utilisent des chemins d’exemples représentatifs ; il faut les appliquer ligne par ligne à la table de correspondance. - Reconfirmation avant action destructive — Si l’utilisateur veut vraiment supprimer / remplacer les liens, reformuler le plan et demander une confirmation explicite ; le script n’exécute rien, c’est à l’utilisateur de le faire ou de donner une autorisation séparée.
Quand exécuter le script
Exécuter le script lorsque l’environnement peut lire root_path directement. Si on dispose seulement d’une liste ou d’un arbre, analyser manuellement avec la même logique (structure de répertoires identique → taille de fichier identique → hachage du contenu) et préciser clairement « hachage non effectué ».
python3 scripts/scan_file_singlify.py <root_path> \
--scan-mode directory-first \ # ou file-only
--hash-algorithm md5 \ # md5 | sha256 | both (strictement both)
--output-format markdown \ # markdown | json | csv
--action-mode report-only \ # report-only|link-plan|delete-plan|hardlink-plan|symlink-plan
--exclude-patterns ".git,node_modules,cache,temp" \
--include-patterns "*.jpg,*.mp4" \
--min-file-size 1024 \
--prefer "/Volumes/Primary" \ # préférer ce chemin pour la copie canonique
--target-os auto \ # auto|macos|linux|windows (utilisé pour les commandes top-4)
--target-shell auto # auto|bash|zsh|fish|powershell|cmd
Pour les paramètres complets et les règles de détection, voir l’aide du script (--help), references/matching-rules.md et references/safety-rules.md.
Format de sortie
Le script produit un rapport structuré contenant : zone scannée, paramètres, nombre total de fichiers/répertoires/capacité, groupes de répertoires en double, répertoires probablement en double, groupes de fichiers en double (confirmés par hachage), estimation de l’espace économisable, table de correspondance canonique, les 4 commandes recommandées (adaptées à l’OS/shell), risques et éléments incertains, suggestions pour la suite. Le format markdown est lisibles par l’humain, json pour les programmes (inclut recommended_commands), csv est la table de correspondance duplicate → canonique.
Chaque ligne de correspondance contient confidence (confirmed / uncertain) et suggested_action (keep / delete_duplicate / replace_with_hardlink / replace_with_symlink / create_manifest_reference / manual_review).
Limites de sécurité
- Par défaut, ne jamais supprimer de fichiers ni créer de liens durs/symboliques automatiquement. Le script est en lecture seule.
- Le simple fait d’avoir le même nom / taille / mtime ne suffit pas à déclarer un doublon — ce ne sont que des candidats ; la conclusion finale doit être basée sur un hachage (même taille + même hash).
- Être particulièrement prudent avec les répertoires système, cachés, d’applications, dépôts Git, bases de données, bibliothèques photos, dossiers de synchronisation cloud.
- Ne pas suivre les liens symboliques, ne pas récurser ; en cas de boucle de répertoires, arrêter la récursion et le signaler.
- Fichiers inaccessibles / de taille zéro / spéciaux / déjà liés par un lien dur → les marquer et les sauter, les classer dans « ignorés / incertains », ne pas les considérer comme des doublons certains.
- Si la copie canonique ne peut pas être déterminée, lister les candidats et demander la confirmation à l’utilisateur, ne pas décider seul.
Erreurs courantes
| Erreur | Correction |
|---|---|
| « Simuler » un scan sans avoir vérifié l’accès au chemin | Vérifier l’accès d’abord ; si impossible, demander la liste ; ne jamais inventer de résultats |
| Déclarer un doublon uniquement sur le nom/taille/date | Ne les considérer que comme candidats ; confirmer avec le hachage |
| Hacher tous les fichiers immédiatement | D’abord filtrer par cohérence de répertoire, puis hacher les candidats |
| Suggérer la suppression/remplacement avant d’avoir produit le rapport | D’abord produire le rapport, puis attendre une confirmation explicite ; le script n’exécute aucune action destructive |
Décider pour l’utilisateur des éléments uncertain | Présenter les éléments incertains comme des questions à l’utilisateur |