mar

mar (ini­tially mr, but the name was already taken) is a versy sim­ple and intu­itive file renam­ing tool with a very easy to learn syn­tax (unlike other mass renam­ing tools, there is only one impor­tant syn­tax element).

Usage exam­ples

mar comes with very few com­mand line para­me­ters. You can list them by pass­ing the para­me­ter -h to it.

$ mar -h
Usage: mar [options] mask files

Options:
  --version        show program's version number and exit
  -h, --help       show this help message and exit
  -n, --no-colors  disable colored output
  -q, --quiet      dismiss status informations
  -b, --backup     creating backup CSV file
  -s N, --start-with=N  start numbering with N instead 1  
  -v, --verbose    print verbose output

Like all my pro­grams, mar uses col­ored out­put. When pass­ing the para­me­ter -q all out­put except errors are hid­den. FYI: All out­puts are writ­ten to STDERR by default because i want to extend the pro­gram in future and there will be out­put in STDOUT for fur­ther processing.

In this doc­u­men­ta­tion I use a set of 10 000 files. Accord­ing to time, mar processes (renames) all files in about 2.5 sec­onds – it will be fast enough for daily needs (I fre­quently process around 100-​200 files with mar, it hap­pens nearly instant).

For pro­cess­ing files you need to pass two oblig­a­tory infor­ma­tions. mask is a string con­tain­ing every char­ac­ters you want (please desist from using slashes. It MIGHT work for mov­ing files, but I wouldn’t rely on it …) plus the string %s (… and right now you’ll not be able to use a lit­eral %s, sorry). On file pro­cess­ing %s will be replaced with the cur­rent file’s number.

With files you give mar the files you want to use. You can use any­thing you know from shell. Wild­cards, rel­a­tive paths, absolute paths, quotes, escaped char­ac­ters, and so on.

The above exam­ple video shows a usual call with no para­me­ters. You get some infor­ma­tions on what’s hap­pen­ing at the moment and after pro­cess­ing the files you get an infor­ma­tion if every­thing went fine (“fine” as in: “the oper­at­ing sys­tem did not return any errors”). If some­thing went wrong dur­ing file pro­cess­ing, you get an infor­ma­tion about this.

Multiple examples for showing several error messages

The above exam­ple shows all error cases. The renam­ing mask describes what the exam­ple is about. As you can see, the arrow’s color indi­cate the infor­ma­tion type: yel­low stands for infor­ma­tional out­put, red is for errors and warn­ings, and green is for suc­cess­ful oper­a­tions. The last exam­ple shows a lot of infor­ma­tions: The ignored “not file” inputs, and two pro­cess­ing errors because of already exist­ing files.

Example call with parameter -b

If you’re going to process impor­tant data, or want to pre­serve the file names for other rea­sons, pass the para­me­ter -b. This cre­ates a (hope­fully g) unique file name in the first file’s direc­tory. This file con­tains a valid CSV list with old and new file names for easy processing.

"Old file name","New file name"
"test/bar","test/new name 1"
"test/blah","test/new name 2"
"test/blubb","test/ new name 3"
"test/foo","test/ new name 4"
"test/moar","test/new name 5"

You can parse (with awk, for exam­ple) the file and restore the orig­i­nal file names, or pro­vide the file (maybe because you renamed files for pub­lish­ing them in the web and want your cus­tomers to restore actual file names).

The most sim­ple call is mar -qn mask files. This turns off all out­put except errors, and removes all ANSI color codes from error messages.

Arch Linux package

There is a pack­age for Arch Linux in AUR. See mar-​git for details. The pack­age uses the lat­est Git sources acces­si­ble at GitHub.

Download sources

See GitHub for details. All my code is available under GPLv3 or later.