Debian Codegraph @

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

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