# HSRename

A **native Linux** GUI for mass renaming files. Inspired by [Bulk Rename Utility](https://www.bulkrenameutility.co.uk/#features) (Windows). Rename hundreds of media files with flexible rules, **preview before applying**, and support for **episode renumbering** without losing episode titles.

## Features

- **GUI** – Structure renames with rule panels; no command line needed.
- **Preview** – See “Original → New name” for every file before committing.
- **Multiple rules** – Combine rules (order: Replace → Regex → Insert → Remove → Case → Numbering → Episode renumber → Prefix/Suffix). Enable only the rules you need.
- **Episode renumbering** – Replace episode numbers (e.g. `S01E05 - Title` → `S01E01 - Title`) while keeping season and title. Multi-episode files like `S01E05-E06` become `S01E01-E02` (range length preserved). Start, step, and zero-padding configurable.
- **Replace / Regex** – Plain text find/replace or full regex with capture groups.
- **Insert / Remove** – Insert text at start/end/position; remove text, digits, or first/last N characters.
- **Case** – Title Case, UPPER, lower, Sentence case.
- **Numbering** – Add a running number (prefix/suffix/insert) with start, step, and padding.
- **Prefix / Suffix** – Add fixed text to the beginning or end of every name.
- **CSV mapping** – Rename from a CSV with columns **Original Name** and **Target Name** (one row per file; lookup by current filename).
- **Safe renames** – Two-pass rename to avoid overwrites; collision detection in preview.
- **Undo** – After applying renames, use **Undo last rename** in the same folder to revert (undo log is stored as a hidden file in that folder).

## Requirements

- Python 3.10+
- PyQt6

## Install and run

```bash
cd /path/to/HSRename
pip install -r requirements.txt
python main.py
```

Or with a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py
```

## Usage

1. **Browse** to a folder (only files in that directory are listed; hidden files are skipped).
2. Pick a **rule type** from the dropdown and check **“Use this rule”**.
3. Configure the rule. You can enable several rules; they run in a fixed order.
4. Check the **Preview** table (Original name → New name). Resolve any duplicate-name warnings.
5. Click **Apply renames** and confirm.

### Episode renumbering example

- Files: `S01E12 - Pilot.mkv`, `S01E07 - Second.mkv`, …
- Enable **Episode renumber**, set **First episode number** to `1`, **Step** to `1`, **Zero-pad width** to `2`.
- Preview: `S01E12 - Pilot.mkv` → `S01E01 - Pilot.mkv`, `S01E07 - Second.mkv` → `S01E02 - Second.mkv`, etc. Titles are preserved.

Sort order is the current list order (alphabetical by filename). Reorder files in the table (e.g. by dragging) if you add that later; for now, use the order given after opening the folder.

### CSV mapping

1. Create a CSV with header row: **Original Name**, **Target Name**.
2. One data row per file: first column = current filename, second column = desired new name.
3. Enable **9. CSV mapping**, click **Browse…** and select the CSV.
4. Only rows that match a current filename in the folder are renamed; others are unchanged. You can combine with other rules (CSV is applied in rule order).

## Gear Lever (AppImage updates)

To have [Gear Lever](https://github.com/mijorus/gearlever) see new releases when we push them and update the AppImage from there, see **[docs/GEARLEVER.md](docs/GEARLEVER.md)** for configuration (custom update URL for Gitea, or static URL).

## AppImage (distribution)

To build a portable AppImage:

```bash
pip install -r requirements.txt -r requirements-build.txt
./build_appimage.sh
```

You need [appimagetool](https://github.com/AppImage/AppImageKit/releases) installed to produce the final `.AppImage`; if missing, the script still creates the AppDir and prints the exact command. The output is `HSRename.AppImage`.

## Push to Gitea

See [PUSH_TO_GITEA.md](PUSH_TO_GITEA.md) for adding this repo to your Gitea and pushing.

## License

MIT.
