https://github.com/igrek51/regex-rename
Bulk rename tool based on regular expressions to rename multiple files at once
https://github.com/igrek51/regex-rename
bulk regex regular-expression rename rename-files
Last synced: 5 months ago
JSON representation
Bulk rename tool based on regular expressions to rename multiple files at once
- Host: GitHub
- URL: https://github.com/igrek51/regex-rename
- Owner: igrek51
- License: mit
- Created: 2017-03-13T22:50:48.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-09-23T13:31:57.000Z (about 1 year ago)
- Last Synced: 2025-04-19T20:44:11.352Z (6 months ago)
- Topics: bulk, regex, regular-expression, rename, rename-files
- Language: Python
- Homepage: https://igrek51.github.io/regex-rename/
- Size: 972 KB
- Stars: 24
- Watchers: 3
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# regex-rename
[](https://github.com/igrek51/regex-rename)
[](https://pypi.org/project/regex-rename)
[](https://igrek51.github.io/regex-rename)
[](https://codecov.io/gh/igrek51/regex-rename)
[](https://github.com/igrek51/regex-rename/actions?query=workflow%3Atest)
Bulk rename tool based on regular expressions to rename multiple files at once.
## Quickstart
Renaming multiple files at once:
```shell
$ ls # awful names:
b45XDS-01.mp3 QsEW2s-02.mp3 VF7t6L-03.mp3
$ regex-rename '-(\d+).mp3' '\1_NeverGonnaGiveYouUp.mp3' --rename
[2022-04-09 09:19:15] DEBUG matching regular expression pattern to files: pattern=-(\d+).mp3 replacement=\1_NeverGonnaGiveYouUp.mp3 full_match=False dry_run=False
[2022-04-09 09:19:15] INFO renaming file: from=b45XDS-01.mp3 to=01_NeverGonnaGiveYouUp.mp3
[2022-04-09 09:19:15] INFO renaming file: from=QsEW2s-02.mp3 to=02_NeverGonnaGiveYouUp.mp3
[2022-04-09 09:19:15] INFO renaming file: from=VF7t6L-03.mp3 to=03_NeverGonnaGiveYouUp.mp3
[2022-04-09 09:19:15] INFO files renamed: renamed=3 mismatched=0
$ ls # now we're talking:
01_NeverGonnaGiveYouUp.mp3 02_NeverGonnaGiveYouUp.mp3 03_NeverGonnaGiveYouUp.mp3
```
## Installation
```shell
pip3 install regex-rename
```
It requires Python 3.7 (or newer) with pip.
## Tutorial
Imagine you have 51 audio files with hideous names like this and you wish to rename them:
- `Stanislaw+Lem+Invincible+(01).mp3` -> `01 The Invincible.mp3`
- `Stanis▯aw+Lem+Invincible+(02 ).mp3` -> `02 The Invincible.mp3`
- `Stanisław_Lem_Invincible (03) .mp3` -> `03 The Invincible.mp3`
- …
- `Stanis▯aw+Lem+Invincible+(51).mp3` -> `51 The Invincible.mp3`
Specifically, you want to place the episode number at the beginning.
### Step 1: Match
Regular Expressions can be tricky.
We figured out this pattern may match the files and extracts the episode number:
```regexp
(\d+).*mp3
```
First, let's check this pattern in a dry run: `regex-rename '(\d+).*mp3'`
Pay attention to the extracted regex groups.
### Step 2: Replace
Now, we'd like to replace all files to a pattern:
```regexp
\1 The Invincible.mp3
```
`\1` is a first group extracted by the matching pattern (episode number).
Let's test it by adding the replacement pattern: `regex-rename '(\d+).*mp3' '\1 The Invincible.mp3'`
### Step 3: Execute
All above commands were just dry-run so that we could experiment with regex patterns.
Once we're sure that everything is matched correctly, we can append `--rename` flag,
which does the actual renaming:
`regex-rename '(\d+).*mp3' '\1 The Invincible.mp3' --rename`
Finally, files are named properly:
- `01 The Invincible.mp3`
- `02 The Invincible.mp3`
- `03 The Invincible.mp3`
- …
- `51 The Invincible.mp3`
## Beyond the Regex
`regex-rename` also supports some transformations not covered by regular expressions standard:
- Converting to lowercase by adding `\L` before group number:
`regex-rename '([A-Z]+).mp3' '\L\1.mp3'`
eg. `AUDIO.mp3` to `audio.mp3`
- Converting to uppercase by adding `\U` before group number:
`regex-rename '([a-z]+).mp3' '\U\1.mp3'`
eg. `audio.mp3` to `AUDIO.mp3`
- Padding numbers with leading zeros by adding `\P2`, `\P3`, … (depending on padding length) before group number:
`regex-rename '(\d+).mp3' '\P2\1.mp3'`
eg. `1.mp3` to `01.mp3`
- Padding numbers with leading zeros by specifying `--pad-to` parameter:
`regex-rename '(\d+).mp3' '\1.mp3' --pad-to=2`
eg. `1.mp3` to `01.mp3`
## More examples
- Extract season and episode numbers, eg. `episode-02x05.mkv` to `S02E05.mkv`:
```shell
regex-rename '(\d+)x(\d+)' 'S\1E\2.mkv' --rename
```
- Swap artist with title, eg. `Echoes - Pink Floyd.mp3` to `Pink Floyd - Echoes.mp3`:
```shell
regex-rename '([^-]+) - ([^-]+)\.mp3' '\2 - \1.mp3' --rename
```
- Pad leading zeros, eg. `1.mp3` to `001.mp3`:
```shell
regex-rename '(\d+).mp3' '\P3\1.mp3' --rename
```
- Convert to lowercase, eg. `SONG.MP3` to `song.mp3`:
```shell
regex-rename '(.+)' '\L\1' --rename
```
- Convert to uppercase, eg. `Tool.mp3` to `TOOL.mp3`:
```shell
regex-rename '(.+)\.mp3' '\U\1.mp3' --rename
```
- Add prefix, eg. `Doors.mp3` to `The Doors.mp3`:
```shell
regex-rename '(.+)' 'The \1' --full --rename
```
- Change extension, eg. `Songbook.apk` to `Songbook.zip`:
```shell
regex-rename '(.+)\.apk' '\1.zip' --rename
```
- Turn directories into prefixes and move files, eg. `Pink Floyd/Echoes.mp3` to `Pink Floyd - Echoes.mp3`:
```shell
regex-rename '(.+)/(.+).mp3' '\1 - \2.mp3' --full --recursive --rename
```
- Rename files in different directories, preserving their parent directories,
eg. `app/logs/file-001.log` to `app/logs/file_001.txt`:
```shell
regex-rename '(.*)/file-([0-9]+).log' '\1/file_\2.txt' --full --recursive --rename
```
- Rename files piped from another command like `find`,
eg. `songs/Jimmi - Voodoo Child.mp3` to `songs/Jimi - Voodoo Child.mp3`:
```shell
find -iname '*jimmi*' | regex-rename '(.*)/.* - (.*).mp3$' '\1/Jimi - \2.mp3' --rename
```
## Usage
Enter `regex-rename` for help:
```shell
$ regex-rename
regex-rename v1.3.0 - Bulk rename tool based on regular expressions to rename multiple files at once
Usage:
regex-rename [OPTIONS] PATTERN [REPLACEMENT]
Arguments:
PATTERN - Regex pattern to match filenames
[REPLACEMENT] - Replacement regex pattern for renamed files. Use \1, \2 syntax to make use of matched groups
Options:
--version - Print version information and exit
-h, --help [SUBCOMMANDS...] - Display this help and exit
-r, --rename - Does actual renaming files instead of just testing replacement pattern
--full - Enforces matching full filename against pattern
--recursive - Search directories recursively
--collate - Compare source filenames with the replaced names
--short - Print output in short, less verbose format without time
--pad-to PAD_TO - Applies padding with zeros with given length on matched numerical groups
```