RENAME(1p)

💅 RENAME(1p) — like, the file-rename manual bestie

okay so before we even start: this is RENAME(1p) from the User Contributed Perl Documentation crew, and it's genuinely one of those tools that changes your whole life once you get it. no cap. let's go 🦋

---

✨ NAME ✨

file-rename — renames multiple files 💖

like. multiple. files. at once. iconic behaviour fr.

---

🌸 SYNOPSIS 🌸

file-rename [ -h|-m|-V ] [ -v ] [ -0 ] [ -n ] [ -f ] [ -d ] [ -u [enc]] [ -e|-E perlexpr]*|perlexpr [ files ]

---

🎀 DESCRIPTION 🎀

So file-rename takes the filenames you hand it and renames them according to the rule you pass as the first argument. That's the whole vibe.

The perlexpr argument is a Perl expression, and it's expected to mess with the $_ string in Perl for at least some of the filenames you specified. Important bit, bestie: if your expression doesn't modify a given filename, that file just does not get renamed. No drama, no error, it simply sits there unbothered. 💅

And if you don't give any filenames on the command line at all? Then filenames get read via standard input. yes queen, pipes work.

---

🌈 Examples (Larry Wall, 1992) 🌈

not me citing the actual Larry Wall, the man himself, from 1992. legend behaviour.

So like, say you wanna rename all files matching *.bak and strip that extension off — you'd say:

file-rename -- 's/\.bak$//' *.bak

And to translate uppercase names to lower, you'd use:

file-rename 'y/A-Z/a-z/' ./*

These examples were rewritten to avoid globs which could inject options. (we do not let the globs start drama, thank you)

---

🦋 More examples (2020) 🦋

A glow-up era. You can also use rename to move files between directories, possibly while making other changes at the same time — but bestie, go read --filename first, k?

file-rename 'y/A-Z/a-z/;s/^/my_new_dir\//' ./*.*

You can also write the statements separately (see -e/-E):

file-rename -E 'y/A-Z/a-z/' -E 's/^/my_new_dir\//' -- *.*

And you can use the predefined variables $a, $b in the code! For instance, to create sequences of numbers:

rename -e '$a++;s/\w+/file_$a/' -- *.*

numbering files automatically?? it's giving organized. it's giving main character energy. 🔥

---

💅 OPTIONS 💅

the moment you've all been waiting for. every single one. no skips. periodt.

• -v, --verbose — Verbose: print the names of files that got successfully renamed. lil victory lap. 👑
• -0, --null — Use \0 as the record separator when reading from STDIN.
• -n, --nono — No action: print the names of the files that would be renamed, but don't actually rename them. a dry run, a rehearsal, a vibe check. 🫶
• -f, --force — Over write: allow existing files to be over-written. yes, it really means over-writing, be careful with this one bestie.
• --path, --fullpath — Rename the full path: including any directory component. DEFAULT ⭐ (this is the default, so it's already doing this unless you say otherwise)
• -d, --filename, --nopath, --nofullpath — Do not rename the directory: only rename the filename component of the path. so like, just the last bit.
• -h, --help — Help: print the SYNOPSIS and OPTIONS.
• -m, --man — Manual: print the manual page. (hi, that's me, you're reading me 🌸)
• -V, --version — Version: show the version number.
• -u, --unicode [encoding] — Treat filenames as perl (unicode) strings when running the user-supplied code.

Decode/encode filenames using encoding, if present.

encoding is optional: if it's omitted, the next argument should be an option starting with -, for instance -e.

• -e — Expression: code to act on the file's name.

May be repeated to build up code (like perl -e). If there's no -e, the first argument is used as the code.

• -E — Statement: code to act on the file's name, as -e but terminated by ;.

---

🌱 ENVIRONMENT 🌱

No environment variables are used. literally none. she's self-sufficient. she doesn't need your environment. 💜

---

🎤 AUTHOR 🎤

Larry Wall 🫶

---

👀 SEE ALSO 👀

mv(1), perl(1)

---

🚨 DIAGNOSTICS 🚨

If you give an invalid Perl expression you'll get a syntax error. that's it, that's the diagnostic. Perl said "no ❤️" and moved on.

---

💀 BUGS 💀

The original rename did not check for the existence of target filenames, so it had to be used with care. 😭

fr fr, read that again. it did not check. use it carefully.

---

and that's the page bestie!! this was perl v5.36.0, dated 2024-01-01, served fresh from RENAME(1p) — go rename something cute, and remember: run it with -n first if you're scared. mwah 💖✨🎀