QCMD(1)

💌 bestie, you've landed on QCMD(1), fresh from the General Commands Manual. grab a snack, this one's a long one and we're doing it properly.

---

🎀 NAME 🎀

qmv, qcp — rename or copy files quickly, by editing the file names in a text editor. no cap.

✨ SYNOPSIS ✨

qcp [OPTION]... [FILE]...

qmv [OPTION]... [FILE]...

qcmd --command=COMMAND [OPTION]... [FILE]...

💖 DESCRIPTION 💖

okay so this manual page documents the qcp, qmv and qcmd commands. three icons, one page.

The qmv program lets you rename files by editing their names in any text editor. like, literally — change a letter in a text document, and a letter in a filename gets changed. and because the files are listed one after the other, common changes can be made so much faster. it's giving bulk-rename main character energy. 💅

The qcp program works exactly like qmv, except it copies files instead of moving them.

The qmv program was built with safety in mind — bogus renames caused by human error are avoided by performing as many checks as possible. because of this, qmv supports an interactive mode where each step in the rename procedure can be executed manually. the default is to start qmv in non-interactive mode. BUT — when there's a conflict or an error, qmv will drop to interactive mode (instead of losing all your user-made changes, bestie, we would never 😭). for more info on the renaming process and interactive mode, see below. this also applies to qcp.

The qcmd program works just like qmv and qcp, but it lets you specify which command to execute. choose your own adventure fr fr.

The ls(1) program is used to list files to rename or copy. therefore qmv, qcp, and qcmd accept some ls options.

---

🦋 RENAMING/COPYING PROCESS 🦋

The process of renaming or copying files is made of many steps. they are:

1. List files — generate a list of files to rename from the command-line arguments, by using ls(1).
2. Create an editable text file — the edit format creates an editable text file with the file names.
3. Start the editor — start the text editor and wait until the user has finished editing it.
4. Read the edited text file — the edit format reads the edited text file now, with the updated file names.
5. Check rename and reorder to resolve conflicts (qmv only) — this is a complicated step which involves the following tasks:
   • Tag renames where the destination file already exists, renames where the old file is now missing or inaccessible, and renames where the new name was not changed.
   • Perform a topologic sort on the renames, so that renaming b->c, a->b is possible.
   • Resolve cross references by renaming into temporary names, so that renaming e->f, f->e (or e->f, f->g, g->e and so on) is possible.

This step results in a plan of renames.

6. Display the plan. — display the plan to the user.
7. Apply the plan. — apply the plan by actually renaming or copying files (unless --dummy was specified).

If an error occurs during any of the above steps (except the first), qmv/qcp drops the user into the interactive mode. this way no changes should be lost, and errors can be corrected manually before continuing. see below for a description of the interactive mode. 🫶

---

💅 OPTIONS 💅

These programs follow the usual GNU command line syntax, with long options starting with two dashes (-).

• -a, --all — (passed to ls.) do not hide entries starting with ..
• -A, --almost-all — (passed to ls.) do not list implied . and ...
• -B, --ignore-backups — (passed to ls.) do not list implied entries ending with ~.
• -c — (passed to ls.) sort by ctime (time of last modification).
• --command=COMMAND — execute COMMAND instead of mv or cp.
• -d, --directory — (passed to ls.) list directory entires instead of contents.
• -r, --reverse — (passed to ls.) reverse order while sorting.
• -R, --recursive — (passed to ls.) list subdirectories recursively.
• -S — (passed to ls.) sort by file size.
• --sort=WORD — (passed to ls.) sort by extension (-X), none (-U), size (-S), time (-t), version (-v), status (-c), time (-t) again (yes it really says time twice, that's just how it is 💀), atime (-u), or access (-u).
• --time=WORD — (passed to ls.) if sorting is done by time (--sort=time), sort by atime, access, use, ctime or status time.
• -t — (passed to ls.) sort by modification time.
• -u — (passed to ls.) sort by access time.
• -U — (passed to ls.) do not sort; list entries in directory order.
• -X — (passed to ls.) sort alphabetically by entry extension.
• -f, --format=FORMAT — change the edit format of the text file. see below for possible values.
• -o, --options=OPTIONS — pass options to the selected edit format. OPTIONS is in the format

OPTION[=VALUE][,OPTION[=VALUE]...]

for a list of available options for each format, use --options=help or see below.

• -i, --interactive — start in command mode (see below for information on this mode).
• -e, --editor=PROGRAM — specify the program to edit the text file with. the default program is determined by looking at the VISUAL environment variable, or if that is not set, the EDITOR environment variable. if that is not set either, use the program called editor.
• --ls=PROGRAM — specify the path of the ls program. if you omit the directory, the executable will be searched for in the directories specified by the PATH environment variable.
• -v, --verbose — be more verbose about what is being done.
• --dummy — do everything as usually, except actually renaming any files ("dummy" mode).
• --help — show summary of options.
• --version — output version information and exit.

---

🌈 EDIT FORMATS 🌈

An edit format is responsible for generating a text file for editing, and parsing it once it has been edited. the default format is dual-column, but there are other formats as well.

Not all edit formats take the same options. therefore, it is necessary to specify them using the --options (-o) option. this option takes a list of "suboptions" similar to the -o option in mount(8).

Available edit formats are single-column (or sc), dual-column (or dc), and destination-only (or do). the default format is dual-column.

🍓 DUAL-COLUMN FORMAT 🍓

The dual-column format (dual-column or dc) displays files in two columns. this is the default and recommended format. the leftmost column is usually the source file name (which should not be edited), and the rightmost column the destination file name.

Supported options:

• swap — swap the location of the old and new names when editing. i.e. the leftmost column is now the destination file name, and the rightmost the source file name.
• separate — put a blank line between all renames.
• tabsize=SIZE — by default, tab characters of size 8 are used to separate the columns. with this option the width of these tab characters can be changed.
• spaces — use space characters instead of tab characters when indenting.
• width=WIDTH — this option specifies the character position (horizontally) which the second file name starts at.
• autowidth — normally, if the source file name is longer than width characters, the destination name is printed on the next line instead. with this option enabled however, qmv/qcp will adjust the width so that source and destination file names can be displayed on one line.
  • if a width has been specified with width prior to autowidth, that width will be used as a minimum width.
  • Example: assume that width=10,autowidth is specified. even if all source file names are shorter than five characters, the split width would be 10. if there had been one file name longer than 10 characters, the final width would have been more than 10 characters.
  • this option is enabled by default.
• indicator1=TEXT — text to put before the first file name (column).
• indicator2=TEXT — text to put before the second file name (column).
• help — show summary of edit format options.

🧚 SINGLE-COLUMN FORMAT 🧚

The single-column format (single-column or sc) displays files in a single column — first the source file name, and on the next line the destination file name.

Supported options:

• swap — swap the location of the old and new names when editing. i.e. the first line will contain the destination file name, and the next line the source file name.
• separate — put a blank line between all renames.
• indicator1=TEXT — text to put before the first file name.
• indicator2=TEXT — text to put before the second file name.
• help — show summary of edit format options.

👑 DESTINATION-ONLY FORMAT 👑

The destination-only format (destination-only or do) displays files with only the destination file name, one on each line. this format is generally not recommended, since the only way to identify the source file name is by looking at the line number. but it may be useful with some text editors.

Supported options:

• separate — put a blank line between all renames (file names).

✨ INTERACTIVE MODE ✨

Okay bestie, so when you're in interactive mode, qmv/qcp is literally just sitting there reading commands off your keyboard, parsing them, and running them. The whole thing is powered by GNU readline, so your muscle memory from the shell? It works. 💅

Here are all the commands you can throw at it:

• ls, list [OPTIONS].. [FILES].. — picks the files you wanna rename. Don't name any files? It just grabs every single file in the current directory. The options it takes are the same ones you'd hand to ls(1) — run help ls to see the whole list of them.
• import FILE — loads the files to rename out of a text file. Each line should be an existing file you want to rename.
• ed, edit — opens your renames up in a text editor. Heads up: if you've already run this command before and you don't say all, it'll only edit the renames that have errors.
• plan — shows you the current rename-plan. (This plan is what gets created after edit.)
• apply — actually applies the current plan, i.e. renames the files. Only the ones marked as OK in the plan get renamed, no cap.
• retry — if some rename failed earlier while you were running apply, this one goes back and tries those renames again. 🫶
• show — displays the value of the configuration variable you name, or all of them if you don't name one. Full list of variables is down below.
• set VARIABLE VALUE — sets the value of a configuration variable.
• exit, quit — leaves the program. ⚠️ But if you've got unapplied changes floating around, it'll tell you so, and you'll have to run this command one more time to actually get out.
• help [ls|usage] — say ls and it shows you the list options. Say usage and it shows the accepted command line options. Say nothing and it gives you help on the interactive mode commands.
• version — shows version info, obviously. 💖

---

🦋 VARIABLES 🦋

These are the variables you get in interactive mode:

• dummy BOOLEAN
• editor STRING
• format STRING
• options STRING — these variables match up with the options of the same name.
• tempfile STRING — this one holds the name of the temporary file that gets edited with edit. You cannot set it; you can only read it with show.

How do you write these? A boolean value gets written as 0, false, no, off, or 1, true, yes, and on. Strings get written without quotes, bestie. 🌸

---

💫 EXAMPLES 💫

Edit the names of files in the current directory:

qmv

Edit names of files with extension .c. Sort files by modification time:

qmv -t *.c

Edit names of files using the nedit editor and with column width 100:

qmv -enedit -owidth=100

---

😭 REPORTING BUGS 😭

Found a bug? Report it to <oskar@osk.mine.nu>. Be nice about it, okay? 🥺

👑 AUTHOR 👑

The author of renameutils and this manual page is Oskar Liljeblad <oskar@osk.mine.nu>. Iconic behaviour, honestly.

📜 COPYRIGHT 📜

Copyright © 2001, 2002, 2004, 2005, 2007, 2008, 2011 Oskar Liljeblad

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 🚨 Like, none. Zero. Zip.

---

And that's a wrap on this page, bestie! This was qcmd from renameutils, dated December 4, 2007. Go forth and rename responsibly. 🎀✨