HS-Rename/README.md

HSRename

A native Linux GUI for mass renaming files. Inspired by Bulk Rename Utility (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. Start number 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

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

Or with a virtual environment:

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).

AppImage (distribution)

To build a portable AppImage:

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

You need appimagetool 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 for adding this repo to your Gitea and pushing.

License

MIT.