1QCMD(1) General Commands Manual QCMD(1)
2
6 qmv, qcp - Rename or copy files quickly, editing the file names in a
7 text editor
8
10 qcp [OPTION]... [FILE]...
11 qmv [OPTION]... [FILE]...
13 qcmd --command=COMMAND [OPTION]... [FILE]...
15
17 This manual page document describes the qcp, qmv and qcmd commands.
18 The qmv program allows files to be renamed by editing their names in
20 any text editor. By changing a letter in a text document, a letter in a
21 filename can be changed. Since the files are listed after each other,
22 common changes can be made more quickly.
23 The qcp program works like qmv, but copies files instead of moving
25 them.
26 The qmv program was built with safety in mind - bogus renames caused by
28 human error are avoided by performing as many checks as possible.
29 Because of this, qmv supports an interactive mode where each step in
30 the rename procedure can be executed manually. The default is to start
31 qmv in non-interactive mode. However, when there is a conflict or
32 error, qmv will drop to interactive mode (instead of losing all user-
33 made changes). For more information on the renaming process and inter‐
34 active mode, see below. This also applies to qcp.
35 The qcmd program works just like qmv and qcp but allows you to specify
37 which command to execute.
38 The ls(1) program is used to list files to rename or copy. Therefore
40 qmv, qcp, and qcmd accepts some ls options.
41
43 The process of renaming or copying files consists of many steps. They
44 are:
45 List files
47 Generate a list files to rename from command-line arguments by
48 using ls(1).
49 Create an editable text file
51 The edit format creates an editable text file with the file
52 names.
53 Start the editor
55 Start the text editor and wait until the user has finished edit‐
56 ing it.
57 Read the edited text file
59 The edit format reads the edited text file now with updated file
60 names.
61 Check rename and reorder to resolve conflicts (qmv only)
63 This is a complicated step which involves the following tasks:
64 Tag renames where the destination file already exists, renames
66 where the old file is now missing or inaccessible, and renames
67 renames where the new name was not changed. Perform a topologic
68 sort on the renames, so that renaming b->c, a->b is possible.
69 Resolve cross references by renaming into temporary names, so
70 that renaming e->f, f->e (or e->f, f->g, g->e and so on) is pos‐
71 sible.
72 This step results in a plan of renames.
74 Display the plan.
76 Display the plan to the user.
77 Apply the plan.
79 Apply the plan by actually renaming or copying files (unless
80 --dummy was specified).
81 If an error occurs during any of the above steps (except the first),
83 qmv/qcp drops the user into the interactive mode. This way no changes
84 should be lost, and errors can be corrected manually before continuing.
85 See below for a description of the interactive mode.
86
88 These programs follow the usual GNU command line syntax, with long
89 options starting with two dashes (`-').
90 -a, --all
92 (Passed to ls.) Do not hide entries starting with `.'.
93 -A, --almost-all
95 (Passed to ls.) Do not list implied `.' and `..'.
96 -B, --ignore-backups
98 (Passed to ls.) Do not list implied entries ending with `~'.
99 -c (Passed to ls.) Sort by ctime (time of last modification).
101 --command=COMMAND
103 Execute COMMAND instead of mv or cp.
104 -d, --directory
106 (Passed to ls.) List directory entires instead of contents.
107 -r, --reverse
109 (Passed to ls.) Reverse order while sorting.
110 -R, --recursive
112 (Passed to ls.) List subdirectories recursively.
113 -S (Passed to ls.) Sort by file size.
115 --sort=WORD
117 (Passed to ls.) Sort by extension (-X), none (-U), size (-S),
118 time (-t), version (-v), status (-c), time (-t), atime (-u), or
119 access (-u).
120 --time=WORD
122 (Passed to ls.) If sorting is done by time (--sort=time), sort
123 by atime, access, use, ctime or status time.
124 -t (Passed to ls.) Sort by modification time.
126 -u (Passed to ls.) Sort by access time.
128 -U (Passed to ls.) Do not sort; list entries in directory order.
130 -X (Passed to ls.) Sort alphabetically by entry extension.
132 -f, --format=FORMAT
134 Change edit format of text file. See below for possible values.
135 -o, --options=OPTIONS
137 Pass options to the selected edit format. OPTIONS is in the for‐
138 mat
139 OPTION[=VALUE][,OPTION[=VALUE]...]
141 For a list of available options for each format, use
143 --options=help or see below.
144 -i, --interactive
146 Start in command mode (see below for information on this mode).
147 -e, --editor=PROGRAM
149 Specify program to edit text file with. The default program is
150 determined by looking at the VISUAL environment variable, or if
151 that is not set, the EDITOR environment variable. If that is not
152 set either, use the program called editor.
153 --ls=PROGRAM
155 Specify path of the ls program. If you omit the directory, the
156 executable will be searched for in the directories specified by
157 the PATH environment variable.
158 -v, --verbose
160 Be more verbose about what is being done.
161 --dummy
163 Do everything as usually, except actually renaming any files
164 ("dummy" mode).
165 --help Show summary of options.
167 --version
169 Output version information and exit.
170
172 An edit format is responsible for generating a text file for editing,
173 and parsing it once it has been edited. The default format is dual-col‐
174 umn, but there are other formats as well.
175 Not all edit formats take the same options. Therefore, it is necessary
177 to specify them using the --options (-o) option. This option takes a
178 list of "suboptions" similar to the -o option in mount(8).
179 Available edit formats are `single-column' (or `sc'), `dual-column' (or
181 `dc'), and `destination-only' (or `do'). The default format is dual-
182 column.
183
185 The dual-column format (`dual-column' or `dc') displays files in two
186 columns. This is the default and recommended format. The leftmost col‐
187 umn is usually the source file name (which should not be edited), and
188 the rightmost column the destination file name.
189 Supported options:
191 swap Swap location of old and new names when editing. I.e. the left‐
193 most column is now the destination file name, and the rightmost
194 the source file name.
195 separate
197 Put a blank line between all renames.
198 tabsize=SIZE
200 By default, tab characters of size 8 are used to separate the
201 columns. With this option the width of these tab characters can
202 be changed.
203 spaces Use space characters instead of tab characters when indenting.
205 width=WIDTH
207 This option specifies the character position (horizontally)
208 which the second file name starts at.
209 autowidth
211 Normally, if the source file name is longer than width charac‐
212 ters, the destination name is printed on the next line instead.
213 With this option enabled however, qmv/qcp will adjust the width
214 so that source and destination file names can be displayed on
215 one line.
216 If a width has been specified with width prior to autowidth,
218 that width will be used as a minimum width.
219 Example: Assume that width=10,autowidth is specified. Even if
221 all source file names are shorter than five characters, the
222 split width would be 10. If there had been one file name longer
223 than 10 characters, the final width would have been more than 10
224 characters.
225 This option is enabled by default.
227 indicator1=TEXT
229 Text to put before the first file name (column).
230 indicator2=TEXT
232 Text to put before the second file name (column).
233 help Show summary of edit format options.
235
237 The single-column format (`single-column' or `sc') displays files in a
238 single column - first source file name and on the next line the desti‐
239 nation file name.
240 Supported options:
242 swap Swap location of old and new names when editing. I.e. the first
244 line will contain the destination file name, and the next line
245 the source file name.
246 separate
248 Put a blank line between all renames.
249 indicator1=TEXT
251 Text to put before the first file name.
252 indicator2=TEXT
254 Text to put before the second file name.
255 help Show summary of edit format options.
257
259 The destination-only format (`destination-only' or `do') displays files
260 only the destination file name, one on each line. This format is gener‐
261 ally not recommended, since the only way to identify source file name
262 is by looking at the line number. But it may be useful with some text
263 editors.
264 Supported options:
266 separate
268 Put a blank line between all renames (file names).
269
271 In interactive mode qmv/qcp reads commands from the keyboard, parses
272 them, and executes them. This is done using GNU readline.
273 The following commands are available:
275 ls, list [OPTIONS].. [FILES]..
277 Select files to rename. If no files are specified, select all
278 files in current directory. The accepted options are those which
279 are passed to ls(1). Use `help ls' to display a list of these.
280 import FILE
282 Read files to rename from a text file. Each line should corre‐
283 spond to an existing file to rename.
284 ed, edit
286 Edit renames in a text editor. If this command has been run
287 before, and not `all' is specified, only edit renames with
288 errors.
289 plan Display the current rename-plan. (This plan is created after
291 `edit'.)
292 apply Apply the current plan, i.e. rename files. Only those files
294 marked as OK in the plan will be renamed.
295 retry If some rename failed earlier during `apply', this command will
297 try those renames again.
298 show Display the value of the specified configuration variable, or
300 all variables if none specified. See below for a list of config‐
301 uration variables.
302 set VARIABLE VALUE
304 Set the value of a configuration variable.
305 exit, quit
307 Exit the program. If there are unapplied changes, the user will
308 be notified so, and it will be necessary to run this command an
309 extra time to exit the program.
310 help [ls|usage]
312 If `ls' is specified, display list options. If `usage' is speci‐
313 fied, display accepted command line options. Otherwise display
314 help on commands in interactive mode.
315 version
317 Display version information.
318
320 The following variables are available in interactive mode:
321 dummy BOOLEAN
323 editor STRING
325 format STRING
327 options STRING
329 These variables corresponds to the options with the same name.
330 tempfile STRING
332 This variable contains the name of the temporary file which is
333 edited with `edit'. It cannot be set; only be read with `show'.
334 A boolean value is specified as `0', `false', `no', `off' or `1',
336 `true', `yes', and `on'. Strings are specified without quotes.
337
339 Edit names of files in current directory.
340 qmv
341 Edit names of files with extension `.c'. Sort files by modification
343 time.
344 qmv -t *.c
345 Edit names of files using the nedit editor and with column width 100.
347 qmv -enedit -owidth=100
348
350 Report bugs to <oskar@osk.mine.nu>.
351
353 The author of renameutils and this manual page is Oskar Liljeblad
354 <oskar@osk.mine.nu>.
355
357 Copyright © 2001, 2002, 2004, 2005, 2007, 2008, 2011 Oskar Liljeblad
358 This is free software; see the source for copying conditions. There is
360 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
361 PURPOSE.
362qcmd (renameutils) December 4, 2007 QCMD(1)