# rename

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

## Usage

Basic syntax:

rename [-I] [-l] [-q] [-t] [-u] [-v "except_regex"] "regex" "target"

rename -s [-I] [-l] [-q] [-t] [-u] [-v "except_regex"] "substring_from" "substring_to" "regex"

rename --selftest [directory]


## Options

### 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"


### --index-first

When using the special \(index) reference, this option specifies what number will the first index be. Default: --index-first=1.

### --index-step

When using the special \(index) reference, this option specifies what number will be added with each step to the first value. The specified number can be negative. Default: --index-step=1.

### --index-digits

When using the special \(index) reference, this option specifies how many digits will be used in each reference. If a number has fewer digits, they will be prefixed by leading zeroes (or another character, see: --index-pad-with). A special value of auto can be used to automatically pad enough digits so that each filename has the same amount of them used. This is useful for ensuring your files will be sorted correctly even by dumb algorithms. Default: --index-digits=auto.

When using the special \(index) reference, this option specifies what character will be used for padding. Default: --index-pad-with=0.

### --selftest

Runs internal unit tests of all functionality. Does actual renaming of a generated set of files in the specified directory. If no directory is passed, uses the temporary directory. Each test generates its own set of files.

## 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


Don't have either of these? You can always grab the latest source release from the PyPI website or better yet equip yourself with easy_install by downloading and running distribute_setup.py.

## 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.
4. The script correctly preserves extended attributes and ACLs.

## Other remarks

1. Regular expressions supported by the script must conform to the syntax handled by Python's re module.
2. 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.
3. 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. -p option to create intermediate directories for the target. One tiny problem is maintaining atomicity of the whole transaction.
2. -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.
3. Interactive mode. Things to be thought over: should the question appear before the transaction begins, before each step, or both? Should that be one option?

## 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 and contains tests. However, be especially wary under these conditions:

1. Renaming between filesystems.
2. Renaming under non case-preserving 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.