PRENAME(1)

📦
version 1.14 · 3 versions
, in epel 9

🎀 PRENAME 🎀

ok so first things first, bestie: this is the prename man page from the User Contributed Perl Documentation section (section 1, obviously), and it's literally the glow-up your messy file names have been waiting for. buckle up 💅

✨ NAME ✨

prename — renames a whole bunch of files at once using perl expressions. yes, plural. yes, at once. slay.

🌸 SYNOPSIS 🌸

prename [-bcfilnv] [-B prefix] [-S suffix] [-V method] [-Y prefix] [-z
suffix] [--backup] [--copy] [--basename-prefix=prefix] [--dry-run]
[--force] [--help] [--no-stdin] [--interactive] [--just-print]
[--link-only] [--prefix=prefix] [--suffix=suffix] [--verbose]
[--version-control=method] [--version] perlexpr [files]...

🦋 DESCRIPTION 🦋

ok so here's the whole vibe: prename renames the filenames you hand it, following the rule you gave as the first argument. that rule is a Perl expression, and the entire expectation is that it modifies the $_ string for at least some of the filenames you passed in. that's it. that's the assignment.

important detail fr: if a given filename does not get modified by your expression, it does not get renamed. no changes, no chaos, it just sits there looking cute.

and if you don't give any filenames on the command line? then filenames get read in via standard input instead — unless you passed --no-stdin on the command line, in which case nope, not doing that.

now the spicy part 🔥: if a destination file is unwritable, AND standard input is a tty, AND you did not give -f or --force, then prename will actually prompt you about whether to overwrite the file. if your response doesn't start with y or Y, the file gets skipped. no take-backs, no drama.

💖 OPTIONS 💖

  • -b, --backup — make backup files, bestie. meaning: when it's about to overwrite a file, it renames the original instead of yeeting it. (check -V / --version-control for how the backup file names actually get figured out.)
  • -B prefix, --prefix=prefix — uses the simple method for determining backup file names (peep the -V method / --version-control=method option for that), and sticks prefix on the front of a file name when it generates that file's backup file name.
  • -c, --copy — copies files to the new names instead of renaming them. the original files stay put. icon behaviour, honestly 🫶
  • -f, --force — removes existing destination files and never prompts the user. aggressive. powerful. use with intent 💀
  • -h, --help — prints a summary of the options and dips.
  • --no-stdin — turns off reading filenames from STDIN. use it when your shell has nullglob enabled so prename doesn't just sit there waiting for input like 👁️👄👁️
  • -i, --interactive — prompts you about whether to overwrite each destination file that already exists. if the response doesn't begin with y or Y, the file is skipped. consent matters ✨
  • -l, --link-only — links files to the new names instead of renaming them. original files? kept. we love a non-destructive queen.
  • -n, --just-print, --dry-run — does everything except the actual renaming; instead it just prints the name of each file that would be renamed. and when you use it together with --verbose, it also prints names of backups — which may or may not be correct depending on previous renaming. (so like, cute preview, but read it with a little skepticism 🙈)
  • -v, --verbose — prints the name of each file before renaming it. narration! we stan a transparent process.
  • -V method, --version-control=method — uses method to determine backup file names. method can also be given by the RENAME_VERSION_CONTROL environment variable (or, if that one's not set, the VERSION_CONTROL environment variable) — and this option overrides those. huge clarification: this option does not affect whether backup files are made. it only affects the name of any backup files that are made.

the value of method is like the GNU Emacs version-control variable, and prename also recognizes synonyms that are more descriptive. the valid values are (unique abbreviations are accepted):

  • existing or nil — makes numbered backups of files that already have them, otherwise simple backups. this is the default.
  • numbered or t — makes numbered backups. the numbered backup file name for F is F.~N~ where N is the version number.
  • simple or never — makes simple backups. the -B or --prefix, -Y or --basename-prefix, and -z or --suffix options specify the simple backup file name. if none of these options are given, then a simple backup suffix is used — either the value of the SIMPLE_BACKUP_SUFFIX environment variable if set, or ~ otherwise.
  • --version — prints version information on standard output, then exits successfully. bye bestie 💜
  • -Y prefix, --basename-prefix=prefix — uses the simple method for determining backup file names (again, see -V method / --version-control=method), and prefixes prefix to the basename of a file name when generating its backup file name. for example, with -Y .del/ the simple backup file name for a/b/foo is a/b/.del/foo. see how that works? the basename got the prefix, the directory stayed iconic 💅
  • -z suffix, -S suffix, --suffix=suffix — uses the simple method for determining backup file names (yep, -V method / --version-control=method again), and appends suffix to a file name when generating its backup file name.
  • --shell-completion=shell, --shellcompletion=shell — generates shell code for parameter completion for either bash or zsh. tab-completion stans rise 🌈

🔥 EXAMPLES 🔥

want to rename all files matching *.bak to strip the extension? you might say:

prename 's/\e.bak$//' *.bak

want to translate uppercase names to lower? you'd use:

prename 'y/A-Z/a-z/' *

more examples, because we're generous:

prename 's/\.flip$/.flop/' *     # rename *.flip to *.flop
prename s/flip/flop/ *           # rename *flip* to *flop*
prename 's/^s\.(.*)/$1.X/' *     # switch sccs filenames around
prename 's/$/.orig/' */*.[ch]    # add .orig to source files in */
prename 'y/A-Z/a-z/' *           # lowercase all filenames in .
prename 'y/A-Z/a-z/ if -B' *     # same, but just binaries!

or even:

prename chop *~                  # restore all ~ backup files

🍓 ENVIRONMENT 🍓

two environment variables are in play: SIMPLE_BACKUP_SUFFIX and VERSION_CONTROL. see "OPTIONS" above for the whole story 👑

🧚 SEE ALSO 🧚

mv(1) and perl(1). go give them a little visit, they're family.

⭐ DIAGNOSTICS ⭐

if you give an invalid Perl expression, you'll get a syntax error. that's the whole diagnostic. perl said what it said 💀

👑 AUTHOR 👑

Peder Stray <pederst@cpan.org> — and the original script is from Larry Wall. legends only.

🌸 BUGS 🌸

report any issues at <https://github.com/pstray/rename/issues>. (yes bestie, real link, go click it if something's cursed.)

ok that's the whole page 💖 this was perl v5.32.1, dated 2023-06-22, served fresh from the PRENAME(1) corner of the User Contributed Perl Documentation. go forth and rename responsibly, mwah 🎀✨

📦 where this page comes from