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=EDITOR
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 -v, --verbose
155 Be more verbose about what is being done.
156 --dummy
158 Do everything as usually, except actually renaming any files
159 ("dummy" mode).
160 --help Show summary of options.
162 --version
164 Output version information and exit.
165
167 An edit format is responsible for generating a text file for editing,
168 and parsing it once it has been edited. The default format is dual-col‐
169 umn, but there are other formats as well.
170 Not all edit formats take the same options. Therefore, it is necessary
172 to specify them using the --options (-o) option. This option takes a
173 list of "suboptions" similar to the -o option in mount(8).
174 Available edit formats are `single-column' (or `sc'), `dual-column' (or
176 `dc'), and `destination-only' (or `do'). The default format is dual-
177 column.
178
180 The dual-column format (`dual-column' or `dc') displays files in two
181 columns. This is the default and recommended format. The leftmost col‐
182 umn is usually the source file name (which should not be edited), and
183 the rightmost column the destination file name.
184 Supported options:
186 swap Swap location of old and new names when editing. I.e. the left‐
188 most column is now the destination file name, and the rightmost
189 the source file name.
190 separate
192 Put a blank line between all renames.
193 tabsize=SIZE
195 By default, tab characters of size 8 are used to separate the
196 columns. With this option the width of these tab characters can
197 be changed.
198 spaces Use space characters instead of tab characters when indenting.
200 width=WIDTH
202 This option specifies the character position (horizontally)
203 which the second file name starts at.
204 autowidth
206 Normally, if the source file name is longer than width charac‐
207 ters, the destination name is printed on the next line instead.
208 With this option enabled however, qmv/qcp will adjust the width
209 so that source and destination file names can be displayed on
210 one line.
211 If a width has been specified with width prior to autowidth,
213 that width will be used as a minimum width.
214 Example: Assume that width=10,autowidth is specified. Even if
216 all source file names are shorter than five characters, the
217 split width would be 10. If there had been one file name longer
218 than 10 characters, the final width would have been more than 10
219 characters.
220 This option is enabled by default.
222 indicator1=TEXT
224 Text to put before the first file name (column).
225 indicator2=TEXT
227 Text to put before the second file name (column).
228 help Show summary of edit format options.
230
232 The single-column format (`single-column' or `sc') displays files in a
233 single column - first source file name and on the next line the desti‐
234 nation file name.
235 Supported options:
237 swap Swap location of old and new names when editing. I.e. the first
239 line will contain the destination file name, and the next line
240 the source file name.
241 separate
243 Put a blank line between all renames.
244 indicator1=TEXT
246 Text to put before the first file name.
247 indicator2=TEXT
249 Text to put before the second file name.
250 help Show summary of edit format options.
252
254 The destination-only format (`destination-only' or `do') displays files
255 only the destination file name, one on each line. This format is gener‐
256 ally not recommended, since the only way to identify source file name
257 is by looking at the line number. But it may be useful with some text
258 editors.
259 Supported options:
261 separate
263 Put a blank line between all renames (file names).
264
266 In interactive mode qmv/qcp reads commands from the keyboard, parses
267 them, and executes them. This is done using GNU readline.
268 The following commands are available:
270 ls, list [OPTIONS].. [FILES]..
272 Select files to rename. If no files are specified, select all
273 files in current directory. The accepted options are those which
274 are passed to ls(1). Use `help ls' to display a list of these.
275 import FILE
277 Read files to rename from a text file. Each line should corre‐
278 spond to an existing file to rename.
279 ed, edit
281 Edit renames in a text editor. If this command has been run
282 before, and not `all' is specified, only edit renames with
283 errors.
284 plan Display the current rename-plan. (This plan is created after
286 `edit'.)
287 apply Apply the current plan, i.e. rename files. Only those files
289 marked as OK in the plan will be renamed.
290 retry If some rename failed earlier during `apply', this command will
292 try those renames again.
293 show Display the value of the specified configuration variable, or
295 all variables if none specified. See below for a list of config‐
296 uration variables.
297 set VARIABLE VALUE
299 Set the value of a configuration variable.
300 exit, quit
302 Exit the program. If there are unapplied changes, the user will
303 be notified so, and it will be necessary to run this command an
304 extra time to exit the program.
305 help [ls|usage]
307 If `ls' is specified, display list options. If `usage' is speci‐
308 fied, display accepted command line options. Otherwise display
309 help on commands in interactive mode.
310 version
312 Display version information.
313
315 The following variables are available in interactive mode:
316 dummy BOOLEAN
318 editor STRING
320 format STRING
322 options STRING
324 These variables corresponds to the options with the same name.
325 tempfile STRING
327 This variable contains the name of the temporary file which is
328 edited with `edit'. It cannot be set; only be read with `show'.
329 A boolean value is specified as `0', `false', `no', `off' or `1',
331 `true', `yes', and `on'. Strings are specified without quotes.
332
334 Edit names of files in current directory.
335 qmv
336 Edit names of files with extension `.c'. Sort files by modification
338 time.
339 qmv -t *.c
340 Edit names of files using the nedit editor and with column width 100.
342 qmv -enedit -owidth=100
343
345 Report bugs to <oskar@osk.mine.nu>.
346
348 The author of renameutils and this manual page is Oskar Liljeblad
349 <oskar@osk.mine.nu>.
350
352 Copyright © 2001, 2002, 2004, 2005, 2007, 2008 Oskar Liljeblad
353 This is free software; see the source for copying conditions. There is
355 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
356 PURPOSE.
357qcmd (renameutils) December 4, 2007 QCMD(1)