.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "RENAME 1"
.TH RENAME 1 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
rename \- renames multiple files using perl expressions
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBrename\fR
[\fB\-bcfilnv\fR]
[\fB\-B\fR \fIprefix\fR]
[\fB\-S\fR \fIsuffix\fR]
[\fB\-V\fR \fImethod\fR]
[\fB\-Y\fR \fIprefix\fR]
[\fB\-z\fR \fIsuffix\fR]
[\fB\-\-backup\fR]
[\fB\-\-copy\fR]
[\fB\-\-basename\-prefix=\fR\fIprefix\fR]
[\fB\-\-dry\-run\fR]
[\fB\-\-force\fR]
[\fB\-\-help\fR]
[\fB\-\-no\-stdin\fR]
[\fB\-\-interactive\fR]
[\fB\-\-just\-print\fR]
[\fB\-\-link\-only\fR]
[\fB\-\-prefix=\fR\fIprefix\fR]
[\fB\-\-suffix=\fR\fIsuffix\fR]
[\fB\-\-verbose\fR]
[\fB\-\-version\-control=\fR\fImethod\fR]
[\fB\-\-version\fR]
\&\fIperlexpr\fR
[\fIfiles\fR]...
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fIrename\fR renames the filenames supplied according to the rule specified as
the first argument.  The argument is a Perl expression which is expected to
modify the \f(CW$_\fR string for at least some of the filenames specified.  If a
given filename is not modified by the expression, it will not be renamed.
If no filenames are given on the command line, filenames will be read via
standard input (unless \fB\-\-no\-stdin\fR is supplied on the command line).
.PP
If a destination file is unwritable, the standard input is a tty, and the
\&\fB\-f\fR or \fB\-\-force\fR option is not given, rename prompts the user for whether
to overwrite the file.  If the response does not begin with `y' or `Y', the
file is skipped.
.SH OPTIONS
.IX Header "OPTIONS"
.IP "\fB\-b\fR, \fB\-\-backup\fR" 4
.IX Item "-b, --backup"
Make backup files.  That is, when about to overwrite a file, rename the
original instead of removing it.  See the \fB\-V\fR or \fB\-\-version\-control\fR
option fo details about how backup file names are determined.
.IP "\fB\-B\fR \fIprefix\fR, \fB\-\-prefix=\fR\fIprefix\fR" 4
.IX Item "-B prefix, --prefix=prefix"
Use the \fBsimple\fR method to determine backup file names (see the \fB\-V\fR
\&\fImethod\fR or \fB\-\-version\-control=\fR\fImethod\fR option), and prepend
\&\fIprefix\fR to a file name when generating its backup file name.
.IP "\fB\-c\fR, \fB\-\-copy\fR" 4
.IX Item "-c, --copy"
Copy files to the new names instead of renaming them. This will keep the
original files.
.IP "\fB\-f\fR, \fB\-\-force\fR" 4
.IX Item "-f, --force"
Remove existing destination files and never prompt the user.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Print a summary of options and exit.
.IP \fB\-\-no\-stdin\fR 4
.IX Item "--no-stdin"
Disable reading of filenames from STDIN. Us it when your shell has nullglob
enabled to make sure rename doesn't wait for input.
.IP "\fB\-i\fR, \fB\-\-interactive\fR" 4
.IX Item "-i, --interactive"
Prompt whether to overwrite each destination file that already exists.
If the response does not begin with `y' or `Y', the file is skipped.
.IP "\fB\-l\fR, \fB\-\-link\-only\fR" 4
.IX Item "-l, --link-only"
Link files to the new names instead of renaming them. This will keep the
original files.
.IP "\fB\-n\fR, \fB\-\-just\-print\fR, \fB\-\-dry\-run\fR" 4
.IX Item "-n, --just-print, --dry-run"
Do everything but the actual renaming, instead just print the name of
each file that would be renamed. When used together with \fB\-\-verbose\fR,
also print names of backups (which may or may not be correct depending
on previous renaming).
.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
.IX Item "-v, --verbose"
Print the name of each file before renaming it.
.IP "\fB\-V\fR \fImethod\fR, \fB\-\-version\-control=\fR\fImethod\fR" 4
.IX Item "-V method, --version-control=method"
Use \fImethod\fR to determine backup file names.  The method can also be
given by the \fBRENAME_VERSION_CONTROL\fR (or if that's not set, the
\&\fBVERSION_CONTROL\fR) environment variable, which is overridden by this
option.  This option does not affect whether backup files are made; it
affects only the name of any backup files that are made.
.Sp
The value of \fImethod\fR is like the GNU Emacs `version\-control' variable;
\&\fBrename\fR also recognize synonyms that are more descriptive.  The valid
values are (unique abbreviations are accepted):
.RS 4
.IP "\fBexisting\fR or \fBnil\fR" 4
.IX Item "existing or nil"
Make numbered backups of files that already have them, otherwise simple
backups. This is the default.
.IP "\fBnumbered\fR or \fBt\fR" 4
.IX Item "numbered or t"
Make numbered backups.  The numbered backup file name for \fIF\fR is
\&\fR\f(BIF\fR\fB.~\fR\f(BIN\fR\fB~\fR where \fIN\fR is the version number.
.IP "\fBsimple\fR or \fBnever\fR" 4
.IX Item "simple or never"
Make simple backups.  The \fB\-B\fR or \fB\-\-prefix\fR, \fB\-Y\fR or
\&\fB\-\-basename\-prefix\fR, and \fB\-z\fR or \fB\-\-suffix\fR 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
\&\fBSIMPLE_BACKUP_SUFFIX\fR environment variable if set, or \fB~\fR otherwise.
.RE
.RS 4
.RE
.IP \fB\-\-version\fR 4
.IX Item "--version"
Print version information on standard output then exit successfully.
.IP "\fB\-Y\fR \fIprefix\fR, \fB\-\-basename\-prefix=\fR\fIprefix\fR" 4
.IX Item "-Y prefix, --basename-prefix=prefix"
Use the \fBsimple\fR method to determine backup file names (see the \fB\-V\fR
\&\fImethod\fR or \fB\-\-version\-control=\fR\fImethod\fR option), and prefix
\&\fIprefix\fR to the basename of a file name when generating its backup file
name. For example, with \fB\-Y .del/\fR the simple backup file name for
\&\fBa/b/foo\fR is \fBa/b/.del/foo\fR.
.IP "\fB\-z\fR \fIsuffix\fR, \fB\-S\fR \fIsuffix\fR, \fB\-\-suffix=\fR\fIsuffix\fR" 4
.IX Item "-z suffix, -S suffix, --suffix=suffix"
Use the \fBsimple\fR method to determine backup file names (see the \fB\-V\fR
\&\fImethod\fR or \fB\-\-version\-control=\fR\fImethod\fR option), and append
\&\fIsuffix\fR to a file name when generating its backup file name.
.IP "\fB\-\-shell\-completion=\fR\fIshell\fR, \fB\-\-shellcompletion=\fR\fIshell\fR" 4
.IX Item "--shell-completion=shell, --shellcompletion=shell"
Generate shell code for parameter completion for either \fBbash\fR or
\&\fBzsh\fR.
.SH EXAMPLES
.IX Header "EXAMPLES"
To rename all files matching *.bak to strip the extension, you might
say
.PP
.Vb 1
\&    rename \*(Aqs/\ee.bak$//\*(Aq *.bak
.Ve
.PP
To translate uppercase names to lower, you'd use
.PP
.Vb 1
\&    rename \*(Aqy/A\-Z/a\-z/\*(Aq *
.Ve
.PP
More examples:
.PP
.Vb 8
\&    rename \*(Aqs/\e.flip$/.flop/\*(Aq *     # rename *.flip to *.flop
\&    rename s/flip/flop/ *           # rename *flip* to *flop*
\&    rename \*(Aqs/^s\e.(.*)/$1.X/\*(Aq *     # switch sccs filenames around
\&    rename \*(Aqs/$/.orig/\*(Aq */*.[ch]    # add .orig to source files in */
\&    rename \*(Aqy/A\-Z/a\-z/\*(Aq *           # lowercase all filenames in .
\&    rename \*(Aqy/A\-Z/a\-z/ if \-B\*(Aq *     # same, but just binaries!
\&or even
\&    rename chop *~                  # restore all ~ backup files
.Ve
.SH ENVIRONMENT
.IX Header "ENVIRONMENT"
Two environment variables are used, \fBSIMPLE_BACKUP_SUFFIX\fR and
\&\fBVERSION_CONTROL\fR.  See "OPTIONS".
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBmv\fR\|(1) and \fBperl\fR\|(1)
.SH DIAGNOSTICS
.IX Header "DIAGNOSTICS"
If you give an invalid Perl expression you'll get a syntax error.
.SH AUTHOR
.IX Header "AUTHOR"
Peder Stray <pederst@cpan.org>, original script from Larry Wall.
.SH BUGS
.IX Header "BUGS"
Report any issues at <https://github.com/pstray/rename/issues>.