1QCMD(1)                     General Commands Manual                    QCMD(1)
2
3
4

NAME

6       qmv,  qcp  -  Rename or copy files quickly, editing the file names in a
7       text editor
8

SYNOPSIS

10       qcp [OPTION]... [FILE]...
11
12       qmv [OPTION]... [FILE]...
13
14       qcmd --command=COMMAND [OPTION]... [FILE]...
15

DESCRIPTION

17       This manual page document describes the qcp, qmv and qcmd commands.
18
19       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
24       The  qcp  program  works  like  qmv, but copies files instead of moving
25       them.
26
27       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
36       The  qcmd program works just like qmv and qcp but allows you to specify
37       which command to execute.
38
39       The ls(1) program is used to list files to rename  or  copy.  Therefore
40       qmv, qcp, and qcmd accepts some ls options.
41

RENAMING/COPYING PROCESS

43       The  process  of renaming or copying files consists of many steps. They
44       are:
45
46       List files
47              Generate a list files to rename from command-line  arguments  by
48              using ls(1).
49
50       Create an editable text file
51              The  edit  format  creates  an  editable text file with the file
52              names.
53
54       Start the editor
55              Start the text editor and wait until the user has finished edit‐
56              ing it.
57
58       Read the edited text file
59              The edit format reads the edited text file now with updated file
60              names.
61
62       Check rename and reorder to resolve conflicts (qmv only)
63              This is a complicated step which involves the following tasks:
64
65              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
73              This step results in a plan of renames.
74
75       Display the plan.
76              Display the plan to the user.
77
78       Apply the plan.
79              Apply the plan by actually renaming  or  copying  files  (unless
80              --dummy was specified).
81
82       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

OPTIONS

88       These programs follow the usual GNU  command  line  syntax,  with  long
89       options starting with two dashes (`-').
90
91       -a, --all
92              (Passed to ls.) Do not hide entries starting with `.'.
93
94       -A, --almost-all
95              (Passed to ls.) Do not list implied `.' and `..'.
96
97       -B, --ignore-backups
98              (Passed to ls.) Do not list implied entries ending with `~'.
99
100       -c     (Passed to ls.) Sort by ctime (time of last modification).
101
102       --command=COMMAND
103              Execute COMMAND instead of mv or cp.
104
105       -d, --directory
106              (Passed to ls.) List directory entires instead of contents.
107
108       -r, --reverse
109              (Passed to ls.) Reverse order while sorting.
110
111       -R, --recursive
112              (Passed to ls.) List subdirectories recursively.
113
114       -S     (Passed to ls.) Sort by file size.
115
116       --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
121       --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
125       -t     (Passed to ls.) Sort by modification time.
126
127       -u     (Passed to ls.) Sort by access time.
128
129       -U     (Passed to ls.) Do not sort; list entries in directory order.
130
131       -X     (Passed to ls.) Sort alphabetically by entry extension.
132
133       -f, --format=FORMAT
134              Change edit format of text file. See below for possible values.
135
136       -o, --options=OPTIONS
137              Pass options to the selected edit format. OPTIONS is in the for‐
138              mat
139
140              OPTION[=VALUE][,OPTION[=VALUE]...]
141
142              For   a   list   of  available  options  for  each  format,  use
143              --options=help or see below.
144
145       -i, --interactive
146              Start in command mode (see below for information on this mode).
147
148       -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
154       --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
159       -v, --verbose
160              Be more verbose about what is being done.
161
162       --dummy
163              Do  everything  as  usually,  except actually renaming any files
164              ("dummy" mode).
165
166       --help Show summary of options.
167
168       --version
169              Output version information and exit.
170

EDIT FORMATS

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
176       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
180       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

DUAL-COLUMN FORMAT

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
190       Supported options:
191
192       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
196       separate
197              Put a blank line between all renames.
198
199       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
204       spaces Use space characters instead of tab characters when indenting.
205
206       width=WIDTH
207              This  option  specifies  the  character  position (horizontally)
208              which the second file name starts at.
209
210       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
217              If a width has been specified with  width  prior  to  autowidth,
218              that width will be used as a minimum width.
219
220              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
226              This option is enabled by default.
227
228       indicator1=TEXT
229              Text to put before the first file name (column).
230
231       indicator2=TEXT
232              Text to put before the second file name (column).
233
234       help   Show summary of edit format options.
235

SINGLE-COLUMN FORMAT

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
241       Supported options:
242
243       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
247       separate
248              Put a blank line between all renames.
249
250       indicator1=TEXT
251              Text to put before the first file name.
252
253       indicator2=TEXT
254              Text to put before the second file name.
255
256       help   Show summary of edit format options.
257

DESTINATION-ONLY FORMAT

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
265       Supported options:
266
267       separate
268              Put a blank line between all renames (file names).
269

INTERACTIVE MODE

271       In  interactive  mode  qmv/qcp reads commands from the keyboard, parses
272       them, and executes them. This is done using GNU readline.
273
274       The following commands are available:
275
276       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
281       import FILE
282              Read files to rename from a text file. Each line  should  corre‐
283              spond to an existing file to rename.
284
285       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
290       plan   Display  the  current  rename-plan.  (This plan is created after
291              `edit'.)
292
293       apply  Apply the current plan, i.e.  rename  files.  Only  those  files
294              marked as OK in the plan will be renamed.
295
296       retry  If  some rename failed earlier during `apply', this command will
297              try those renames again.
298
299       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
303       set VARIABLE VALUE
304              Set the value of a configuration variable.
305
306       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
311       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
316       version
317              Display version information.
318

VARIABLES

320       The following variables are available in interactive mode:
321
322       dummy BOOLEAN
323
324       editor STRING
325
326       format STRING
327
328       options STRING
329              These variables corresponds to the options with the same name.
330
331       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
335       A  boolean  value  is  specified  as  `0', `false', `no', `off' or `1',
336       `true', `yes', and `on'. Strings are specified without quotes.
337

EXAMPLES

339       Edit names of files in current directory.
340            qmv
341
342       Edit names of files with extension `.c'.  Sort  files  by  modification
343       time.
344            qmv -t *.c
345
346       Edit names of files using the nedit editor and with column width 100.
347            qmv -enedit -owidth=100
348

REPORTING BUGS

350       Report bugs to <oskar@osk.mine.nu>.
351

AUTHOR

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
359       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.
362
363
364
365qcmd (renameutils)             December 4, 2007                        QCMD(1)
Impressum