FRENUM(1)

NAME
frenum - renumbers multiple file names

SYNOPSIS
frenum [options] [file...]

DESCRIPTION
frenum renumbers the file names supplied according to the specified options. The default action is to number the files starting from 1, which is probably not what the average user really wants; which means that some options must usually be specified. The starting number, the increment, the zero-filled field width, any required prefix or suffix, can all be specified. If the existing file name's alpha component is required to be retained, that can be specified, including truncation point and any case modifications (upper, lower, initial-caps) that might be desired. No files will be overwritten; if there is a name clash, frenum will gracefully re-compute the next file name in the series. If no files are found on the command line, the standard input is read. To allow usage in a pipeline initiated with find, all non-regular files are ignored without error. The pathname up to the last slash is also left as-is; the transformation rules are applied only to the file name. For example, to renumber files in directory "img" to preserve the first four characters, initial-uppercased, use a three-digit number and change the extension to ".jpg":

  find img -print | frenum --Trunc 4 --Case i --Width 3 -.jpg

If the original name was:            The result would be:
     img/ASHGROVE.JPEG       -->       img/Ashg001.jpg
     img/ASIMOV_39.JPG       -->       img/Asim002.jpg
     img/woodland2003.jpeg   -->       img/Wood003.jpg
     img/woodland99.jpeg     -->       img/Wood004.jpg
     img/xenia.jfif          -->       img/Xeni005.jpg

To do the same thing, but begin numbering at 100 in increments of 10:

  find img -print | frenum -t4 -ci -w3 -.jpg -b100 -n10

OPTIONS

-n, --Num[ber] nn
    Increment is nn, discard original name (default is 1). Use -n0 to turn off numbering; file name clashes may result.

-b, --Begin nn
    Start with nn (otherwise defaults to 1).

-w, --Width nn
    Zero-filled field width. This really must be given, since an unformatted numeric file name is really ugly. The maximum width is 10 and the minimum is -20. If a negative width is specified, it is taken as the fixed width of the entire file name (including all prefixes, but not including any explicit extension or suffix). Consider the following examples:

      Original Name        Using "-w4"         Using "-w-8"
      -------------        ------------        ------------
      Jack                 Jack0001            Jack0001
      Jem                  Jem0002             Jem00002
      Jeremy               Jeremy0003          Jeremy03
      Julianne             Julianne0004        Juliann4

    Note that the name is truncated to acommodate the number.

-t, --Trunc[ate] nn
    Delete from nn or first non-alpha. If you want to preserve all alphas, you could use -t99 or something like that.

-x, --Skip nn
    Drop the first nn characters of the file name before applying any other rules. The --Skip and --Trunc options together define a segment (substring) of the original file name.

-p, --Prefix aaa
    Add a string in front. Usually not done in conjunction with the --Truncate option, but you can if you want to.

-s, --Suffix aaa
    Add a string at the end. This is in addition to any existing suffix or extension. If you want to replace the existing extension, don't use this; use --Extension instead.

-., --Extension aaa
    Suffix starting with a dot. If there is already an extension, it will be replaced. If there are multiple extensions, the rearmost one will be replaced.

-/, --Translate aaa/bbb
    Translate characters. Each matching character in the string aaa is replaced by its same-position character in bbb. The two strings must be of equal length. For example, using the command:

      frenum -t99 -/aei/xyz -w-7

         alpha      -->      xlphx01
         beta       -->      bytx002
         phi        -->      phz0003

    This translation applies only to existing components of the file name, not to any supplied prefixes or suffixes.

-c, --Case [ lower | Upper | initial-caps ]
    Adjust the case of the alphabetic portion of the file name.

-o, --Opt[imal]
    Permit only alphanumerics, -, +, ., and _. Use this option if your file names have got rather garbaged; you'll end up with nice clean names with no nasty characters in them. If you want only to optimize the file names and nothing else, use:

      frenum --Optimal --Number 0

    and perhaps --Case initial-caps to beautify a bit more.

-z, --Zap[-Numerics]
    Delete all non-alphas. You would use this to remove numerics interspersed with alphas in the file names. If you're simply renumbering, of course, you won't need this; you will probably use --Trunc.

-d, --Dirs[-Also]
    Don't ignore directory names. Use with caution, specially if you are also piping in the contents of directories. It is possible that a directory name might be changed, and a later pathname specifies a directory which no longer exists. This is best used interactively with wildcards.

-l, --List[-Only]
    Don't do it, just report what would happen. Strongly recommended the first time you prepare a command line.

-k, --Keep-Going
    Don't stop on file errors, go to next file name. This will be needed only if the numbering option is turned off, or you are trying to renumber files some of which you don't own.

-v, --Ver[sion]
    Shows the version of the program and its creation date.

-h, --Help
    Shows a help page which is a summary of the options. If you include "2" as a parameter, i.e. "-h2", a second help page gives a quick summary of other useful information.

-u, --Verbose
    The opposite of --Quiet. Only needed if you want verbosity in a pipeline; it's the default when output is to the screen.

-q, --Quiet, --Silent
    Don't give chatty status messages. However, each renumbered file will still be echoed to the standard output, and errors are sent to the error output. This is the default if output is to a pipe. It is ignored if you specify the --List option.

-, --Standard-input
    Read stdin for more file names. This is not normally necessary unless at least one file name has already been specified on the command line.

ENVIRONMENT
No environment variables are used.

SEE ALSO
mv(1)

DIAGNOSTICS
If you give an invalid option it may give you some feedback. However, use of the --List option is strongly recommended to avoid unexpected results. Specific messages include:

  Unrecognized option "x", possibly meant to be "y"

You have probably mis-spelled a long option.

  "Case" option argument is invalid

The argument to --Case must be one of "u", "l", or "i".

  "Translate" option argument has no replacement section
  "Translate" option's find and replace parts of different size

Translate requires an argument which is two charsets separated by a slash.

  Width value is not in the allowed range

Field too fat.

  Numeric option x has improper value y

We're expecting a number. Use digits. And not too many of them.

  Number too large for field

You asked for a fixed-width name, but the digits of the number alone are bigger than that. Give it more width or reduce the number.

BUGS
Report bugs to: Renuk de Silva (renuk007@users.sourceforge.net). No new or interesting bugs have been reported yet.

COPYRIGHT
Copyright (C) 2008 by Renuk de Silva. Modifications copyright (C) 2025-2026 by Brian Lindholm. This program is free software; you can use it, 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, 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.