citizenTwice/srnames

Multiplatform command-line rename utility for search and replace in file and directory names

srnames

Multi-platform search+replace file & directory rename utility.

Table of Contents

Features
Supported platforms
Syntax
Notes
Examples
Demos
Download & binaries
Building
License
Feedback & Contributing

Features

• Rename files and/or directories, recursively if needed
• Regex support
• Variables in replacement expressions
• Preview actions without making changes
• Create changes log, for undo (provided by separate scripts)
• Unicode support
• Portable, stand-alone executables
• Builds without dependencies other than the platform's compiler/SDK

Platforms

• macOS
• Linux
• Windows (ASCII & Unicode builds)
• DOS/DPMI, FreeDOS - [experimental, some features are not available]

Syntax

srnames [options] str1 str2
  Search and replace file/dir names.
  Parameters:
    str1, --search=str1              String to search to for.
    str2, --repl=str2                Replacement string.
  Options:
      -i, --ignore-case              Ignore case in searches.
      -d, --dirs-too                 Also rename directories (default is files-only.)
      -D, --dirs-only                Only rename directories (no files.)
      -a, --start-at=path            Start searching at given path.
                                     Default is: current directory.
      -r, --recurse                  Recursively include all directories.
          --regex                    Interpret search string as regex.
                                     Makes capture groups available in replacement string.
          --what-if                  Preview results without making any changes.
          --dry-run                  Same as --what-if.
      -q, --quiet                    Do not print changes to stdout.
      -y, --yes                      Skip initial confirmation prompt.
          --chglog=filepath          Log changes (enables undo).
                                     On by default (temp file) for some platforms.
      -n, --no-chglog                Disable changes log.
  Exit codes:                        0 = Success.
                                     1 = Error.
  Regex replacement variables:       $1..n = Capture group n. E.g. 'file_(\d+)'
                                     $&    = The entire regex match
  Repl. string variables:            (applied after regex, when that's available)
                                     #dir  = Parent dir of current item.
                                     #dtm  = YYYYMMDDhhmmss.
                                     #del  = empty string "".
                                             to remove str1 inst.of replacing it.
                                     #cnt  = Rename counter.
                                     #2cnt = ditto, zero-filled NN.
                                     #3cnt = ditto, zero-filled NNN.
                                     #4cnt = ditto, zero-filled NNNN.
                                     #8cnt = ditto, zero-filled NNNNNNNN.
                                     ##    = literal #.

Notes

Unix Shells

Use single quotes '' to prevent the shell from altering search/replace strings:

--search=([_-]+) -> '--search=([_-]+)' 
--repl=$1_$1     -> '--repl=$1_$1' 
--repl=#del      -> '--repl=#del' 

Windows CMD.EXE

Special character ^ should be escaped as ^^ in order for it to passed to the program:

--search=^begin  -> --search=^^begin

Unicode support

On macOS and Linux, Unicode should work out-of-the-box with UTF-8 locales. On working with regular expressions, remember that things like Emoji's do not necessarily count as or expand to a single character. On Windows, there is separate build SRNAMESU.EXE, Unicode will not work with the normal, ASCII-only build SRNAMES.EXE.

DOS

Unicode support and regular expressions are not available under DOS due to lack of experience building Unicode under DOS and not being able to find a usable std::regex implementation (yet.)

Examples

change file extension for whole tree

Replace .CPP file extension with .cc for the whole codebase:

srnames.exe -r --search=.CPP --repl=.cc --start-at=$HOME/prj/src/

remove spaces

Remove spaces from file names in the current directory

srnames.exe " "  #del

Same as above but also rename directories

srnames.exe " "  #del -d

use of cnt variable

Align/anonimize file & directory names, saving the original names to the changelog.

srnames.exe -r --regex --search=.* --repl=FILE_#cnt.BIN --chglog=FILECHANGES.LOG --start-at=W:\SHARE\ -q -y 
srnames.exe -r -D --regex --search=.* --repl=DIR#8cnt --chglog=DIRCHANGES.LOG --start-at=W:\SHARE\ -q -y

regex search & replace

Prefix images with parent dir name, preserving image number, so files can be merged into a single directory

 % find .
./THUMB
./THUMB/IMG0397.JPG
./THUMB/IMG0437.JPG
./THUMB/IMG0450.JPG
./THUMB/IMG0402.JPG
./img
./PIC/IMG0397.JPG
./PIC/IMG0437.JPG
./PIC/IMG0450.JPG
./PIC/IMG0402.JPG
 # DO notice options have been 'quoted' to prevent the shell from corrputing the passed parameters
 % srnames -r --regex '--search=IMG(\d\d\d\d)' '--repl=#dir_$1' -q -y && 
  mv PIC/* img/ &&
  mv THUMB/* img/
 % find . 
./PIC
./THUMB
./img
./img/PIC_0397.JPG
./img/PIC_0402.JPG
./img/PIC_0437.JPG
./img/PIC_0450.JPG
./img/THUMB_0397.JPG
./img/THUMB_0402.JPG
./img/THUMB_0437.JPG
./img/THUMB_0450.JPG

Rolling-back changes

Creating a changelog is recommended as it makes it possible to undo/'unrname' what was changed. The changelog is created by default on some platforms and can be specified via command-line with the --chglog option. The below scripts (which can be found in the tools directory) can use the changelog to roll-back changes.

Mac/Linux

./tools/make_undo_script.sh CHANGES_TO_LINUX_MASTER.LST
bash UNDO_SCRIPT_95613.sh
Done!

Windows

powershell -ExecutionPolicy Bypass -File tools\ps_undo_rename_from_changelog.ps1
Please enter path to changelog file: CHANGES.LOG
Done!

Demos

regex & Unicode

Simple DOS rename

Windows Unicode

The Unicode build on Windows should handle things like emojis without problems even if they don't show up correctly in the console

Undo demo

Download

Head over to Releases

Building

macOS

• requirements: recent (as of 2021) XCode version
• build command build_macos.sh

Linux and other *ix

• requirements: recent (as of 2021) GCC C++ version
• build command build_unix.sh
• it is possible to create a static build on some systems. See comments in build_unix.sh for an example.

Windows

• requirements: Visual C++ from VS2019 or newer
• build command build_vc2019.cmd

DOS

• requirements: recent (as of 2021) OpenWatcom C/C++
• build command BUILDOS.BAT

License

MIT License

Feedback

Bugs/Suggestions/Comments/Feedback to:

• Email: feedback@THLG.NL

Finally

Thanks for visting!