# rename /

Filename Size Date modified Message
bin
src
32.1 KB
4.2 KB
1.9 KB

# rename

Renames files using regular expression matching. This enables elegant handling of multiple renames using a single command.

## Installation

This script requires Python 2.4+ with the argparse library. It can be used standalone or installed using pip or easy_install:

pip install rename
easy_install rename


## Usage

Basic syntax:

rename [-t] "regex" "target"


## Options

### -t, or --test

When used, the script will only fake renaming and verbosely state what it would do. Use this if you're unsure of the effects your expression may cause.

### regex

Regular expression that matches source files which are to be renamed. Examples:

"(\w+).caf"
"IMG(\d\d\d\d\).[Jj][Pp][Ee]?[Gg]"
"([0-9]{2})-([0-9]{2})-([12][0-9]{3}).log"


### target

Name of the target file with references to regular expression groups caught in the source matches. References to groups are formed by a backslash character followed by he group number. Groups are indexed from 1. The group number can be contained within parentheses to disambiguate a reference followed by digits. Examples:

"\1.aiff"
"\(1)1337.zip"
"\3-\1-\2.log"


## Security

1. The script will not let multiple files be renamed to a single name.
2. The script will not let existing files to be overwritten.
3. Both checks above are made for all matches before any renaming is performed.

## Other remarks

1. Regular expressions supported by the script must conform to the syntax handled by Python's re module.
2. The regular expression is global by default (e.g. writing "[0-9]" means "^[0-9]\$. This is to avoid accidental partial catches. If you want to match all files that start or end with a specific expression, add .* to the expression, e.g. ".*\.mp3" will match all files that end with .mp3.
3. Actual renaming of a single file is done by the os.rename() function from Python's standard library. No additional atomicity is ensured, e.g. if a single rename fails halfway through, the filesystem is left in a state of partially complete renaming.
1. Due to differences in behaviour of different shells, the recommended form of execution is to put both arguments in quotation marks.

## Possible future enhancements

1. Automatic numbering with \(auto) target reference.

2. -p option to create intermediate directories for the target. One tiny problem is maintaining atomicity of the whole transaction.

3. -v except_regex option to constrain source matches to those that don't match except_regex. This would enable easy handling of special cases.

4. -r option to make the source match recursive. Tricky to get right I guess, e.g. where to rename? Existing directory structure or new one?. Let the user decide? What's the default? Etc. etc.

5. -s option to enable a "translate" mode to replace certain substrings with other, example (translating underscores to spaces):

rename.py ".*\.txt" -s "_" " "

6. -l option to enable translating all letters to lowercase. -U option to translate letters to uppercase.

## BFD: BIG FRIENDLY DISCLAIMER

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

DON'T PANIC. This code has been successfully used by its author. However, be especially wary under these conditions:

1. Renaming between filesystems.
2. Renaming under case-insensitive filesystems.
3. Renaming within very long paths.
4. Renaming volatile state (e.g. rotating logs).

And if you do lose any data, it's your fault. Have a nice day!

## Authors

Script glued together by Łukasz Langa.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.