fix-digits.1

.TH FIX-DIGITS 1 2024 FIX-DIGITS\ 0.2.2

.SH NAME

fix-digits \- adjust numbers in filenames

.SH SYNOPSIS

.SY
\fBfix-digits\fR [<options>] [<file> ...]
.YS

.SH DESCRIPTION

\fBfix-digits\fR allows the user to perform various operations on numbered files that involve modifying the part of the filename containing the number. Those operations include zero-padding (\fB-z, --zero-pad\fR), reordering (\fB-o, --reorder\fR), incrementing or decrementing (\fB-s, --shift\fR), and removing gaps (\fB-g, --preserve-gaps\fR).

Here is an example of zero-padding numbered files:

.RS
.TS
l c l .
1-name.ext	->	001-name.ext
2-name.ext	->	002-name.ext
3-name.ext	->	003-name.ext
4-name.ext	->	004-name.ext
5-name.ext	->	005-name.ext
6-name.ext	->	006-name.ext
7-name.ext	->	007-name.ext
8-name.ext	->	008-name.ext
9-name.ext	->	009-name.ext
10-name.ext	->	010-name.ext
11-name.ext	->	011-name.ext
12-name.ext	->	012-name.ext
\...
99-name.ext	->	099-name.ext
100-name.ext	->	100-name.ext
.TE
.RE

This ensures that the files are always sorted in the intended numerical order \- whether or not a given program supports a sorting method that would allow for such a sort order without the numbers in filenames having leading zeros added.

Renaming is done by matching parts of the filenames that immediately precede and follow the numeric part, with regular expressions. This allows \fBfix-digits\fR to identify the part that contains the numbers, and rename the files. These regular expressions are set by using the \fB-b, --match-before\fR and \fB-a, --match-after\fR options.

Reordering files is done by rearranging lines in a reorder file. A reorder file gets generated and opened in a text editor when \fBfix-digits\fR is run with \fB-o, --reorder\fR. Each line in the reorder file represents an input file. Rearranging the lines in the desired order, saving the reorder file, and closing the text editor will result in the numbers in filenames being adjusted according to the order specified in the reorder file.

For more information on other operations, see OPTIONS below.

By default, \fBfix-digits\fR does not rename the files, but only simulates the renaming, providing the user with a preview of the changes to be made. The actual renaming can then be done by running \fBfix-digits\fR with \fB-r, --run\fR set.

If no <file> argument is passed to \fBfix-digits\fR, it performs the operation on all files in the current working directory (except for the files whose names start with a dot). This is equivalent to running `fix-digits [<options>] *` (with `shopt dotglob` set to `off`).

Files that don't match regular expressions set with \fB-b, --match-before\fR and \fB-a, --match-after\fR are ignored.

If a file with the same name already exists, it will not be renamed, a warning message will appear, and \fBfix-digits\fR will exit with exit status \fB2\fR.

.SH OPTIONS

.SS Passing arguments to options

Enhanced \fBgetopt\fR syntax applies when passing options. There is one important point to highlight when it comes to passing options with required vs optional arguments.

In case of a short option, if an option takes a *required* argument, the argument may be written as a separate parameter, *or* directly after the option character. If an option takes an *optional* argument, however, the argument *must* be written directly after the option character.

In case of a long option, if an option takes a *required* argument, the argument may be written as a separate parameter, *or* directly after the option name, separated by an equals sign (`=`). If an option takes an *optional* argument, however, the argument *must* be writtent directly after the option name, separated by an equals sign (`=`).

.TS
tab(|);
l l l .
|Short option|Long option
Required argument|\fB-o\fR <value>|\fB--option\fR <value>
|\fB-o\fR<value>|\fB--option\fR=<value>
Optional argument|\fB-o\fR[<value>]|\fB--option\fR[=<value>]
.TE

Options that take optional arguments can be recognized in the options list below by their <value> and the preceding equals sign being enclosed in square brackets:

.EX
\fB-o, --option\fR[=<value>]
.EE

.SS General

.TP
.B -r, --run
Rename the files instead of simulating the renaming.

.TP
.B -R, --no-run
Do not rename the files, only simulate the renaming. This is the default.

.TP
.B -p, --print-cmd
Print a preview of the commands to be executed.

.TP
.B -P, --no-print-cmd
Do not print a preview of the commands to be executed. This is the default.

.TP
.B -b, --match-before\fR=<regex>
Regular expression to match the part of the filenames immediately preceding the numbers. Note that matching is performed only on the basename of the file (i.e. not on the path that might precede the filename).

The default value is `^`.

Also see REGULAR EXPESSIONS below.

.TP
.B -a, --match-after\fR=<regex>
Regular expression to match the part of the filenames immediately following the numbers.

The default value is `-.*$`.

Also see REGULAR EXPESSIONS below.

.TP
.B --match-sign
Match minus (-) signs preceding numbers in filenames.

.TP
.B --no-match-sign
Do not match minus (-) signs preceding numbers in filenames. This is the default.

.TP
.B -g, --preserve-gaps
Preserve gaps in numbering of files. This is the default.

.TP
.B -G, --no-preserve-gaps
Do not preserve gaps in numbering of files.

.TP
.B -s, --shift\fR=[+|-]<integer>
Increment or decrement numbers in filenames by a specified value. The default value is `0`.

.TP
.B -z, --zero-pad\fR[={<integer>|auto}]
Add leading zeros to numbers in filenames. The default value is `auto`.

The value can be an integer greater than or equal to 0, `auto`, or no value. Omitting the value is equivalent to passing `auto`.

.TP
.B -Z, --no-zero-pad
Do not add leading zeros to numbers in filenames. Equivalent to \fB-z, --zero-pad\fR set to `0`.

.TP
.B -n, --zero-pad-normalize
Remove existing leading zeros from numbers in filenames.

.TP
.B -N, --zero-pad-no-normalize
Do not remove existing leading zeros from numbers in filenames. This is the default.

.SS Reordering

.TP
.B -o, --reorder
Change the order of files by modifying numbers in their names.

Also see REORDER FILE.

.TP
.B -O, --no-reorder
Do not change the order of files by modifying numbers in their names. This is the default.

.TP
.B -f, --reorder-file=<path>
A custom path to a reorder file.

If not set, a temporary file in the cache directory gets created. See FILES for more information.

.TP
.B -k, --reorder-file-keep-temporary\fR[={always|auto|never}]
Whether or when to keep the temporary reorder file after an operation finishes. The default value is `auto`.

NB: This option does not apply when a path to a reorder file is set with \fB-f, --reorder-file\fR. Such a file never gets automatically deleted. See \fB-f, --reorder-file\fR for more information.

.RS
.TP
[always]
Always keep the reorder file.
.TP
auto (default)
Keep the reorder file when simulating the operation (\fB-R, --no-run\fR), but delete it when actually renaming the files (\fB-r, --run\fR).
.TP
never
Never keep the reorder file.
.RE

.TP
.B -K, --reorder-file-no-keep-temporary
Do not keep the reorder file after an operation finishes. Equivalent to \fB-k, --reorder-file-keep-temporary\fR set to `never`.

.TP
.B -x, --reorder-file-clear-temporary\fR[={always|auto|prompt|never}]
Whether or when to delete the temporary reorder file before beginning an operation. The default value is `never`.

NB: This option does not apply when a path to a reorder file is set with \fB-f, --reorder-file\fR. Such a file never gets automatically deleted. See \fB-f, --reorder-file\fR for more information.

If this option is used while \fB-o, --reorder\fR is not set, the file renaming operation does not run, and only attempting to delete the temporary reorder file takes place.

.RS
.TP
[always]
Always delete the reorder file.
.TP
auto (default)
Delete the reorder file if it does not match the current file set; otherwise, keep it. 
.TP
prompt
Like `auto`, but ask what to do if the reorder file does not match the current file set. Provides an option to view the file before making a decision.
.TP
never
Never delete the reorder file.
.RE

.TP
.B -X, --reorder-file-no-clear-temporary
Do not delete the reorder file before beginning an operation. Equivalent to \fB-k, --reorder-file-clear-temporary\fR set to `never`.

.TP
.B -e, --reorder-file-edit\fR[={always|auto|never}]
Whether or when to edit the reorder file. The default value is `auto`.

.RS
.TP
[always]
Always edit the reorder file.
.TP
auto (default)
Edit the reorder file when generating it for the first time, but do not edit, and only load it if it already existed.
.TP
never
Never edit the reorder file.
.RE

.TP
.B -E, --reorder-file-no-edit
Do not edit the reorder file. Equivalent to \fB-k, --reorder-file-edit\fR set to `never`.

.TP
.B -m, --reorder-file-gaps-compact
Represent gaps with ranges in reorder file instead of one number per line.

.TP
.B -M, --reorder-file-gaps-no-compact
Do not represent gaps with ranges in reorder file, but one number per line. This is the default.

.TP
.B --editor\fR=<value>
A text editor to use for reordering files with \fB-o, --reorder\fR. The default value depends on the values of VISUAL and EDITOR environment variables. If neither is set, the default value is `nano`.

See ENVIRONMENT for more information.

.SS Other

.TP
.B -c, --color
Colorize the output. This is the default.

.TP
.B -C, --no-color
Disable colorization of the output.

.TP
.B -h, --help
Print help.

.TP
.B -V, --version
Print version information.

.SH EXIT STATUS

.TS
l l .
\fB0\fR	Success. No errors have occured.
\fB1\fR	A general error has occured.
\fB2\fR	Renaming failed. File with the same name already exists.
\fB3\fR	Reorder file is invalid.
.TE

.SH ENVIRONMENT

.SS VISUAL / EDITOR

The values of \fIVISUAL\fR and \fIEDITOR\fR environment variables are checked if \fB--editor\fR is left at its default value. \fB--editor\fR determines the text editor to use for reordering files with \fB-o, --reorder.

\fIVISUAL\fR is evaluated first. If not set, then \fIEDITOR\fR is evaluated. See \fB--editor\fR for more information.

.SH REGULAR EXPRESSIONS

The regular expressions used are POSIX Extended Regular Expressions as used in Bash, in the `[[ <value> =~ <regex> ]]` construct. More information on POSIX Regular Expressions can be found at <https://www.gnu.org/software/grep/manual/html_node/Regular-Expressions.html>.

.SH REORDER FILE

A reorder file is a plain text file used to represent a new order of files according to which the part of the filenames that contains a number should be changed. See \fB-o, --reorder\fR, and \fB--reorder-file-*\fR options for more information.

Each line in a reorder file can be a filename, a gap specification, or a comment. Generate a reorder file by running \fBfix-digits\fR with the \fB-o, --reorder\fR option. Rearrange the lines in the file to specify a new order.

The file lines contain the original name of the file. To move a file to a new position, only move the line without modifying the filename.

If a filename contains a newline, it is represented as `\\n` in the reorder file. If a filename contains a backslash (`\\`), it is represented with a double backslash (`\\\\`) in the reorder line. If a filename starts with a number sign (`#`), it must also be escaped with a backslash: `\\#`.

A gap specification is a special comment line. Its format is `# gap: <start>[-<end>]` where <start> and <end> are integers. Whitespace is optional. The \fB-m, --reorder-file-gaps-compact\fR option controls whether to generate gap specifications with one number per line (`# gap: <start>`), or in the range format (`# gap: <start>-<end>`).

Gaps behave just like filenames in terms of the effect that rearranging lines has on the new numbers in filenames. For example, you can put a file between two gaps, and the order will be respected.

All gaps in the numerical sequence formed by the numbers in filenames must be specified in the reorder file. If that is not the case, a reorder file validation check will fail. If filenames in the reorder file do not match the original filenames, the validation check will fail as well. When this validation check fails, \fBfix-digits\fR exits with exit status 3, and no renaming of files takes place. Error messages specify what the problem was.

Any line that starts with a number sign (`#`), and does not match the gap specification format is a comment line.

.SH FILES

A configuration file can be used to set default options.

The configuration file's location is \fI$XDG_CONFIG_HOME/fix-digits/config.bash\fR. If \fIXDG_CONFIG_HOME\fR is not set, it defaults to \fI~/.config\fR.

A temporary reorder file that is generated when using \fB-o, --reorder\fR is stored in a cache directory.

The cache directory's location is \fI$XDG_CACHE_HOME/fix-digits\fR. If \fIXDG_CACHE_HOME\fR is not set, it defaults to \fI~/.cache\fR.

.SH BUGS

Renaming identically numbered files currently does not work when reordering (\fB-o, --reorder\fR). To work around this, split the file set into batches in which numbers do not repeat, and reorder each batch separately.

.SH AUTHOR

Alex Rogers <https://github.com/linguisticmind>

.SH HOMEPAGE

<https://github.com/linguisticmind/fix-digits>

.SH COPYRIGHT

Copyright © 2024 Alex Rogers. License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.