cleaner/README.md

147 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Cleaner
Go CLI-утилита для нормализации имён файлов и папок путём удаления спам-ключевых слов и удаления известных мусорных файлов.
## Обзор
Инструмент рекурсивно обходит целевую директорию, удаляет заданные ключевые слова из имён файлов и папок и удаляет файлы, совпадающие с точным списком мусора, например служебные метаданные ОС или кэши превью.
Подходит для задач очистки, когда в загруженных материалах встречаются рекламные подписи, названия сервисов или повторяющиеся служебные строки в именах файлов.
## Возможности
- рекурсивный обход целевой директории;
- очистка имён файлов и папок по ключевым словам;
- поиск без учёта регистра по умолчанию;
- удаление точных имён файлов по списку мусора;
- нормализация повторяющихся расширений через `replacements.txt`;
- безопасный режим предпросмотра через `--dry-run`;
- автоматическое создание файлов словарей при отсутствии.
## Требования
- Go 1.22+
## Быстрый старт
### Сборка
```bash
go build -o cleaner ./cmd/cleaner
```
### Предпросмотр без изменения файлов
```bash
./cleaner --dir /path/to/content --dry-run
```
### Применение изменений
```bash
./cleaner --dir /path/to/content
```
## Конфигурация
По умолчанию программа читает словари из текущей рабочей директории. Пути можно переопределить явно:
```bash
./cleaner \
--dir ./content \
--words-file ./config/words.txt \
--trash-file ./config/trash.txt \
--replace-file ./config/replacements.txt
```
Если файлы отсутствуют, программа создаёт их на основе встроенных шаблонов и продолжает работу.
## Флаги CLI
```bash
./cleaner --help
```
Доступные параметры:
- `--dir` — корневая папка для обработки;
- `--words-file` — список ключевых слов для удаления из имён;
- `--trash-file` — список точных имён файлов для удаления;
- `--replace-file` — список правил замены вида `old -> new`;
- `--dry-run` — показать действия без изменения файлов;
- `-i` / `--ignore-case` — включить поиск без учёта регистра (по умолчанию);
- `--version` — вывести метаданные сборки.
## Формат словарей
### `words.txt`
```text
# комментарии начинаются с #
# по одному слову на строку
[SWBAND.CO]
```
Эти значения будут удаляться из имён файлов и папок.
### `trash.txt`
```text
# точные имена файлов для удаления
# комментарии начинаются с #
.DS_Store
Thumbs.db
desktop.ini
```
Совпадающие имена будут удалены с диска.
### `replacements.txt`
```text
# правила замены вида old -> new
# комментарии начинаются с #
.mp4.mp4 -> .mp4
.wmv.mp4 -> .mp4
```
Это удобно для исправления повторяющихся расширений и типовых мусорных суффиксов, например:
- `movie.mp4.mp4` -> `movie.mp4`
- `movie.wmv.mp4` -> `movie.mp4`
## Структура проекта
```text
.
├── cmd/
│ └── cleaner/
│ └── main.go
├── internal/
│ ├── keywords/
│ │ ├── templates/
│ │ │ ├── words.txt
│ │ │ ├── trash.txt
│ │ │ └── replacements.txt
│ │ └── keywords.go
│ └── renamer/
│ └── renamer.go
├── go.mod
├── README.md
├── Makefile
└── bin/
└── cleaner
```
## Рекомендации по безопасной работе
- сначала проверяйте запуск на копии данных;
- используйте `--dry-run` перед массовой очисткой;
- храните пользовательские словари под контролем версий;
- проверяйте списки ключевых слов перед запуском на больших архивах;
- не указывайте `--dir` на важные системные папки.
## Примечания
Словари по умолчанию встроены в бинарник через Go `embed`, но приложение создаёт локальные файлы, если они отсутствуют. Это сохраняет бинарник самодостаточным и одновременно позволяет использовать пользовательские словари.