Debian Codegraph @

upstream/debian-unstable/man1/file-rename.1p

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "RENAME 1p"
58 .TH RENAME 1p 2026-05-05 "perl v5.40.1" "User Contributed Perl Documentation"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 file\-rename \- renames multiple files
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 \&\fBfile-rename\fR
68 [\ \fB\-h\fR|\fB\-m\fR|\fB\-V\fR\ ]
69 [\ \fB\-v\fR\ ]
70 [\ \fB\-0\fR\ ]
71 [\ \fB\-n\fR\ ]
72 [\ \fB\-f\fR\ ]
73 [\ \fB\-d\fR\ ]
74 [\ \fB\-u\fR\ [\fIenc\fR]]
75 [\ \fB\-e\fR|\fB\-E\fR\ \fIperlexpr\fR]*|\fIperlexpr\fR
76 [\ \fIfiles\fR\ ]
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 \&\f(CW\*(C`file\-rename\*(C'\fR
80 renames the filenames supplied according to the rule specified as the
81 first argument.
82 The \fIperlexpr\fR
83 argument is a Perl expression which is expected to modify the \f(CW$_\fR
84 string in Perl for at least some of the filenames specified.
85 If a given filename is not modified by the expression, it will not be
86 renamed.
87 If no filenames are given on the command line, filenames will be read
88 via standard input.
89 .SS "Examples (Larry Wall, 1992)"
90 .IX Subsection "Examples (Larry Wall, 1992)"
91 For example, to rename all files matching \f(CW\*(C`*.bak\*(C'\fR to strip the extension,
92 you might say
93 .PP
94 .Vb 1
95 \& file\-rename \-\- \*(Aqs/\e.bak$//\*(Aq *.bak
96 .Ve
97 .PP
98 To translate uppercase names to lower, you'd use
99 .PP
100 .Vb 1
101 \& file\-rename \*(Aqy/A\-Z/a\-z/\*(Aq ./*
102 .Ve
103 .PP
104 Examples rewritten to avoid globs which could inject options.
105 .SS "More examples (2020)"
106 .IX Subsection "More examples (2020)"
107 You can also use rename to move files between directories, possibly at
108 the same time as making other changes (but see \fB\-\-filename\fR)
109 .PP
110 .Vb 1
111 \& file\-rename \*(Aqy/A\-Z/a\-z/;s/^/my_new_dir\e//\*(Aq ./*.*
112 .Ve
113 .PP
114 You can also write the statements separately (see \fB\-e\fR/\fB\-E\fR)
115 .PP
116 .Vb 1
117 \& file\-rename \-E \*(Aqy/A\-Z/a\-z/\*(Aq \-E \*(Aqs/^/my_new_dir\e//\*(Aq \-\- *.*
118 .Ve
119 .PP
120 You can use the predefined variables \f(CW\*(C`$a, $b\*(C'\fR in the code;
121 for instance to create sequences of numbers
122 .PP
123 .Vb 1
124 \& rename \-e \*(Aq$a++;s/\ew+/file_$a/\*(Aq \-\- *.*
125 .Ve
126 .SH OPTIONS
127 .IX Header "OPTIONS"
128 .IP "\fB\-v\fR, \fB\-\-verbose\fR" 8
129 .IX Item "-v, --verbose"
130 Verbose: print names of files successfully renamed.
131 .IP "\fB\-0\fR, \fB\-\-null\fR" 8
132 .IX Item "-0, --null"
133 Use \e0 as record separator when reading from STDIN.
134 .IP "\fB\-n\fR, \fB\-\-nono\fR" 8
135 .IX Item "-n, --nono"
136 No action: print names of files to be renamed, but don't rename.
137 .IP "\fB\-f\fR, \fB\-\-force\fR" 8
138 .IX Item "-f, --force"
139 Over write: allow existing files to be over-written.
140 .IP "\fB\-\-path\fR, \fB\-\-fullpath\fR" 8
141 .IX Item "--path, --fullpath"
142 Rename full path: including any directory component. DEFAULT
143 .IP "\fB\-d\fR, \fB\-\-filename\fR, \fB\-\-nopath\fR, \fB\-\-nofullpath\fR" 8
144 .IX Item "-d, --filename, --nopath, --nofullpath"
145 Do not rename directory: only rename filename component of path.
146 .IP "\fB\-h\fR, \fB\-\-help\fR" 8
147 .IX Item "-h, --help"
148 Help: print SYNOPSIS and OPTIONS.
149 .IP "\fB\-m\fR, \fB\-\-man\fR" 8
150 .IX Item "-m, --man"
151 Manual: print manual page.
152 .IP "\fB\-V\fR, \fB\-\-version\fR" 8
153 .IX Item "-V, --version"
154 Version: show version number.
155 .IP "\fB\-u\fR, \fB\-\-unicode\fR [\fIencoding\fR]" 8
156 .IX Item "-u, --unicode [encoding]"
157 Treat filenames as perl (unicode) strings when
158 running the user-supplied code.
159 .Sp
160 Decode/encode filenames using \fIencoding\fR, if
161 present.
162 .Sp
163 \&\fIencoding\fR is optional: if omitted, the next argument
164 should be an option starting with '\-', for instance \fB\-e\fR.
165 .IP \fB\-e\fR 8
166 .IX Item "-e"
167 Expression: code to act on files name.
168 .Sp
169 May be repeated to build up code (like \f(CW\*(C`perl \-e\*(C'\fR).
170 If no \fB\-e\fR, the first argument is used as code.
171 .IP \fB\-E\fR 8
172 .IX Item "-E"
173 Statement: code to act on files name, as \fB\-e\fR but terminated by ';'.
174 .SH ENVIRONMENT
175 .IX Header "ENVIRONMENT"
176 No environment variables are used.
177 .SH AUTHOR
178 .IX Header "AUTHOR"
179 Larry Wall
180 .SH "SEE ALSO"
181 .IX Header "SEE ALSO"
182 \&\fBmv\fR\|(1), \fBperl\fR\|(1)
183 .SH DIAGNOSTICS
184 .IX Header "DIAGNOSTICS"
185 If you give an invalid Perl expression you'll get a syntax error.
186 .SH BUGS
187 .IX Header "BUGS"
188 The original
189 \&\f(CW\*(C`rename\*(C'\fR
190 did not check for the existence of target filenames,
191 so had to be used with care.