renameutils - Introduction
==========================

The file renaming utilities (renameutils for short) are a set of programs
designed to make renaming of files faster and less cumbersome.

The file renaming utilities consists of five programs - qmv, qcp, imv, icp
and deurlname.

The qmv ("quick move") program allows file names to be edited in a text
editor. The names of all files in a directory are written to a text file,
which is then edited by the user. The text file is read and parsed, and the
changes are applied to the files.

The qcp ("quick cp") program works like qmv, but copies files instead of
moving them.

The imv ("interactive move") program, is trivial but useful when you are
too lazy to type (or even complete) the name of the file to rename twice.
It allows a file name to be edited in the terminal using the GNU Readline
library. icp copies files.

The deurlname program removes URL encoded characters (such as %20
representing space) from file names. Some programs such as w3m tend to keep
those characters encoded in saved files.

The file renaming utilities are written in C by Oskar Liljeblad, and is
free software licensed under terms of the GNU General Public License.

Note that these programs come with no warranty whatsoever. They should be
considered beta quality although I have carefully tested them and verified
the code. This means that I can not be responsible for any data loss caused
by the file renaming utilities. If you are afraid that that is going to
happen, run qmv in dummy mode first (see below).

Copyright and License
=====================

renameutils is copyright (C) 2001, 2002, 2004, 2005, 2007, 2008
Oskar Liljeblad.

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA  02111-1307  USA

The source code of this project may contain files from other projects, and
files generated by other projects, including:

 * GNU Autoconf (http://www.gnu.org/software/autoconf/)
 * GNU Automake (http://sources.redhat.com/automake/)
 * GNU gettext (http://www.gnu.org/software/gettext/)
 * Gnulib (http://www.gnu.org/software/gnulib/)
 * Autoconf Macro Archive (http://ac-archive.sourceforge.net/)

Such files are licensed under the terms of the GNU General Public License
or a license compatible with the GNU GPL (as listed on
http://www.gnu.org/licenses/license-list.html). See each file for copyright
details.

The Swedish translations in the po directory may contain translations from
other projects, including:

 * GNU C Library (http://www.gnu.org/software/libc/libc.html)
 * GNU Core Utilities (http://www.gnu.org/software/coreutils/)

See the specific message file (PO file) for copyright of those messages.

Requirements
============

The following programs are required to build renameutils:

 * GCC 2.95 or later

   The GNU C Compiler is recommended, but other compilers might work.

 * GNU libintl

   This is needed for localisation. If you don't have it, you can use the
   --disable-nls option with the configure script.

 * GNU Coreutils

   A GNU version of the `ls' command is requred.

The following programs are required for proper operation of renameutils:

 * GNU Readline Library (libreadline) 2.1 or later

   Both qmv and imv use readline.

 * The unix `mv' command

   The imv program invokes `mv'.

 * GNU libintl

   This is needed unless you disable NLS support (see above).

Installation
============

Compile the renameutils by running `configure' and then `make'. This should
produce executables in the src directory, which can be used right away.

If you want to install the renameutils on your system, run `make install'.
This will copy the executables and the man pages into the appropriate
directories (usually /usr/local/bin and /usr/local/share/man/man1,
respecively).

For further details regarding `configure' and `make', see the INSTALL file.

Usage
=====

A list of options that each program accepts can be displayed by running it
with the --help option:

   qmv --help
   qcp --help
   imv --help
   icp --help
   deurlname --help

Please consult the manual page for each program for full usage information.
These documents can usually be viewed this way:

   man ./qcmd.1

or

   man -l qcmd.1

To rename a file using imv, use

   imv FILENAME

To rename files in the current directory using qmv, use

   qmv

or use the interactive mode of qmv:

   qmv -i

Enable the simulation mode of qmv by specifying the --dummy option. I use
imv and qmv in my user menu in Midnight Commander. The following lines are
in my ~/.mc/menu file:

     q	qmv
   	qmv .

     Q	qmv wide
   	qmv -owidth=120 .

     r	mv
   	imv %f

Homepage
========

The latest version of the file renaming utilities can be downloaded from

   http://www.nongnu.org/renameutils/

Feedback
========

The author of the file renaming utilities and this document, Oskar
Liljeblad, can be reached via email:

   oskar@osk.mine.nu (mailto:oskar@osk.mine.nu)

Please send bug reports, suggestions, ideas or comments in general to me.

Known bugs
==========

The imv program defaults to -i (--interactive) unlike mv which defaults to
-f (--force). This means that imv will ask before overwriting files.

The imv program trims the edited file name. This means that the destination
file name cannot have leading or trailing whitespace.

If you use alias mv=imv then you will only get the imv help and version
number with mv --help and mv --version.

Possible things to do
=====================

Please see the TODO document.

-