Refactoring of readme

This commit is contained in:
Kirill Kalikin 2026-11-14 17:22:13 +07:00
parent de4555b3ba
commit b3c659373e
1 changed files with 113 additions and 50 deletions

159
README.md
View File

@ -1,65 +1,128 @@
# Cleaner # Cleaner
Утилита на Go для очистки курсов скачанных с пиратских сайтов от спама и рекламы: Go CLI-утилита для нормализации имён файлов и папок путём удаления спам-ключевых слов и удаления известных мусорных файлов.
- Удаляет ненужный файлы по вашему списку.
- Убирает из названий файлов и папок названия сервисов и ненужны подписи.
- Вы можете самостоятельно добавить новые ключевые слова и названия файлов.
## Обзор
## Особенности архитектуры Инструмент рекурсивно обходит целевую директорию, удаляет заданные ключевые слова из имён файлов и папок и удаляет файлы, совпадающие с точным списком мусора, например служебные метаданные ОС или кэши превью.
В проекте используется стандартный пакет **`embed`** (Go 1.16+) для встраивания текстовых ресурсов (словаря `words.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
```
Если файлы отсутствуют, программа создаёт их на основе встроенных шаблонов и продолжает работу.
## Флаги CLI
```bash
./cleaner --help
```
Доступные параметры:
- `--dir` — корневая папка для обработки;
- `--words-file` — список ключевых слов для удаления из имён;
- `--trash-file` — список точных имён файлов для удаления;
- `--dry-run` — показать действия без изменения файлов;
- `-i` / `--ignore-case` — включить поиск без учёта регистра (по умолчанию);
- `--version` — вывести метаданные сборки.
## Формат словарей
### `words.txt`
```text
# комментарии начинаются с #
# по одному слову на строку
[SWBAND.CO]
```
Эти значения будут удаляться из имён файлов и папок.
### `trash.txt`
```text
# точные имена файлов для удаления
# комментарии начинаются с #
.DS_Store
Thumbs.db
desktop.ini
```
Совпадающие имена будут удалены с диска.
## Структура проекта ## Структура проекта
```text ```text
. .
├── go.mod # Файл описания модуля и зависимостей
├── cmd/ ├── cmd/
│ └── cleaner/ │ └── cleaner/
│ └── main.go # Точка входа в приложение (если применимо) │ └── main.go
└── internal/ # Приватный код приложения ├── internal/
├── keywords/ # Бизнес-логика работы со словами │ ├── keywords/
| ├── templates/ # Директория со статическими ресурсами и шаблонами │ │ ├── templates/
| │ ├── words.txt # Словарь удаляемых слов из названий файлов и папок │ │ │ ├── words.txt
| │ └── trash.txt # Словарь имен удаляемых файлов │ │ │ └── trash.txt
| └── keywords.go # Пакет работы с ключевыми словами │ │ └── keywords.go
└── renamer/ │ └── renamer/
└── renamer.go # Пакет переименовывателя │ └── renamer.go
├── go.mod
├── README.md
├── Makefile
└── bin/
└── cleaner
``` ```
## Требования ## Рекомендации по безопасной работе
* **Go** версии 1.16 или выше (рекомендуется актуальная стабильная версия). - сначала проверяйте запуск на копии данных;
- используйте `--dry-run` перед массовой очисткой;
- храните пользовательские словари под контролем версий;
- проверяйте списки ключевых слов перед запуском на больших архивах;
- не указывайте `--dir` на важные системные папки.
## Установка и запуск ## Примечания
1. **Клонируйте репозиторий:** Словари по умолчанию встроены в бинарник через Go `embed`, но приложение создаёт локальные файлы, если они отсутствуют. Это сохраняет бинарник самодостаточным и одновременно позволяет использовать пользовательские словари.
```bash
git clone https://github.com
cd ваш-проект
```
2. **Загрузите зависимости (если есть):**
```bash
go mod download
```
3. **Запустите проект:**
```bash
go run .
```
## Сборка
Для компиляции в единый бинарный файл (все файлы из `templates/` будут автоматически вшиты внутрь):
```bash
go build -o app .
```
После сборки вы можете перенести файл `app` на любой сервер — папка `templates/` рядом с ним больше не потребуется.
## Работа с ресурсами (`templates/`)
Поскольку в Go директива `//go:embed` запрещает обращение к родительским директориям (`../`), доступ к файлам из вложенных пакетов (таких как `internal/keywords`) реализован через пакет `templates`.