Glindra
Documentation Index Download
Command Line File Handling and ASCII Tools

rena - Rename


Renames one or more files, or moves them to another directory on the same device.

Example (Windows)
> rena ***\*.html \backup\***\*.htm -before=yesterday
Renamed to: e:\backup\about.htm
Renamed to: e:\backup\index.htm
Created dir: e:\backup\doc\
Renamed to: e:\backup\doc\00readme.htm
Created dir: e:\backup\doc\old
Renamed to: e:\backup\doc\old\index.htm
19 kb renamed, 4 files


rena accepts the same wildcards and file selection options as the d directory command.

The rena command supports version numbers. If an output file already exists, it is not overwritten. Instead the existing file is renamed with a version number, before the input file is renamed to the name without a version number.


Parameters

Input File Specification

Example
> rena a.xyz b.xyz


The first parameter is an input file specification.  rena accepts the same wildcards as the d directory command. See File Specifications.

No default wildcards for input file

Unlike the d directory command, rena does not add any defaults to the input file specification, so you must specify all wildcards explicitly.

This makes rena a bit less generous than the d directory command, just like the cop (copy) command. This stinginess is intentional.

Wildcards to use with cop and rena:
*.*.* All versions of all files in the directory.
*.*
*.*.
The highest version of all files in the directory, but not the previous versions.

Both variants have the same meaning. The first one is shortest.

*
*.
The highest version of all files in the directory that have an empty extension.

Note that this is different from how a Unix shell would interpret a single asterisk. It is also different from the meaning it has in the d directory command, where wildcards for extension and version number are added automatically.

*..*
*.~*~
All versions of all files in the directory that have an empty extension.

If you use the syntax with only one dot, the tildes are required, or the last asterisk will be interpreted as "all extensions" rather than "all versions".


Multiple input files

If you want to give a list of input files, they must be enclosed in parentheses (to separate them from the second parameter, which is the output file specification). The parentheses must be prefixed with the backslash escape character under Linux.

Example (Windows)
> rena (*.html x.css *.gif) publish\
Example (Linux)
> rena \('*.html' 'x.css' '*.gif'\) publish/

Output File Specification

Example
> rena a.xyz b.xyz


The second parameter is an output file specification, which is described on the page Output File Specifications.

The rest of the description here deals with specifics for the rena command.

Output file default is *.* in original directory
The default output file specification is "*.*".  If you do not specify any output directory, the files will remain in their respective original directories. Note how this is different from the cop command.

If you want to move files to the current working directory, you have to specify it explicitly with a dot.

Example
> rena '/somewhere/else/*.html' .
moves the files to the current directory.


If you want to move files to another directory without changing their names, you can omit the name and extension wildcards in the output file specification.

Example
> rena '*.html' 'publish/'

Normalizing version numbers

Suppose we have the following files in a directory:

Directory of e:\work\

2 kb 12-Jan-2005 14:58:55 myfile.txt.~1~
2 kb 14-Jan-2005 02:17:30 myfile.txt.~2~
----------
4 kb total, 2 files

The most current version of the file is the one with version number .~2~ . Normally the most current version does not have any version number as part of the disk filename, but here it does. This situation occurs when we delete the last version of a file, in order to revert to the previous one.

If we give the command

> rena myfile.txt

(without any output file specification), rena will normalize the filename of the last version.

The result will be:

Directory of e:\work\

2 kb 12-Jan-2005 14:58:55 myfile.txt.~1~
2 kb 14-Jan-2005 02:17:30 myfile.txt
----------
4 kb total, 2 files


This very useful functionality follows automatically from the syntax and defaults of the rena command. If we type

> rena '*.*'

this is the same as

> rena '*.*' '*.*'

after the default wildcards have been added to the (empty) output file specification.

The meaning of this is to take the most current version of all files (whether they have an explicit version number or not), and rename them to the same name in the same directory, using the version number mechanism.

For the files where the current version does not have an explicit version number (which is the normal case), the rename operation is a no-op, and is not carried out. But when the most current version does have a version number, the version number mechanism will ensure that it is renamed so that the version number is removed.

Renaming directories

Directories can be renamed just like any other files. This has the effect of "moving" all files and subdirectories in the entire directory tree.

Example
> rena mydir old

renames the directory mydir to old. All the files that were previously located somewhere in mydir\***\ can now instead be found in old\***\.

Do not use the *** wildcard in the command line when renaming directory trees, as you would with the cop command.  This is an important difference between the two commands. Renaming the top directory implicitly renames the entire directory tree, while copying the top directory only creates an empty directory.

If you try to rename a directory tree using the *** syntax that is appropriate for the cop command, the end result will be correct (because the rename operation starts at the top), but you'll get a lot of spurious error messages saying "no such file".


Options

File Selection Options

Example (Windows)
> rena ***\*.*.* junk\ -exclude=(.doc .txt) -before=today -min_size=2mb -hidden=also
Example (Linux)
> rena '***/*.*.*' junk/ -exclude=\(.doc .txt\) -before=today -min_size=2mb -hidden=also
Options
-since [= datetime] Select files that were created on or after a certain date/time.
-before [= datetime] Select file that were created before a certain date/time.
-min_size [= size] Specify a minimum file size in bytes, Mb, or some other unit
-max_size [= size] Specify a maximum file size .
-directories [= only/also/not]
List directory files (only/also/not) . Default is also.
-hidden [= only/also/not] List hidden files (only/also/not). Default is not.
-nodefault Do not add any default wildcards or other filename parts to the filename.

For the rena command, option is used to suppress wildcards in the output file specification. (The input file specifications has no default wildcards to suppress.)

-exclude [= filespec] Exclude files that match the file specification given as option value. If the option value is enclosed in parenthesis, it can contain a full file specification, including recursive file selection options.

These options control which files are selected. See File Selection Options.

Filename Cleanup Options

Example (Windows)
> rena *.* -lower -portable
Example (Linux)
> rena '*.*' -lower -portable
Changes all filenames in the directory to lower case, and converts characters that are likely to cause problems on some platforms.
Options
-safe
  • Maps leading dashes (hyphens) to underscores.
  • Collapses spaces.
  • Maps problematic characters like *?:[]"<>|(){} to underscore.
-portable Performs the same cleanup operations as -safe, and additionally:
  • Maps all 8-bit characters from the upper half of the Latin 1 alphabet to reasonable 7-bit fallback characters.
  • Maps the single quote characters '`´ to underscore.
-lower
-upper
-title
Converts the filenames to lower, UPPER, or Title Case.
-nospace Maps all spaces to underscore.
-nodash Maps all dashes (hyphens) to underscore.

These options  are used to clean up filenames. See Filename Cleanup Options

Help and Information Options

Example
> rena '*.log' '*.oldlog' -nowarning
Options
-help   -h   -?
Print out a brief help text with a summary of each of the different options, and exit from the program.
-version Show the name and version number of the program, and exit. This option must be written out in full, and cannot be abbreviated.
-verbose   -v
-statistics
-noverbose
Specify the amount of informational messages.
-warning
-nowarning
-noerror
Specify the level of error reporting.

See Help and Information Options.